Docstrings: Imperative or indicative mood?

Internals & Design
8

I use a slight variation of the “recommended” style, consisting of three elements:

  • a “title” (a single-sentence summary of the function in imperative style)
  • the code block with the function signature
  • one or more paragraphs in the descriptive style. This continues the code block, as a sentence.

For example,

"""Optimize a quantum control problem.

```julia
result = optimize(
    problem;
    method,  # mandatory keyword argument
    check=true,
    callback=nothing,
    print_iters=true,
    kwargs...
)
```

optimizes towards a solution of given [`problem`](@ref ControlProblem) with
the given `method`, which should be a `Module` implementing the method, …

for QuantumControl.optimize.

One reason is that at some point (maybe with a Documenter plugin), it might be nice to surface the summary of functions, like in the docs of one of the Python-precedents of QuantumControl.

As far a linters go, I’d like a linter to be able to enforce that particular style :wink:

2 Likes