# What should go in module docstrings?

**URL:** <https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742>\
**Category:** General Usage\
**Created:** [January 12, 2024, 7:19pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742 "2024-01-12T19:19:37Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![jar1](https://avatars.discourse-cdn.com/v4/letter/j/c0e974/32.png) [@jar1](https://discourse.julialang.org/u/jar1)\
**Post date:** [January 12, 2024, 7:19pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/1 "2024-01-12T19:19:37Z")

</div>

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](https://github.com/JuliaLang/julia/issues/52725#issuecomment-1889747971).

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?

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [January 12, 2024, 7:35pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/2 "2024-01-12T19:35:02Z")

</div>

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.

> <https://github.com/JuliaLang/julia/blob/5b6a94da5af35a4aa91759cac2f8db7669a6ec2a/stdlib/REPL/src/REPL.jl#L4>

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

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [January 12, 2024, 8:29pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/3 "2024-01-12T20:29:27Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![stevengj](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/stevengj/32/71_2.png) [@stevengj](https://discourse.julialang.org/u/stevengj)\
**Post date:** [January 12, 2024, 9:18pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/4 "2024-01-12T21:18:25Z")

</div>

> [@ericphanson](#):
>
> So I would only include one if it is more informative than the readme.

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.

---

<div class="post-metadata">

**Author:** ![ericphanson](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/ericphanson/32/215186_2.png) [@ericphanson](https://discourse.julialang.org/u/ericphanson)\
**Post date:** [January 12, 2024, 9:38pm UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/5 "2024-01-12T21:38:27Z")

</div>

> [@stevengj](#):
>
> 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.

Yes, but I have seen module docstrings written like

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

> [@stevengj](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![savq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/savq/32/22063_2.png) [@savq](https://discourse.julialang.org/u/savq)\
**Post date:** [January 13, 2024, 12:21am UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/6 "2024-01-13T00:21:20Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![jar1](https://avatars.discourse-cdn.com/v4/letter/j/c0e974/32.png) [@jar1](https://discourse.julialang.org/u/jar1)\
**Post date:** [January 13, 2024, 12:37am UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/7 "2024-01-13T00:37:12Z")

</div>

> [@savq](#):
>
> Hopefully this will improve with `public`, but I think it’s important that this information is explicit somewhere.

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

---

<div class="post-metadata">

**Author:** ![savq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/savq/32/22063_2.png) [@savq](https://discourse.julialang.org/u/savq)\
**Post date:** [January 13, 2024, 1:04am UTC](https://discourse.julialang.org/t/what-should-go-in-module-docstrings/108742/8 "2024-01-13T01:04:04Z")

</div>

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-repl
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(…)`”.