# Documentation: how should names be qualified?

**URL:** <https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529>\
**Category:** Internals & Design\
**Tags:** documentation\
**Created:** [October 10, 2022, 4:30pm UTC](https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529 "2022-10-10T16:30:45Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![matthias314](https://avatars.discourse-cdn.com/v4/letter/m/a88e4f/32.png) [@matthias314](https://discourse.julialang.org/u/matthias314)\
**Post date:** [October 10, 2022, 4:30pm UTC](https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529/1 "2022-10-10T16:30:45Z")

</div>

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

```julia
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

```julia
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?

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [October 11, 2022, 1:53am UTC](https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529/2 "2022-10-11T01:53:16Z")

</div>

[The Julia Docs](https://docs.julialang.org/en/v1/manual/style-guide/) 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](https://github.com/invenia/BlueStyle) and [Yas](https://github.com/jrevels/YASGuide). 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.

---

<div class="post-metadata">

**Author:** ![matthias314](https://avatars.discourse-cdn.com/v4/letter/m/a88e4f/32.png) [@matthias314](https://discourse.julialang.org/u/matthias314)\
**Post date:** [October 11, 2022, 2:14am UTC](https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529/3 "2022-10-11T02:14:22Z")

</div>

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,

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

```

or rather as

```julia
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

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

```

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [October 11, 2022, 1:47pm UTC](https://discourse.julialang.org/t/documentation-how-should-names-be-qualified/88529/4 "2022-10-11T13:47:59Z")

</div>

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!