./mfc.sh precheck runs lint_docs.py, which checks that documentation references resolve. It does not
check that documented enumerated values agree with the toolchain, so a doc table can advertise a value
the validator rejects and omit one it accepts, and CI stays green.
#1782 is a live instance: case.md lists riemann_solver = 3 (rejected by case_validator.py) and omits
5 (accepted, and used by this repo's own AMR benchmark cases).
Why this is cheap to close: the data needed to check it is already machine-readable in
toolchain/mfc/params/definitions.py:
"riemann_solver": {
"choices": [1, 2, 4, 5],
"value_labels": {1: "HLL", 2: "HLLC", 4: "HLLD", 5: "Lax-Friedrichs"},
"names": {"hll": 1, "hllc": 2, "hlld": 4, "lax_friedrichs": 5},
},
"wave_speeds": {"choices": [1, 2], "value_labels": {1: "direct", 2: "pressure"}, ...},
"avg_state": {"choices": [1, 2], "value_labels": {1: "Roe", 2: "arithmetic"}, ...},
"model_eqns": {"choices": [1, 2, 3, 4], ...},Every parameter with a choices key is a candidate. A lint pass could, for each such parameter, find its
row in case.md and assert that the bracketed integers appearing there are exactly choices — flagging
both documented-but-rejected and accepted-but-undocumented values.
Two ways to do it, in increasing order of ambition:
- Check only. Parse the
case.md row for each choices parameter, compare the integer set, fail
precheck on a mismatch. Catches drift in both directions without changing how docs are written.
- Generate. Emit the enum portion of each row from
value_labels the way the Fortran declarations and
namelist bindings are already generated from definitions.py, so the two cannot diverge at all.
(1) is the smaller change and would have caught #1782. (2) matches the pattern the repo already uses for
parameter declarations, but it constrains prose formatting, so it is a bigger call.
This is a suggestion from the outside rather than a request — I hit the underlying divergence while
checking a solver setting and it seemed worth reporting the class as well as the instance.
./mfc.sh precheckrunslint_docs.py, which checks that documentation references resolve. It does notcheck that documented enumerated values agree with the toolchain, so a doc table can advertise a value
the validator rejects and omit one it accepts, and CI stays green.
#1782 is a live instance:
case.mdlistsriemann_solver = 3(rejected bycase_validator.py) and omits5(accepted, and used by this repo's own AMR benchmark cases).Why this is cheap to close: the data needed to check it is already machine-readable in
toolchain/mfc/params/definitions.py:Every parameter with a
choiceskey is a candidate. A lint pass could, for each such parameter, find itsrow in
case.mdand assert that the bracketed integers appearing there are exactlychoices— flaggingboth documented-but-rejected and accepted-but-undocumented values.
Two ways to do it, in increasing order of ambition:
case.mdrow for eachchoicesparameter, compare the integer set, failprecheck on a mismatch. Catches drift in both directions without changing how docs are written.
value_labelsthe way the Fortran declarations andnamelist bindings are already generated from
definitions.py, so the two cannot diverge at all.(1) is the smaller change and would have caught #1782. (2) matches the pattern the repo already uses for
parameter declarations, but it constrains prose formatting, so it is a bigger call.
This is a suggestion from the outside rather than a request — I hit the underlying divergence while
checking a solver setting and it seemed worth reporting the class as well as the instance.