Check FSharp.Core xml doc comments for validity #10111
Closed
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.
This adds optional basic checking of XML validity of XML doc comments using a new off-by-default warning 3390 and turns it on for FSharp.Core via
/warnon:3390
The main reason to add this is to guarantee our doc quality - we currently don't have any checking of the validity of the FSharp.Core.xml file, This means a single mistake in any of the XML docs for FSharp.Core can kill all documentation tooling that consumes it including our intellisense hints - because the whole file is invalid XML. By doing basic checking on individual comments we basically ensure overall validity of the file.
Separately I've been working on documentation for DiffSharp, and the lack of checking of XML docs in the F# compiler is really very driving me crazy - simple typos only reveal themselves much later. Optionally giving warnings about invalid XML is really necessary if we expect anyone to write good documentation - though this only does one small part of doc checking.
This warning is off by default - we can turn it on by default for the standard templates in vNext.