Question

I use doxygen and XML documentation comments to create an internal API documentation for our framework libaries.

Doxygen creates a “package” per namespace.
I wonder wether it’s possible to add source documentation on namespace level to show up in Doxygen’s package view?

Answer 1

It is possible to do this using the standard <summary> XML commenting style.

Even though Visual Studio does not recognise the fact that a namespace can be commented, adding summary documentation above any single namespace declaration will add that description to your generated documentation.

For example:

using System;
using System.Web;
using System.Web.Caching;

/// <summary> 
/// Testing namespace package descriptions
/// </summary>
namespace MyProject.Caching
{
   ...

You only need to add one instance of XML commenting for each namespace. For example, if you have two classes and one interface that are all declared under the same namespace, you only need to provide comments once for Doxygen to add a description for that namespace. Whether you add those comments on either of your classes or for the interface is immaterial.

Where conflicting namespace descriptions are added, Doxygen will pick up only the first instance it finds and ignore any others.