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

Question

I understand that if you /// over a class, field, method or property, Visual Studio will start setting XML comments for you.

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

For instance:

• .NET Framework Class Library
  • System.Collections namespaces
    • System.Collections namespace
    • System.Collections.Concurrent Namespace
    • ...

I'm not sure if these pages were created manually or were they automatically created using XML-style comments that are added to the appropriate locations?

Answer 1

It depends on the tool you use to create your documentation. With NDoc , I suppose you just needed to create a class called NamespaceDoc inside the namespace that you wanted to document. Then the XML comment of this class will be used.

Since the question is marked as "sandcastle", I assume that you really use it. If so, this SO answer should provide details.

Update: OK, I just ( in the same thread ) saw that Sandcastle apparently understood the NamespaceDoc classes. Someone may want to close this question as a duplicate.

Answer 2

To generate an xml file, you need to include it in the project properties. This is the XML documentation file checkbox on the Build tab of the project properties.

If you enable it and recompile the assembly, the same XML file as the assembly appears next to the assembly.

Then you can use a tool like sandcastle to create a help file for your code. sandcastle is actually a set of tools that you can use to customize the entire process of creating help files. This path will require a lot of reading the sandcastle help file and tutorials.

The sandcastle installation examples folder also has a tool that allows you to quickly generate a help file, but offers less cusomization.

In the past, I used a visual studio plugin called "DocProject" for a while. I'm not sure if it is still active, but you can find it on codeplex if you are 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 this is more about breaking up programs and document decoders, and then at something else.