PortfolioOptimisers.jl julia-docstrings.instructions.md

Docstring and Documentation Guidelines for PortfolioOptimisers.jl

General Guidelines

• Look at how other docstrings are implemented and follow similar patterns.
• Write clear and concise documentation.
• Use consistent terminology and style.
• Include code examples where applicable.
• All public types, functions, and macros must have docstrings.
• Scope: src/**/*.jl, ext/**/*.jl and docs/**/*.md. A package extension in ext/ is documented on the same terms as src/.
• An extension documents the names it declares itself, and nothing else. An extension implements a seam that src/ declares, and the declaration carries the docstring, the # References section and the API-page entry. So a method of a function declared in src/ gets no docstring of its own in ext/, and the extension's own module, constants, types and macros each get one. Write a citation in the src/ declaration, where the API page that renders it carries the bibliography block; an extension needs neither an API page nor a bibliography block of its own. test/test_26_docs.jl gates this per file, through the swept flag in sweep/manifest.toml.

The summary sentence (load-bearing — read this before writing a type docstring)

Every type docstring opens with $(DocStringExtensions.TYPEDEF), a blank line, then a summary paragraph. The first sentence of that paragraph is extracted verbatim and rendered as the type's one-line description in the Capability Catalogue (ADR 0040), which is the user-facing inventory of everything the package can do.

This is a real contract, not a convention that merely happens to hold. It is what lets the catalogue carry prose without keeping a second, drifting copy of every description. If a docstring loses its summary paragraph, the docs build fails with an error naming the type.

Write the first sentence so it stands alone in a bullet list:

• Lead with what it does, in the active voice. Denoises by setting the smallest \num_factors` eigenvalues to zero.— notA denoising algorithm that sets...`.
• Keep it under ~120 characters. If the idea needs more, put a crisp first sentence and move the detail into a second sentence, which still renders on the API page but not in the catalogue. Do not compress by deleting information.
• Avoid filler openers: A flexible container type for..., A concrete estimator type for.... They cost a line and say nothing.
• **Do not append in \PortfolioOptimisers.jl`.** Every docstring in the package is inPortfolioOptimisers.jl`.
• Do not put @ref links in the first sentence. The catalogue appends the type's own links after the description, so a link in the summary renders twice. Put cross-references in a second sentence or in # Related.
• Do not open with a display formula. Inline maths is fine; a full $...$ equation belongs in # Mathematical definition.
• Never leave a bare _ outside a code span. Markdown reads _ as emphasis and will pair it with the underscore inside a neighbouring `snake_case` link, eating both and destroying the link. (f_μ vector) sitting next to [`plot_factor_mu`](@ref) rendered as (fμ vector … [`plotfactor_ — a dead link that Documenter cannot resolve and the site builder reports only as a single anonymous ./@ref. Write `f_mu` instead.
• Siblings should not all share a prefix. If every algorithm in a family starts Centrality algorithm type for ..., the catalogue shows that boilerplate eight times over. Say what distinguishes each one.