fix(common): preflight XML doc warnings for strict-gate composition#171
Closed
ottobolyos wants to merge 2 commits into
Closed
fix(common): preflight XML doc warnings for strict-gate composition#171ottobolyos wants to merge 2 commits into
ottobolyos wants to merge 2 commits into
Conversation
1c871f3 to
ba1df9b
Compare
…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 '&' 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.
ba1df9b to
4644f4f
Compare
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:
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. |
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
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
Fixes pre-existing XML doc structural defects that surface only when
GenerateDocumentationFile=trueandTreatWarningsAsErrors=truecompose. Two families:&in///comments) — escape&to&in 8 sites underlibraries/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".<summary>tag) — remove the duplicated<summary>opener inIAdapterApplicationConfiguration.ServiceName, which produces "Expected an end tag for element 'summary'".<param name="logger">+ crefILogger) — three sites inMTConnect.NET-SysML/Xmi/XmiDeserializer.cscarry 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
mastertoday; 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:
<param>tag)<param>tags at other sites)<typeparam>)0x02in 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 onmasterand 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.