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 dotnet/roslyn#15474)
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
NamespaceDocclass 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 fromGetDocumentationCommentXml(). 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 dotnet/roslyn#15474)