Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for namespace XML doc comments #315

Open
daveaglick opened this issue Mar 22, 2017 · 3 comments
Open

Support for namespace XML doc comments #315

daveaglick opened this issue Mar 22, 2017 · 3 comments

Comments

@daveaglick
Copy link

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)

@gafter
Copy link
Member

gafter commented May 10, 2017

Implementation proposed at dotnet/roslyn#15494

@gafter gafter self-assigned this May 10, 2017
@gafter
Copy link
Member

gafter commented May 10, 2017

I'm championing this for LDM triage.

@daveaglick
Copy link
Author

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

@MadsTorgersen MadsTorgersen modified the milestone: X.X candidate May 16, 2017
@gafter gafter removed their assignment May 17, 2017
@DustinCampbell DustinCampbell modified the milestones: X.X candidate, X.0 candidate Sep 19, 2018
@MadsTorgersen MadsTorgersen added the Blocked Waiting for a dependency label Sep 19, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

5 participants