0022 — The `NetStructure` family documentation tables are `???` placeholders

ID	0022
Class	DOCUMENTATION
Severity	2
Status	blocked
Models	Net/NetStructure, Net/NetStructureArray, Net/NetStructureWakeEffect
Found	2026-09-15 audit (e3f3107)
Decision needed	Provide the parameter meanings, or accept a mechanical names-and-defaults table as an interim.

Evidence

src/net/NetStructure.h:109-124 and :160-161, for instance:

@addoption{ <???>Force...<???>Force , 3, Only if external node tags are used ...}
@addoption{BottomContact, 6, ???}
@addoption{ VelNorm , 1, ???}

and the entire configuration-parameter table is one placeholder row (:129-131):

@beginoptions
@addoption{ ??? , ???, ???}
@endoptions

src/net/NetStructureArray.h:105-120 and src/net/NetStructureWakeEffect.h:116-131 repeat the same rows. The headers say as much themselves: each carries @todo Finish documentation and make complete example file.

Effect

Net/NetStructure is the core model of the library, and its generated page names no configuration parameter at all and gives port names as <???>Force. A user has to read src/net/NetStructureSpec.cpp and the <General> tag handling to configure a net. The port-name rows are worse than blank, because <???> reads as if it were the documented syntax.

Possible fix

• (a) Fill the tables from the code: the <General>-tag parameters are read in src/net/NetStructureSpec.cpp, the adaptation subset is SAdaptationSpec_t (src/net/NetStructureSpec.h), and the external-node port naming is in src/net/NetStructure.cpp. Do NetStructure first; NetStructureArray and NetStructureWakeEffect inherit most of it and should then reference the base page rather than copy it a third time.
• (b) Replace the placeholder rows with one honest sentence pointing at the source files, and keep the @todo. Less useful, but not misleading.

Owner question, open

the external-node port naming (<???>Force) depends on whether external node tags are used, and the rule is not obvious from the code. That rule needs stating by someone who knows it before the rows can be written.

Test that would prove it

The coverage script from MARE-0020, with an added check that no @addoption row contains ???.

Risk

None to behaviour. As in MARE-0020, the risk is inventing descriptions; the parameter names and defaults are recoverable from src/net/NetStructureSpec.cpp and src/net/protobuf/net.proto with certainty, the meanings are not.

---

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

Re-confirmed at HEAD: the NetStructure family documentation tables are ??? placeholders. As with MARE-0020, the names and defaults can be read from the code but the meanings cannot, and filling the tables with restated identifiers would misrepresent the documentation as complete. The owner or the model's author must supply the parameter meanings. Smallest owner decision: provide the meanings, or accept a mechanical names-and-defaults table as an interim.

---