[Proposal]: Support for namespace XML doc comments
- Dominant language
- C#
- Stars
- 12.7k
- Forks
- 1.1k
- Avg merge
- 11h 1m
- Merged PRs (30d)
- 3
Description
* Discussion: https://github.com/dotnet/csharplang/discussions/8982
## Summary
[summary]: #summary
Over the years, different .NET documentation generators have used different techniques for representing documentation on a namespace. For example, NDoc and SHFB both use a special `NamespaceDoc` class and "promote" any XML doc comments on that type to the containing namespace.
As far as I can tell, Roslyn doesn't currently support XML doc comments on namespaces (there's no `GetDocumentationCommentXml()` override for namespace symbols). I propose that XML doc comments applied to a use of the namespace get picked up and returned from `GetDocumentationCommentXml()`. This would work just like a partial class and if multiple doc comment blocks are provided for a namespace, the last one wins.
I suppose namespace comments should also be included in the generated XML documentation output file (as created in `DocumentationCommentCompiler`). That seems like it might be a bit trickier since consumers probably don't expect comment elements at the namespace level. Is there a formalized schema somewhere for this XML output?
(copied from https://github.com/dotnet/roslyn/issues/15474)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.