That said, documentation shouldn’t assume prior experience in other languages
As someone not coming from a C background I had stumbled onto the @sprintf documentation but have never used it simply because I have no idea how the formatting works. A link to somewhere explaining or an explanation of what “%0.5f” means (and the other syntax the macro takes) would be helpful here.
Quoting from the docstring of @printf
For a systematic specification of the format, see here.
Although I’d argue we shouldn’t use here links, so that’s another low-hanging fruit to take.
Ah excellent! I never saw that link under the @printf docs instead of the @sprintf ones. Thank you!
While I wholeheartedly support and intend to contribute to this initiative to improve the reference documentation, I think that we first need to discuss what good reference documentation of a function should include, because I believe that consistency is very important there. Specifically, in your repo, you write:
What Does Good Documentation Look?
Non-exhaustively, it’s useful for a function to contain:
- Description: A 1-3 sentence summary of what the function/method does.
- Usage: A theoretical call to the function/method with all arguments.
- Arguments: A list of all arguments, their types and their meaning.
- Returned Values: A list of all returned values, their types and their meaning.
- Details: More details about how the function/method works, how it should be called, how it is implemented, how its returned values are meant to be used, etc.
- References: Bibliographic information
- See Also: Other documentation sections that are relevant and text explaining their relationship to the current function/method.
- Examples: Specific examples that show what using the function/method in practice would look like.
As far as I can tell (almost) no function in the documentation right now satistfies these eight points. For example, let’s look at the reference for arguably the most used function: Base.:+.
Right now, it includes only the methods for dt::Date + t::Time -> DateTime and +(x, y...). It says nothing about +(x::T, y::T) where T<:Union{Int128, Int16, Int32, Int64, Int8, UInt128, UInt16, UInt32, UInt64, UInt8} which is probably the most used. More generally, very rarely the function documentation explicitly specifies the return type of the function or its meaning. And for a reason, since that would e.g. entail that all 100+ methods of + have to be mentioned.
What I want to say is this: let’s first discuss what a good reference would look like, with simple multimethod functions like + in mind. Then, a list of functions can be made whose docs are not up that standard. If you all agree with this, I would like to contribute to creating that list and writing the references (although my git skills are not so good).
(On the short term, we should probably not put the dt::Date + t::Time -> DateTime method of + as the first entry in the documentation of the maths section)