GitHub

Docstring dictionaries: private API

src/01_Base/ implements the most basal symbols used in PortfolioOptimisers.jl. One file per concept: the docstring dictionaries, the type roots, the pretty-show macro, the ScopedConfig holders, the load-time preferences, the message builders, the error hierarchy, the type aliases, the observation weights, the assert_* family, VecScalar, the NormError family, the Kaniadakis logarithm, the partial-fit state seam and the sample buffer the online step folds into.

In order to standardise the documentation we use an arg_dict of terms.

PortfolioOptimisers.arg_dict — Constant
arg_dict

Maps a parameter key to the docstring description of the corresponding argument or field, so that a single description is written once here and interpolated into every docstring that mentions that parameter (via $(arg_dict[key]) for # Arguments entries, or through the derived field_dict for # Fields entries).

Each value has the form $"`name`: description."$, where name is the display name the caller sees and everything after the first : is the prose; field_dict strips the $"`name`: "$ prefix. A few illustrative entries:

:ce   => "`ce`: Covariance estimator.":oow  => "`w`: Optional observation weights vector `observations × 1`, ...":per  => "`pr`: Prior estimator or result.":pler => "`pl`: Network estimator, phylogeny result, clustering estimator, or clustering result.":plsrc => "`pl`: Network estimator or clustering estimator -- a source that refits, never a precomputed result."

The const definition below is the single source of truth; consult it for the full table of keys and descriptions. A key must appear once: unique_key_dict builds the table and refuses a repeat, because a Dict literal drops the earlier entry in silence.

Related

source
PortfolioOptimisers.val_dict — Constant
const val_dict = Dict(:oow => "If `w` is not `nothing`, `!isempty(w)`.")

Validation rules for certain arg_dict terms used in the documentation of PortfolioOptimisers.jl.

:relax is the exception: it is the fixed opening sentence of a ## Relaxation subsection under # JuMP formulation, held here so that the wording cannot drift between docstrings.

Related

source
PortfolioOptimisers.math_dict — Constant
math_dict

Dictionary of mathematical notation descriptions used for docstring interpolation throughout PortfolioOptimisers.jl.

Keys are symbols that identify mathematical variables or subscripts; values are LaTeX-formatted strings suitable for embedding in docstrings.

A key owns a definition, not a glyph: one glyph carries different quantities in different families, so a second quantity on the same glyph takes its own key under its own symbol.

Related

source
PortfolioOptimisers.err_name_dict — Constant
err_name_dict

Maps high-order-moment argument keys to the domain noun used in error messages, so a message names what the caller supplied (e.g. cokurtosis) rather than the bare field symbol. The symbol itself is appended at the call site, giving messages like $cokurtosis (`kt`) cannot be empty$.

Related

source
PortfolioOptimisers.ref_dict — Constant
ref_dict

Maps a key of docs/src/References.bib to the formatted # References bullet for that work, so the reference text is written once here and interpolated wherever a docstring cites it.

Each value is a complete bullet body: the citation marker for the key, followed by the reference in the style DocumenterCitations renders in the bibliography. A citing docstring writes the whole bullet as one interpolation of this table and never pastes the reference prose inline. A pasted copy drifts from the entry in References.bib and from the other copies of itself: before this table existed, gerber2025squeezing was pasted 31 times and mlp1 13 times.

The const definition below is the single source of truth. A key must appear once: unique_key_dict builds the table and refuses a repeat.

Related

source
PortfolioOptimisers.unique_key_dict — Function
unique_key_dict(
    name::Symbol,
    pairs::Pair{Symbol, <:AbstractString}...
) -> Dict{Symbol, String}

Build a documentation dictionary from pairs, and throw if a key appears more than once.

A Dict literal is last-wins, so a repeated key drops the earlier entry with no warning and makes its prose unreachable. This constructor is the guard against that: it fails at load time and names both descriptions, so the duplicate is visible instead of silent.

Algorithm

  1. Start dict empty.
  2. For each pair, in the order the caller wrote it, raise an ArgumentError when dict already holds the key. The message names name, the key, and both descriptions.
  3. Otherwise store the pair in dict.

Arguments

  • name::Symbol: Name of the dictionary under construction, used in the error message.
  • pairs: The key-description pairs, in the order they are written.

Validation

  • Each key appears exactly once. A repeat raises an ArgumentError naming name, the key, and both descriptions.

Returns

  • dict::Dict{Symbol, String}: The built table.

Related

source