# Docstrings: Imperative or indicative mood?

**URL:** <https://discourse.julialang.org/t/docstrings-imperative-or-indicative-mood/121524>\
**Category:** Internals & Design\
**Created:** [October 21, 2024, 9:41am UTC](https://discourse.julialang.org/t/docstrings-imperative-or-indicative-mood/121524 "2024-10-21T09:41:44Z")\
**Posts on this page:** 1\
**Showing post:** 8

<div class="post-metadata">

**Author:** ![goerz](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/goerz/32/3269_2.png) [@goerz](https://discourse.julialang.org/u/goerz)\
**Post date:** [October 21, 2024, 12:41pm UTC](https://discourse.julialang.org/t/docstrings-imperative-or-indicative-mood/121524/8 "2024-10-21T12:41:30Z")

</div>

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,

````julia
"""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`](https://juliaquantumcontrol.github.io/QuantumControl.jl/stable/api/reference/#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](https://qucontrol.github.io/krotov/v1.3.0/API/krotov.html#summary) of one of the Python-precedents of `QuantumControl`.

[As far a linters go](https://discourse.julialang.org/t/some-thoughts-on-improving-basic-function-documentation/103546/47), I’d like a linter to be able to enforce that particular style 😉

---

_[View the full topic](https://discourse.julialang.org/t/docstrings-imperative-or-indicative-mood/121524)._