Skip to content

fix(common): preflight XML doc warnings for strict-gate composition#171

Closed
ottobolyos wants to merge 2 commits into
TrakHound:masterfrom
ottobolyos:fix/doc-warnings-preflight
Closed

fix(common): preflight XML doc warnings for strict-gate composition#171
ottobolyos wants to merge 2 commits into
TrakHound:masterfrom
ottobolyos:fix/doc-warnings-preflight

Conversation

@ottobolyos
Copy link
Copy Markdown
Contributor

Summary

Fixes pre-existing XML doc structural defects that surface only when GenerateDocumentationFile=true and TreatWarningsAsErrors=true compose. Two families:

  • CS1570 (bare & in /// comments) — escape & to & in 8 sites under libraries/MTConnect.NET-Common/Streams/. Bare & in a doc-comment is interpreted as the start of an XML entity reference; the doc-file build step then reports "badly formed XML in include comment".
  • CS1570 (nested <summary> tag) — remove the duplicated <summary> opener in IAdapterApplicationConfiguration.ServiceName, which produces "Expected an end tag for element 'summary'".
  • CS1572 + CS1574 (orphan <param name="logger"> + cref ILogger) — three sites in MTConnect.NET-SysML/Xmi/XmiDeserializer.cs carry stale param tags referring to a parameter that no longer exists, and cite a type (ILogger) the project doesn't reference. Drop the lines; the surviving tags cover every real parameter.

These are silent warnings on master today; the build only goes red when a downstream branch flips both gates. Preflighting them here keeps the downstream branch's diff focused on its real change.

Deferred follow-up

Investigation under the strict-gate composition surfaced ~114 additional XML-doc-comment-vs-signature mismatches beyond the structural defects fixed here:

  • 104 × CS1573 (parameter has no matching <param> tag)
  • 4 × CS1572 (orphan <param> tags at other sites)
  • 2 × CS1712 (missing <typeparam>)
  • 2 × CS1711 (typeparam for non-existent type parameter)
  • 2 × CS1570 (other malformed XML — including one with literal 0x02 in a copy-pasted XML body)

These concentrate in libraries/MTConnect.NET-Common/{Configurations,Agents,Devices}/ (DeviceConfiguration.cs, ConfigurationFileWatcher.cs, MTConnectAgentBroker.cs, IMTConnectAgentBroker.cs, IDevicesDocument.cs). They are pre-existing on master and turn into errors under the same strict gates. Tracking as a follow-up rather than expanding this PR's scope, since the fix is per-signature reconciliation (semantic content review of each <param> block) rather than mechanical escaping.

@ottobolyos ottobolyos force-pushed the fix/doc-warnings-preflight branch 6 times, most recently from 1c871f3 to ba1df9b Compare May 28, 2026 15:17
…r config

Bare '&' in /// comments is interpreted as the start of an XML entity
reference, triggering CS1570 ('badly formed XML in include comment')
when GenerateDocumentationFile=true. Escape to '&amp;' on every site.

Also resolve a malformed nested <summary> tag in
IAdapterApplicationConfiguration that produces 'Expected an end tag
for element summary' on the same gate.

These are silent warnings on master today; only the combination of
GenerateDocumentationFile=true (planned via the documentation
generation initiative) and TreatWarningsAsErrors=true turns them red.
XmiDeserializer's ctor + the two static factory methods carry
<param name="logger"> tags that reference a parameter that no
longer exists on any of the three signatures (and an <inheritdoc
cref="ILogger"/> for a type the project doesn't reference).

Under GenerateDocumentationFile=true these produce CS1572 ('param
tag for logger, but there is no parameter by that name') and
CS1574 ('cref ILogger could not be resolved') at every site; the
combined gate of TreatWarningsAsErrors=true (planned via the
warning-cleanup initiative) makes them break the build.

Drop the orphan lines; the surviving param tags already cover
every real parameter.
@ottobolyos ottobolyos force-pushed the fix/doc-warnings-preflight branch from ba1df9b to 4644f4f Compare May 28, 2026 16:46
@ottobolyos
Copy link
Copy Markdown
Contributor Author

Closing this — the three doc-comment defects it addressed have all landed in #157 (the VitePress documentation PR) as part of that branch's documentation-gate work, via independent and arguably cleaner fixes:

  • the Streams/ summaries were rephrased to "Samples, Events, and Conditions", avoiding the bare ampersand entirely rather than escaping it to &amp;;
  • the orphan <param name="logger"> tags on XmiDeserializer were dropped;
  • the duplicated <summary> opener on IAdapterApplicationConfiguration.ServiceName was removed.

With #157 carrying equivalent fixes for every item here, this preflight PR is redundant. The broader signature/param-mismatch cleanup noted in the description (the ~114 CS1573/CS1572/CS1711/CS1712 sites) remains worthwhile as a separate future pass.

@ottobolyos ottobolyos closed this May 28, 2026
@github-project-automation github-project-automation Bot moved this from In Progress to Done in MTConnect.NET-Development May 28, 2026
@ottobolyos ottobolyos deleted the fix/doc-warnings-preflight branch May 28, 2026 20:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Development

Successfully merging this pull request may close these issues.

2 participants