0020 — The trawl/mooring SimObjects and `Net/NetStructureWithConstraints` have no port or parameter documentation

ID	0020
Class	DOCUMENTATION
Severity	2
Status	blocked
Models	TrawlBeam, MooringCable, TrawlCable, RundDorg, Net/NetStructureWithConstraints
Found	2026-09-15 audit (e3f3107)
Decision needed	Supply or point to the parameter meanings and units, or accept a mechanical names-and-defaults table as a first step.

Evidence

All five headers carry a @group line, so they generate a documentation page, but none carries a single @addoption row:

Class	Header	@addoption rows	Parameters read	Ports registered
TrawlCable	src/trawl_mooring_interaction/TrawlCable.h:5	0	59	18
MooringCable	src/trawl_mooring_interaction/MooringCable.h:3	0	53	8
RundDorg	src/trawl_mooring_interaction/RundDorg.h:4	0	42	13
TrawlBeam	src/trawl_mooring_interaction/TrawlBeam.h:4	0	13	12
NetStructureWithConstraints	src/net/NetStructureWithConstraints.h:5	0	9	—

(Counts are Get*Param and AddInport/AddOutport call sites in the matching .cpp.)

Effect

167 configuration parameters and 51 ports across five registered SimObjects — including TrawlCable, the largest model in the library — are discoverable only by reading the .cpp. The generated page for each shows a title and a brief and nothing a user can configure from. DEVELOPING.md names the section structure (purpose, example, input ports, output ports, configuration parameters, initial conditions) that the RMCable, cable and net headers follow; these five predate it or were skipped.

This is also why MARE-0003 is hard to reason about from outside the code: nothing documents what TrawlCable does with the integrator step.

Possible fix

• (a) Write the six standard sections for each of the five headers, taking every name from the Get*Param/AddInport/AddOutport call sites rather than from any existing prose. This is real work — TrawlCable alone is 59 parameters — and best done one class at a time.
• (b) Start with TrawlBeam (13 parameters, 12 ports) as a template and a proof that the section structure fits this group, then work up to TrawlCable.

Owner question, open

the meaning of most of these parameters is not recoverable from the call sites — only the name, type and default are. Anyone writing these tables will need owner input for the descriptions, or they will produce 167 rows of restated identifiers, which is worse than nothing because it looks like documentation.

Test that would prove it

The same coverage script as in MARE-0005, extended: for each registered class, assert that every Get*Param name and every port name in its .cpp appears in an @addoption row in its .h. That script is the durable fix for this whole class of finding — it would have caught MARE-0006, MARE-0007, MARE-0009, MARE-0010, MARE-0013, MARE-0015 and MARE-0017 as well.

Risk

None to behaviour. The risk is writing plausible-sounding descriptions that are wrong, which is worse than the current silence; where the meaning is unknown, say so in the row.

---

Why not solved (fix pass 2026-09-15)

Re-confirmed at HEAD: the trawl and mooring SimObjects and Net/NetStructureWithConstraints have no port or parameter documentation. Names, widths and defaults are recoverable from the code, but the meaning and units of each parameter are not, and about 167 rows of restated identifiers would be worse than the gap because they would look complete while saying nothing. Writing these tables needs the model owner's knowledge of the physics. Smallest owner decision: supply or point to the parameter meanings, or accept a mechanical names-and-defaults table as a first step.

---