Some thoughts on improving basic function documentation

General Usage
41

One of the examples does show this, but if you feel that it can be clearer then open an issue at
Issues · JuliaLang/julia · GitHub with your exact proposed change (If you can, then a pull request would be better).

42

Maybe by adding a comment to it like

julia> 7 > 3 > 1 # equivalent to 7 > 3 && 3 > 1
  true
43

This chaining is missing in the doc of <

1 Like
44

So it is, maybe should add a corresponding

julia> 1 < 3 < 7 # equivalent to 1 < 3 && 3 < 7
  true
45 
mutable struct Car
odometer::Float64
end
cars = [Car(rand(4)...) for _ in 1:5]
Base.isless(c1::Car,c2::Car) = c1.odometer < c2.odometer
findmin(cars)

The above code is really a Julia gem.[got from stackoverflow]. Why not it is included in the Julia doc of isless.

julia> isless([1,2],[1,3])
true

julia> isless([1,2],[1,-1])
false

This can also be included I think

46

Doesn’t work, maybe

cars = [Car(rand()) for _ in 1:5]

but I would prefer

cars = Car.(rand(5))

The docs state that if you define Base.isless then you should also define Base.isequal, so make sure to do that to make the example 100% correct.

Good idea and I think that it could even clarify things an extra amount with a third example: isless([0,2],[1,-1])

I see that the 1.9 docstring for isless(A::AbstractVector, B::AbstractVector) uses capitals for the parameter names which is against Julia naming convention, so this should also be changed to isless(a::AbstractVector, b::AbstractVector)

2 Likes
47

Update: GitHub - tecosaur/CheckDoc.jl: Documentation linting is now public :grinning: (though currently unregistered).

2 Likes
48

Reported an issue:

49

I am also following up here to say that the Documentation tutorial is up on JuliaLang youtube channel and it indeed tries to establish a standard form for docstrings:

4 Likes
50

I vaguely remember having seen admonitions in the Julia manual that Description, Arguments, etc. should be level-one headings. I think GD uses second-level. Are there any arguments for one over the other?

1 Like
51

I don’t know what GD means, but I use level 2 headings. My reason was that in the rendered pages in Documenter’s HTML output, which is the default setup for most packages, level 1 headers in docstrings were very large. I preferred them just a bit toned down so I went with level 2 markdown headers in docstrings.

52

GD is you :wink: