
ID	0018
Class	DOCUMENTATION
Severity	1
Status	blocked
Models	—
Found	2026-09-22 while adding the `ScalarField.*` parameter group
Decision needed	Which style is the convention: keep `@` and correct AGENTS.md, or keep the rule and convert the code?

Evidence

AGENTS.md:280, in the "Standard Doxygen (classes, methods, members)" section, states the rule for method and member documentation:

- Prefer `\` (backslash) style over `@` style for method/member docs.

The surrounding example block at AGENTS.md:263-275 is written in backslash style throughout (\brief, \param[in], \return, \note, \warning, \sa).

No source file follows it. Counted over src/ and include/ at HEAD:

$ grep -rho '\\param' src include | wc -l
0
$ grep -rho '@param' src include | wc -l
314

The @ style is uniform across every hand-written header, including the most recently added ones, for example include/fhsim_environment/EnvironmentProvider.h:84-86:

@param[in] nextWaveState  The new wave field to use.
@param[in] timeNow        Current simulation time.
@param[in] transitionTime Time over which to cross-fade to the new field.

The same file uses @sa, @note and @return. src/environment/ParametricBathymetry.h and src/environment/VisualFlowPlane.h do likewise.

The neighbouring rules in the same AGENTS.md list are followed: /// for single-line member comments, units in brackets, and the coordinate frame stated. Only the backslash rule is contradicted.

Note that the FhSim-specific tags are @-only by construction — @group, <table><tr><th align="left" width="30%"> Name </th> <th align="left" width="10%"> Width </th><th align="left" width="60%"> Description </th></tr>, @addoption, </table> and @issue all appear with @ in AGENTS.md itself (AGENTS.md:255-258) and in every SimObject header. A file following AGENTS.md:280 literally would therefore mix both sigils in the same comment block.

Effect

An agent or contributor reading AGENTS.md as the authority writes \param and produces a file that is inconsistent with every other file in the repository. An agent reading the surrounding code instead writes @param and is inconsistent with the stated rule. Either way the choice is arbitrary and is re-litigated on each contribution, and a reviewer has no basis on which to ask for a change.

Because Doxygen accepts both sigils, nothing fails to build and nothing renders wrongly. The cost is confusion and churn, not broken output.

Possible fix

Two options; the choice is an owner question.

Correct the rule to match the code. Change AGENTS.md:280 to prefer @ and rewrite the example block at AGENTS.md:263-275 in @ style. This touches one file, makes the documented rule true immediately, and removes the mixed-sigil problem, since the FhSim tags are already @. It also silently blesses 314 existing occurrences.
Convert the code to match the rule. Rewrite the Doxygen tags in every hand-written header and source file under src/ and include/. This is a large, purely cosmetic diff across the whole tree; it would collide with any in-flight branch, and it cannot be applied to the FhSim-specific tags, so files would end up mixing \param with @addoption.

Option 1 is the smaller and more coherent change, but the decision is the owner's: the rule may have been written deliberately to follow an external house style shared with sibling packages, in which case the wider convention matters more than this repository's history. Worth checking marenv/AGENTS.md and the other fhsim_* packages before deciding, since a per-package answer would be worse than either option.

Test that would prove it

$ grep -rho '\\param' src include | wc -l # currently 0

$ grep -rho '@param' src include | wc -l # currently 314

After option 1, the second count stays non-zero and AGENTS.md:280 no longer contradicts it. After option 2, the two counts swap.

Risk

Option 1 is documentation-only and carries no build or runtime risk.

Option 2 touches every documented declaration in the package. The risk is not functional — Doxygen accepts both forms — but a tree-wide comment rewrite is easy to get subtly wrong (for example converting \endcode-adjacent text or the \code blocks inside EnvironmentProvider.h), and it would invalidate the OpenWiki Claim evidence that quotes current file contents.