dotnet / dotnet/csharplang

[Proposal]: Support for namespace XML doc comments

Open
#8,983 0 comments 0 reactions 1 assignee Claimed by @DustinCampbell View on GitHub
Proposal champion
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.