Documentation: how should names be qualified?

Internals & Design
1

There seem to be different styles in the documentation regarding qualified names. For example, the docstring for Threads.foreach describes the functions as

Threads.foreach(f, channel::Channel;
                schedule::Threads.AbstractSchedule=Threads.FairSchedule(),
                ntasks=Threads.nthreads())

Here all names are qualified in the way one has to use them without additional using and import statements. On the other hand, the description of Base.Order.ord only says

ord(lt, by, rev::Union{Bool, Nothing}, order::Ordering=Forward)

although by default one has to use Base.Order.ord, Base.Order.Ordering and Base.Order.Forward.
Using all necessary qualifications is more precise and probably helps readers avoid mistakes, but at the same time it makes the documentation more clumsy. Is there any style guide on this for the Julia documentation?

2

The Julia Docs have a style guide. The answer to your question is at least partially covered in the first header, “Avoid writing overly-specific types”.

There are also other style guides Blue and Yas. They differ on many points but agree about adding type annotations to function arguments.

The preference toward untyped functions is because of multiple dispatch. Having untyped arguments acts as the default version of the function. Then, if you want to write specific implementations for certain types of parameters, you can do so. This is especially important for code that’s going into Base or a package because you want to let the user pass in custom types or add their own dispatching.

However, in my personal code, I depart from the style guide. I prefer to type my parameters as much as possible so that my code throws a MethodError if my assumptions about the types I’m working with are wrong!

Edit: I also like typing my functions because then I can assure my tests have full coverage of the input space.

3

My question was not about typed versus untyped arguments. It was about how to refer to function names and argument types (if they are defined) in docstrings.
For instance, should one display the function ord as as it’s currently done,

ord(lt, by, rev::Union{Bool, Nothing}, order::Ordering=Forward)

or rather as

Base.Order.ord(lt, by, rev::Union{Bool, Nothing}, order::Base.Order.Ordering=Base.Order.Forward)

since Base doesn’t export the submodule Order. I think it helps the reader to indicate which names are defined in Base and which not, but the resulting docstring is harder to read. Maybe there is some other way that strikes a better balance between precision and readability. I could think of

using Base.Order: ord, Ordering, Forward
ord(lt, by, rev::Union{Bool, Nothing}, order::Ordering=Forward)
1 Like
4

Ooh, I was obviously not reading closely. I’m sorry about that.

I don’t have any great insights about best practice on this one. I hope someone with better visibility into package dev can help!