What should go in module docstrings?

General Usage
1

Currently a community effort is adding docstrings for a lot of names, tracked by @stevengj in Missing docstrings for public/exported symbols · Issue #52725 · JuliaLang/julia · GitHub.

For some ecosystem modules, the module docstring has the same text as the manual section; for others the docstring is just a single phrase.

As a user, what is useful for you to have in a module docstring, accessible in the repl?

1 Like
2
  1. What does the name mean? REPL, what is that?
  2. Brief explanation of the contents.
  3. Example basic usage.
  4. Extended Help or link to manual page

A while back I wrote a docstring for REPL. It was quite minimal, but surprisingly effective. I fiund examples of that minimal code in several blogs or posts.

I think this might be too minimalist, but I would lean towards less than more rather than writing a long description.

1 Like
3

For packages, ?PkgName will pull up the readme if there is no module docstring. So I would only include one if it is more informative than the readme. Otherwise it is annoying to lose that information. (This does not apply to Base or submodules of course).

4

For some packages the README.md file is quite long, essentially a manual, and it often has links to extraneous things like CI status. I would think that for REPL help you’d generally want something more minimalist that fits on a terminal in < 40 lines or so.

Of course, the issue linked above is about fixing cases that have no docstring at all. In such cases, even a couple sentences is a big improvement — it can always be expanded later.

2 Likes
5

Yes, but I have seen module docstrings written like

"""
   MyPackage

The main module for MyPackage.
"""

which can be frustrating (since if they just didn’t spend the time to add that, a more informative result - the README - would appear). I agree README’s aren’t optimal, but they can be pretty good, so I just want folks to know that fallback exists so they only overwrite it if they really have something better.

Yeah, that’s great to do, that issue looks really valuable. I think the term “ecosystem modules” in the OP got me sidetracked to packages.

2 Likes
6

A module’s docstring should describe its guarantees about visibility and stability.

Does the module export a lot of names? Does it not export names at all? Does it use some other convention (like a leading underscore) for private functions?

Hopefully this will improve with public, but I think it’s important that this information is explicit somewhere.

7

What would be the benefit of listing names in the docstring vs just using names(m)?

1 Like
8

Julia confuses “this function is public” with “I want this function to be automatically brought into scope”.

Different packages have different policies around this. For example CSV doesn’t actually export any function so you get:

julia> using CSV

julia> names(CSV)
11-element Vector{Symbol}:
 :CSV
 :InlineString
 :PosLenString
 :String1
 :String127
 :String15
 :String255
 :String3
 :String31
 :String63
 :String7

I’m not saying you should manually write down all the public names, I’m saying the docstring should explicitly say how the authors expect a user to interact with the module.

Again, in the case of CSV, the docstring mentions some methods and gives an example, but AFAIK nowhere in the documentation says “CSV doesn’t export any function, we recommend you call each function a qualified name e.g. CSV.read(…)”.