Support for namespace XML doc comments

[daveaglick]

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?

[svick]

Already mentioned in #67.

[jjrdk]

Obvious question: which namespace declaration the documentation goes on. How do you determine "last one wins"?

[daveaglick]

@svick Missed it in there, thanks. I think it's worthwhile separating doc comment inheritance from namespace/assembly doc comment support since they're essentially two totally different issues. The discussion in #67 seems to focus on inheriting doc comments, so I'll suggest this issue track the namespace/assembly request.

[daveaglick]

@jjrdk Same way it does for partial classes - it appears to be based on sorting the trivia locations, but I could be mistaken on that point.

[daveaglick]

After some research, it looks like the default behavior for symbols that span multiple trivia locations is to aggregate their documentation comments. I was actually able to stub out some rudimentary support for this using reflection to see how it might work. The following code uses DocumentationCommentCompiler.DefaultVisit() to compile the XML comments for a specific namespace symbol (the .Dump() call at the end is from LINQPad and just outputs the result):

var syntaxTree = CSharpSyntaxTree.ParseText(@"
	/// <summary>ABC</summary>
	namespace Foo
	{
	}
	
	/// <summary>EFG</summary>
	namespace Foo
	{
	}
");

var mscorlib = MetadataReference.CreateFromFile(typeof(object).Assembly.Location);
var options = new CSharpCompilationOptions(OutputKind.DynamicallyLinkedLibrary);
var compilation = CSharpCompilation.Create("MyAssembly").AddSyntaxTrees(syntaxTree).AddReferences(mscorlib).WithOptions(options);
var symbols = compilation.GetSymbolsWithName(x => x == "Foo", SymbolFilter.Namespace);

TextWriter writer = new StringWriter();
var ct = new CancellationToken();
var assembly = typeof(CSharpCompilation).Assembly;
var type = assembly.GetType("Microsoft.CodeAnalysis.CSharp.DocumentationCommentCompiler");
object documentationCompiler = Activator.CreateInstance(type, BindingFlags.Instance|BindingFlags.NonPublic, null, new object[]
{
	(string)null,
	compilation,
	writer,
	(SyntaxTree)null,
	(TextSpan?)null,
	true,
	true,
	null,
	ct
}, null);
var method = type.GetMethod("DefaultVisit");
method.Invoke(documentationCompiler, new object[] { symbols.First() });
writer.ToString().Dump();

It produces the following XML:

<member name="N:Foo">
    <summary>ABC</summary>
    <summary>EFG</summary>
</member>

I also gave some thought to namespace XML comments in the XML comment output file. I think it's reasonable to include them since that file can also contain custom XML comment elements. Because of that, anyone parsing this file is likely using XPath or some other parsing mechanism that looks for specific element names rather than position.

I plan to submit a PR for this soon that addresses it in the following way:

• Add code to DocumentationCommentCompiler.VisitNamespace() that checks _isForSingleSymbol and only outputs the local namespace comments if true. Also call DefaultVisit() from within VisitNamespace() to output the namespace XML comments.
• Add an overloaded NamespaceSymbol.GetDocumentationCommentXml().

Still not sure what to do about PENamespaceSymbol and VB, but I'll attempt to address those as well. Hopefully we can continue the discussion about appropriateness and approach in the PR.

[daveaglick]

Copied to dotnet/csharplang#315

[gafter]

Thanks! Closing this so discussion can continue at dotnet/csharplang#315