XML Comments -- How (or where) do you create XML comments for your namespaces and library?

Question

I understand that if you /// above a class, field, method, or property Visual Studio will start establishing XML-style comments for you.

However, where can I go to add XML comments for my namespaces and/or library...

For example:

.NET Framework Class Library
- System.Collections Namespaces

I'm not sure if those pages were manually created or if they were automatically created via XML-style comments being added in the proper locations?

[Duplicate](http://stackoverflow.com/questions/156582/namespace-documentation-on-a-net-project-sandcastle)? — Christian.K, May 20 '11 at 07:20

score 3 · Accepted Answer · edited May 23 '17 at 12:09

3

That depends on the tool you use to generate your documentation. With NDoc, I believe, you simply had to create a class called NamespaceDoc inside the namespace you wanted to document. The XML-Comment of that class would have then be used.

Since the question is tagged with "sandcastle", I assume you are indeed using it. If so, this SO answer should give the details.

Update: OK, I just (in that same thread) saw that apparently Sandcastle understands NamespaceDoc-classes as well. Somebody might want to close this question as a duplicate.

edited May 23 '17 at 12:09

Community

1
1

answered May 20 '11 at 07:01

Christian.K

47,778
10
99
143

i have doubt regarding this XML-Comment for namespace, do we need to create `NamespaceDoc` class for each of my classes in my whole project ? or do i missing something ? im not using "sandcastle" – FosterZ May 10 '12 at 13:23
You create one "NamespaceDoc" class for (and inside) each namespace in your project (that you want to document). – Christian.K May 10 '12 at 13:28

score 0 · Answer 2 · answered May 19 '11 at 21:18

To generate the xml file you need to turn it on in your project properties. It's the checkbox XML documentation file on the Build tab of the project properties.

If you turned it on and you re-compile the assembly an xml file will appear next to the assembly with the same name as that assembly.

You can then use a tool like sandcastle to create a helpfile for your code. sandcastle is actually a set of tools you can use to customize the whole process of generating help files. This path will require a lot of reading the sandcastle helpfile and tutorials.

There also is a tool burried in the examples folder of the sandcastle installation that lets you quickly generate a helpfile but offers less cusomization.

In the past i used a visual studio plugin called "DocProject" for a little while. I'm not sure if it still active but you can find it on codeplex if your interested: http://docproject.codeplex.com/

According to Microsoft the MSDN examples you refer to are not created by extracting the /// tags from their source but that had more to do with splitting the programmers and documenters deparments then anything else.

XML Comments -- How (or where) do you create XML comments for your namespaces and library?

2 Answers2