Inline docs requirements

[hartez]

1. What fields are required in /// comments
2. What's our standard/format when including external files (samples, etc)
3. What's the threshold for making doc parts external?
4. Do we need to add CI enforcement to make sure things get doc comments?

[jfversluis]

1. I will see if I can come up with something that makes sense. I think we don't have to do anything too special here mostly a summary of what the thing is in one or two lines will already help a lot. And is infinitely better than "To be added." 😬
2. Tbh personally I feel we shouldn't want to be taking it as far as adding samples or external files, etc. in our inline/API docs. I think this would mostly serve for IntelliSense and an online reference. If you really want an example in context you should go to the conceptual docs
3. See 2 I guess.
4. Ideally yes. I think by default if we enable the xml doc generation for our projects together with warnings as errors it won't build if we're missing something. We could and/or choose to also add something to our editorconfig file to make errors show up while you're working on code in the IDE. Since we're a bit behind on the coverage I would say that's something for later

[hartez]

Tagging #3960 so we can work on these all at once.

[hartez]

Adding this for reference: https://github.com/dotnet/dotnet-api-docs/wiki

[jfversluis]

Making some quick notes here so I can start materializing this.

• https://docs.microsoft.com/dotnet/csharp/language-reference/xmldoc/recommended-tags
• summary, returns, exceptions, remarks
• https://github.com/DotNetAnalyzers/StyleCopAnalyzers/blob/master/documentation/DocumentationRules.md

Tips and tricks:

• Add comments on base class/interface
  • <inheritdoc/>
• <see langword="true"/> for keywords
• <c>foo</c> == backticks in markdown
• No external files, if more than 5 lines go to external file???

What guidelines do other projects have? (ASPNET?)