feat(docs): expand API reference to every committed project#182
Draft
ottobolyos wants to merge 28 commits into
Draft
feat(docs): expand API reference to every committed project#182ottobolyos wants to merge 28 commits into
ottobolyos wants to merge 28 commits into
Conversation
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
2 times, most recently
from
0c02529 to
789c54c
Compare
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
7ecc7c1 to
c3adc58
Compare
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
639c0c1 to
b6485d7
Compare
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 1, 2026
# Conflicts: # docs/.docfx/docfx.json # docs/scripts/generate-api-ref.sh
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 1, 2026
# Conflicts: # docs/.docfx/docfx.json # docs/scripts/generate-api-ref.sh
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 1, 2026
# Conflicts: # docs/.docfx/docfx.json # docs/scripts/generate-api-ref.sh
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
b6485d7 to
28a5384
Compare
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 1, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 1, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
Adds /// doc comments to the HttpClientDeviceModel test fixture and each of its five [Test] methods so the project survives the campaign's 100% XML-doc coverage gate (CS1591 → error). The original block comment on the class is promoted to a /// summary; each test gains a one-line summary that pins the behaviour the test name expresses. The gap surfaced when this PR's branch was union-merged into the integration branch on top of feat/docs-full-coverage (TrakHound#182), which turns CS1591 into a build error for every test project.
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
e295194 to
1167076
Compare
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
1167076 to
f150749
Compare
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
Grow the API reference from the 13 shipped libraries to every committed .csproj in the repo: agent and adapter applications and modules, in-tree generator and builder tools, the four standalone examples, the embedded-agent template content project, and the ten test suites. The audience comment on generate-api-ref.sh is broadened from 'libraries' to 'every committed project'. The script's project list now uses path-prefixed entries with an optional ':csproj' suffix for the project whose csproj filename diverges from the directory name (the embedded-agent template content). Reference output grows from ~1881 pages on the 13-library subset to the full repo surface.
The doc-comments commit on MTConnect-Compliance-Tests shifted the line of the FixtureDirEnv read in CppAgentParityWorkflowTests.cs from 488 to 499. The generated page embeds source line numbers, so the change desynced docs/reference/environment-variables.md and the in-sync test in MTConnect.NET-Docs-Tests failed on every integration branch layered on top of this PR (TrakHound#185, TrakHound#186).
docfx emits two C#-generic patterns whose opening `<` is bare while
the closing `>` is markdown-escaped as `\>`:
1. heading text after the anchor close, e.g.
`### <a id="…"></a> CollectShell(string, List<EnvVarInfo\>)`
2. return / parameter blocks where docfx renders an outer-generic
link followed by an inner-generic link, e.g.
` [List](…)<[EnvVarInfo](…)\>`
VitePress's underlying Vue template compiler sees the bare `<` as the
start tag of an element that never closes (the escaped `\>` is rendered
as a literal `>` rather than an end-tag token), tripping "Element is
missing end tag" during `vitepress build` and failing the Docs-site
CI's Build VitePress site job.
Add a post-processing awk pass to generate-api-ref.sh that rewrites
`<[A-Z]` and `<[` outside fenced code blocks to `<[A-Z]` /
`<[`. The `<` HTML entity survives the markdown -> HTML
pipeline, whereas a backslash-escape would decode back to `<` and
re-trip the same error. The awk filter tracks ```-fence state so
signatures in code blocks (e.g. `public IReadOnlyList<EnvVarInfo>
Collect(...)`) stay untouched, and the lowercase `<a id="…"></a>`
anchor itself is unaffected because the pattern requires either an
uppercase letter or `[`.
The class-level XML doc comment on PalletMeasurementContractTests
wrapped a single `<c>PhysicalAsset > Pallet > Measurements</c>`
span across two source lines:
/// Per the MTConnect SysML model, the <c>PhysicalAsset > Pallet
/// > Measurements</c> package declares ...
docfx flattens the wrapped XML doc into adjacent markdown lines,
producing a line that starts with `> Measurements</code> package
declares ...`. The leading `> ` is then re-parsed as a markdown
blockquote, eating the `</code>` close tag and tripping Vue's
"Element is missing end tag" error during the Docs-site CI's Build
VitePress site job.
Reflow the comment so the `<c>...</c>` span fits on one line. The
generated markdown then carries the full code span on a single line
and the blockquote-collision goes away.
docfx preserves verbatim spec-marker text from XML doc comments like
"{{term(data set)}} of the number of {{termplural(Asset)}} ..."
in the generated `*.md` files. VitePress's underlying Vue template
compiler then treats `{{ ... }}` as a mustache interpolation and
tries to parse the contents as a JavaScript expression. Spec markers
contain unquoted spaces and operator-like tokens, so the parse fails
and the Docs-site CI's Build VitePress site job aborts with errors
like `Error parsing JavaScript expression: Unexpected token`.
Extend the post-processing awk pass to rewrite every `{{` outside
fenced code blocks as `&TrakHound#123;&TrakHound#123;`. The html-entity form survives
the markdown -> HTML pipeline and presents the original characters
to readers without engaging Vue's mustache parser. Standalone `}}`
is harmless once its opening `{{` is gone, so it is left alone.
The in-tree DocsGen generator produces the docs/api/ tree at build time; it is not a public NuGet surface, so its own API reference does not need to ship. Its EnvVarInventory summary embeds a bulleted list whose items mix six-space indents with bare <c> tags, which docfx forwards verbatim into Markdown. VitePress's Vue template parser then sees an inline code element opening inside what Markdown promotes to an indented code block, and rejects the page with "Element is missing end tag" at api/MTConnect.NET_DocsGen.EnvVarInventory.md:85. Removing the project from docs/.docfx/docfx.json and the parallel list in docs/scripts/generate-api-ref.sh skips both the problematic page and every other DocsGen-namespaced page (none are referenced from any sidebar or cross-link). Three earlier escape fixes f7290a1, dcc4cdb, f150749 patched related cases but could not handle this specific Markdown / Vue interaction without rewriting the source XML doc comment, which is the longer path.
Dropping MTConnect.NET-DocsGen from the docfx project list and the generator script was insufficient: MTConnect.NET-Docs-Tests references DocsGen as a project reference, so the build copies MTConnect.NET-DocsGen.dll and its XML doc file into the tests' bin/Debug/net8.0/ output. Docfx then re-discovers the DocsGen types via the copy-local'd assembly and re-emits MTConnect.NET_DocsGen.*.md pages -- including the EnvVarInventory page whose summary still trips VitePress's Vue template parser. Add an apiRules exclude in docs/.docfx/filter.yml that drops the namespace at metadata extraction time. The filter runs after assembly discovery, so it catches the namespace regardless of which DLL pulls it in.
The flat 2 000-page API reference plus the unified server + client bundles push rollup past the GitHub Actions runner's default Node heap (~4 GB) during the markdown -> Vue transform, aborting the build with "Ineffective mark-compacts near heap limit" / exit 134 even when no individual page fails to parse. The runner has 16 GB of RAM, so 8 GB is comfortably within budget and matches the local bluefin verification that produces a clean rc=0.
docfx renders XML doc `<c>*.sh</c>` and `<c>*.ps1</c>` tags into `<code v-pre>*.sh</code>` / `<code v-pre>*.ps1</code>` markdown spans. When two such spans appear on the same line of the generated `*.md` -- as they do whenever an XML doc lists multiple glob patterns inline -- markdown-it interprets the four `*` characters as the bookends of two `<em>` emphasis spans. The pre-existing `<code>` open / close tags then end up spliced into the wrong positions in the rendered HTML, producing fragments like `<em>.sh</code> and <code v-pre></em>` with the element-nesting broken. Vue's template compiler then trips with `Element is missing end tag` during `vitepress build` and the Docs-site CI's Build VitePress site job aborts. Extend the post-processing awk pass to walk each `<code ...>... </code>` span on a non-fenced line and rewrite every `*` inside to `&TrakHound#42;`. The html-entity preserves the visible character for readers while keeping markdown's emphasis parser from ever seeing a literal `*`. Single-span lines were never broken, but the same escape applies harmlessly to them too.
ottobolyos
force-pushed
the
feat/docs-full-coverage
branch
from
69a72f3 to
4f1f6a6
Compare
ottobolyos
added a commit
to ottobolyos/mtconnect.net
that referenced
this pull request
Jun 2, 2026
Adds /// doc comments to the HttpClientDeviceModel test fixture and each of its five [Test] methods so the project survives the campaign's 100% XML-doc coverage gate (CS1591 → error). The original block comment on the class is promoted to a /// summary; each test gains a one-line summary that pins the behaviour the test name expresses. The gap surfaced when this PR's branch was union-merged into the integration branch on top of feat/docs-full-coverage (TrakHound#182), which turns CS1591 into a build error for every test project.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Expands the docfx-generated API reference from the 13 shipped libraries to every committed project in the repository — 44 in total — and authors the missing XML doc comments those new projects required so the build stays clean under
TreatWarningsAsErrors=true.docs/.docfx/docfx.jsonanddocs/scripts/generate-api-ref.sh: enlarge the project list to include the agent and adapter core libraries plus their per-module assemblies, the in-tree generator and builder tools underbuild/MTConnect.NET-SysML-Import,build/MTConnect.NET-DocsGen, andbuild/MTConnect.NET.Builder, the four standalone examples underexamples/, the embedded-agent template content project undertemplates/mtconnect.net-agent/content/MTConnect.NET-Embedded-Agent, and everytests/MTConnect.NET-*-Testsproject plustests/Compliance/MTConnect-Compliance-Tests(eleven test projects in total). The generator now produces 2 158 reference pages against the full repo surface.docs/scripts/generate-api-ref.sh: the per-project loop runsdotnet build --no-incrementaland passes noNoWarnoverride, soDirectory.Build.props'sTreatWarningsAsErrors=truegate catches every missing XML doc (CS1591) and every malformed-XML diagnostic (CS1570) at compile time. Without--no-incrementalanobj/tree produced under a previously suppressed build silently masked the missing-doc errors.examples/, thetemplates/mtconnect.net-agentagent-template content project, and every test project — class, struct, property, method, constructor, set-up and tear-down hook, helper, and test case. Each summary is one sentence; method parameters and non-void returns carry brief<param>and<returns>tags.<c><summary></c>escapes are used where prose references the XML-doc element name itself, to keep CS1570 clear.The libraries, agent, adapter, and
build/production projects were already at 100 % XML doc coverage and required no edits — the new doc-comment work is scoped strictly to the projects this PR adds to docfx coverage.