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
    1. System.Collections Namespace
    2. System.Collections.Concurrent Namespace
    3. ...

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?

Answer 1

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.

Answer 2

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.