Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Check FSharp.Core xml doc comments for validity #10111

Closed
wants to merge 7 commits into from

Conversation

dsyme
Copy link
Contributor

@dsyme dsyme commented Sep 12, 2020

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.

@dsyme dsyme changed the title optionally check xml doc comments for xml validity Check FSharp.Core xml doc comments for validity Sep 12, 2020
@dsyme
Copy link
Contributor Author

dsyme commented Sep 14, 2020

This is now ready

@dsyme
Copy link
Contributor Author

dsyme commented Sep 14, 2020

Closing in favour of the more complete #10118

@dsyme dsyme closed this Sep 14, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants