Docstrings

docstrings

Add or normalise Julia docstrings on public symbols (exported types, functions, and constants) across the package source. The goal is complete, consistent API documentation that renders correctly under Documenter.jl and follows whichever docstring convention is already established in the package — typically DocStringExtensions macros such as $(TYPEDEF), $(TYPEDFIELDS), and $(TYPEDSIGNATURES). Completing this skill makes the package's public API fully self-documenting and satisfies any checkdocs requirement in the docs build.

Workflow

Step 1 — Detect the existing convention

Use an Explore subagent to read 2–3 symbols that already have complete docstrings to calibrate style. This avoids consuming the main context window with large file reads. Ask the Explore agent to return the verbatim docstring text for each symbol.

Identify:

• Whether DocStringExtensions macros are used, and which ones ($(TYPEDEF), $(TYPEDFIELDS), $(TYPEDSIGNATURES), $(METHODLIST)).
• How prose is structured relative to macro-generated content (e.g. does prose come before or after $(TYPEDFIELDS)?).
• What field documentation pattern is preferred: inline string literals above each struct field vs. a separate prose block.
• Which format is used for struct docstrings: the old format (an indented type-name header on the first line, no $(TYPEDEF), manual # Constructor section), or the new format (prose only, $(TYPEDEF) for the signature, $(METHODLIST) for constructors). Normalise old-format structs to new-format during Step 3.

This detected baseline becomes the style target for every new or normalised docstring. Do not impose a different convention — match what is already there.

Step 2 — Enumerate candidates

Discover the package name from Project.toml (the name = field). Then run:

grep -nE '^(function |struct |abstract type |mutable struct |const )' src/**/*.jl

Cross-file exports: exported names may be declared in a central module file (e.g. src/PackageName.jl) while the definition lives in a different file. Read the module file for all export statements so you catch every public symbol regardless of where it is defined.

For each exported symbol, check whether a non-empty docstring immediately precedes the definition. Produce a prioritised list:

1. Missing entirely — no docstring at all.
2. Old-format struct — indented type name on first line, no $(TYPEDEF), or redundant manual # Constructor / # Constructors section alongside $(METHODLIST).
3. Empty or stub — only a bare macro line (e.g. $(TYPEDSIGNATURES)) with no prose.
4. Incomplete — prose present but key sections absent (missing # Arguments, # Examples, or field strings not describing semantic role).

Also scan every function in the file for old-style docstrings, regardless of whether it is exported. An old-style docstring is one that uses an indented function-name header (e.g. my_func(arg1, arg2)) and/or an Args: / Arguments: block with the `name` - description format. Convert these to the $(TYPEDSIGNATURES) convention in the same editing pass — the whole file should end up stylistically uniform.

Step 3 — Draft docstrings

For each candidate, write a docstring that matches the detected convention.

Getters and simple accessors

Simple getters for exported process/struct types (e.g. get_prior_mean(p::MyProcess)) are public API and must be documented if exported. A one-line $(TYPEDSIGNATURES) + short prose sentence suffices; no # Arguments or # Examples is needed unless the semantics are non-obvious.

Old-format struct docstrings

If a struct docstring starts with an indented type name (e.g. MyStruct{...}), convert it to the new format:

• Remove the indented type name from the docstring.
• Add $(TYPEDEF) immediately after the opening prose sentence.
• Replace any manual # Constructor or # Constructors section (listing function signatures) with a # Constructors section containing only $(METHODLIST). If $(METHODLIST) is already present alongside the manual list, remove the manual list.
• Preserve any genuine prose that was in the old # Constructor section if it explains non-obvious behaviour; discard boilerplate signature repetition.

Named constructors (factory functions)

$(METHODLIST) only lists methods whose name matches the struct type. Exported functions that build an instance of the struct but carry a different name — factory functions such as constrained_gaussian for ParameterDistribution — are invisible to $(METHODLIST) and must be surfaced manually in the struct docstring.

When such functions exist, add a prose note inside the # Constructors section, immediately before $(METHODLIST):

"""
Structure to hold a parameter distribution, always stored as an array of
distributions internally.

$(TYPEDEF)

# Fields

$(TYPEDFIELDS)

# Constructors

Recommended construction (for most problems) is via the `constrained_gaussian()`
utility (see its own docstring for details and a usage example).

$(METHODLIST)
"""
struct ParameterDistribution
    ...
end

The note should:

• Name the function in backticks.
• Give a one-line hint about when to prefer it over the direct constructor.
• Optionally include a minimal usage snippet if the factory is the primary entry point and no separate # Examples block exists on the factory function itself.

The factory function still needs its own full docstring ($(TYPEDSIGNATURES), # Arguments, # Examples if non-trivial). The struct-level note is a pointer, not a replacement.

Detecting named constructors during Step 2: when enumerating candidates, flag exported functions whose name differs from any type name but whose body or doc clearly returns an instance of a specific struct. Common signals: the function name ends with a domain term (e.g. constrained_gaussian, from_file), its return statement calls the struct constructor directly, or the existing codebase already mentions the relationship somewhere in prose.

Multiple dispatch — one docstring per concept

When a function has multiple dispatch methods, document only the primary user-facing overload and leave all other overloads undocumented. Competing docstrings fragment the rendered API docs and create maintenance burden.

The primary overload is the method whose argument type is the broadest user-facing type — e.g. ParameterDistribution rather than Parameterized or Samples.

Type-parameter specialisations count as overloads. If the same function name is defined for where {FT, P <: MyProcess{FT, TypeA}} and where {FT, P <: MyProcess{FT, TypeB}}, these are two dispatch methods of the same concept. Document only one — typically the first defined, or the more general one — and leave the rest undocumented.

update_ensemble! is a specialised internal update hook called by the framework, not by users directly. It must not be documented even if it is exported.

Old-style function docstrings (all functions, not just exported)

Convert any docstring that uses an indented function-name header or an Args: / Arguments: section to the $(TYPEDSIGNATURES) style, even for internal (non-exported) helpers. The canonical old-style markers are:

• First line indented with spaces: my_func(arg, ...) — replace with $(TYPEDSIGNATURES).
• Argument block labelled Args: or Arguments: with `name` - description lines — replace with a # Arguments section using - `name`: description format.

Doing this in the same pass keeps the file stylistically uniform and prevents old-style docstrings from persisting as invisible technical debt.

General rules

• Use the same macro set as the best-documented symbols already in the package.
• Preserve any inline field string literals already present above struct fields — do not merge them into the struct-level docstring.
• Prose should answer: what does this symbol represent or do, when would a caller use it, and what are the physical units of key quantities.
• Do not duplicate content that macros generate automatically (e.g. do not restate field types when $(TYPEDFIELDS) already renders them).
• Physical quantities: always include units in square brackets, e.g. [m/day].
• For functions with more than two arguments, or whose argument semantics are not obvious from the name alone, add a # Arguments section listing each parameter as - `name`: description [unit if applicable].
• For every non-trivial public function where a minimal runnable example can be written, add a # Examples section with a jldoctest block so Documenter.jl can verify the example stays correct as the code evolves.

Step 4 — Apply edits

When editing files that contain non-ASCII characters (e.g. author names with accented letters like "Garbuno-Iñigo" or "Nüsken"), the file may store characters in Unicode NFD form while the Edit tool normalises to NFC, causing match failures. If an Edit call fails with a "not found" error on a string you can see in the file, use a Python one-liner to apply the replacement with NFD-normalised strings:

python3 - <<'EOF'
import unicodedata, pathlib
p = pathlib.Path("src/MyFile.jl")
text = p.read_text()
old = unicodedata.normalize('NFD', "the old string here")
new = unicodedata.normalize('NFD', "the new string here")
p.write_text(text.replace(old, new, 1))
EOF

After a Python edit, re-read the file before making any further Edit calls to the same file (the Edit tool tracks file state from the last Read).

Step 5 — Sync docs/src/API/ pages

After all source-file edits are applied, update the Documenter.jl API pages so that every exported, documented symbol appears exactly once, organised into logical categories. The goal is that a reader browsing docs/src/API/ sees a complete, non-redundant index of the public API — nothing missing, nothing stale.

5a — Build the source-to-page map

Read docs/make.jl and extract the api array to see which display name maps to which page path (e.g. "Inversion" => "API/Inversion.md"). For each page, read its @meta block to find CurrentModule = .... This tells you which module's exports the page is responsible for.

5b — Collect current @docs entries per page

For each API page, extract every symbol entry listed inside ```@docs ``` blocks. Some entries carry type-signature qualifiers (e.g. get_obs(ekp::EnsembleKalmanProcess)) — track both the raw entry string and the base name (everything before the first ().

5c — Find missing and stale entries

Exported but not defined (phantom exports). Before anything else, check that every exported name actually resolves to a definition — a function, type, or constant — somewhere in the source files of that module. If an exported name has no definition anywhere, it is a phantom export: remove the export statement (or just that name from a multi-name export line) from the source file. Do not add phantom exports to any API page.

Missing from the API. A symbol is missing from a page when it is exported from that page's CurrentModule, its base name does not appear in any @docs block on any API page, and it has a definition in the source. If it lacks a docstring, go back and write one now (following the conventions from Steps 1–3) before adding it to the API page — an undocumented entry in a @docs block will cause the docs build to error. Every exported, defined symbol must end up with a docstring and an API page entry.

Stale API entries. An entry is stale when the base name is no longer exported from the module, or the symbol no longer has a definition in the source.

Run all three checks before making edits so you can see the full diff in one pass.