mrdocs.rng and mrdocs.schema.json are generated from MrDocs's own metadata types. Of the 108 definitions in the RELAX NG schema, 100 are named S_ followed by a base58 ID. They should be named after the type they describe.
Problem
The two generated schemas under docs/modules/ROOT/attachments/schemas/generators/ are produced by the reflected schema generator (docs/mrdocs/extensions/schema.js). Eight definitions have readable names:
AnyAttribute AnyBlock AnyInline AnyName
AnySymbol AnyTArg AnyTParam AnyType
The other 100 look like this:
S_21EdS1EVSJuD9X76CVhzhLTLg1fi
S_22nFJc2hmNmmR5h1kq6NkgViKdEM
S_248GJRqqz5PAQuAWsyXn1pQuWx3E
The JSON schema has the same problem: 8 readable entries in $defs and 95 IDs.
That script walks MrDocs's own record symbols and emits both schemas plus the DOM reference partial, so the naming rule is one function in it.
A user reading the schema to understand the XML output, or wiring the JSON schema into an editor, gets no help from the names. The IDs also move when Clang changes how it computes them, so a schema regeneration produces a large meaningless diff.
Proposed solution
Each definition is named after the C++ type it reflects, for example FunctionSymbol or RecordTranche, with a documented rule for making the name unique when two reflected types share an unqualified name.
The symbol ID stays available as the fallback for anything the rule cannot name.
Regeneration and checking go through utils/codegen/generate-schema.sh and the schema-check test. The xml-lint test validates every golden XML fixture against the RELAX NG schema, so it will catch a rename that breaks a reference. Both schemas are also compiled in CI, the JSON one with ajv.
mrdocs.rngandmrdocs.schema.jsonare generated from MrDocs's own metadata types. Of the 108 definitions in the RELAX NG schema, 100 are namedS_followed by a base58 ID. They should be named after the type they describe.Problem
The two generated schemas under
docs/modules/ROOT/attachments/schemas/generators/are produced by the reflected schema generator (docs/mrdocs/extensions/schema.js). Eight definitions have readable names:The other 100 look like this:
The JSON schema has the same problem: 8 readable entries in
$defsand 95 IDs.That script walks MrDocs's own record symbols and emits both schemas plus the DOM reference partial, so the naming rule is one function in it.
A user reading the schema to understand the XML output, or wiring the JSON schema into an editor, gets no help from the names. The IDs also move when Clang changes how it computes them, so a schema regeneration produces a large meaningless diff.
Proposed solution
Each definition is named after the C++ type it reflects, for example
FunctionSymbolorRecordTranche, with a documented rule for making the name unique when two reflected types share an unqualified name.The symbol ID stays available as the fallback for anything the rule cannot name.
Regeneration and checking go through
utils/codegen/generate-schema.shand theschema-checktest. Thexml-linttest validates every golden XML fixture against the RELAX NG schema, so it will catch a rename that breaks a reference. Both schemas are also compiled in CI, the JSON one withajv.