search

dotnet / csharplang

The official repo for the design of the C# programming language
11.48k stars 1.02k forks source link

Support for namespace XML doc comments #315

Open daveaglick opened 7 years ago

daveaglick commented 7 years ago

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)

gafter commented 7 years ago

Implementation proposed at https://github.com/dotnet/roslyn/pull/15494

gafter commented 7 years ago

I'm championing this for LDM triage.

daveaglick commented 7 years ago

Thanks @gafter, just let me know when/if you need anything else from my end