XML-документация для пространства имен

Вы могли бы написать xml-doc для пространства имен? И если да, то как и где?

Я подумал бы, если это возможно, возможно, почти пустой файл вроде этого:

/// <summary>
/// This namespace contains stuff
/// </summary>
namespace Some.Namespace
{

}

Но это сработает? Поскольку вы... "объявляете" или, по крайней мере, используете пространство имен во всех других файлах... и что произойдет, если вы напишете xml-документацию в другом месте в том же пространстве имен? Кто-нибудь исчезнет? Или они каким-то образом слились?

Ответы

Ответ 1

NDoc поддерживает это, признавая специальный класс NamespaceDoc, расположенный в каждом пространстве имен, и используя документацию из этого. Я не пробовал, но Sandcastle, похоже, поддерживает тот же трюк.

Edit: Например:

namespace Some.Namespace
{
    /// <summary>
    /// This namespace contains stuff
    /// </summary>
    public static class NamespaceDoc
    {
    }
}

Ответ 2

Sandcastle не поддерживает NamespaceDoc напрямую, но если вы используете Sandbule Help File Builder, вы можете использовать класс NamespaceDoc, упомянутый Тимом.

namespace Example
{
    /// <summary>
    ///   <para>
    ///     Summary
    ///   </para>
    /// </summary>
    /// <include file='_Namespace.xml' path='Documentation/*' />
    internal class NamespaceDoc
    {
    }
}

SCHB также немного расширяет синтаксис и позволяет вставлять примеры кода прямо из файлов кода. Пример _Namespace.xml:

<?xml version="1.0" encoding="utf-8" ?>
<Documentation>
  <summary>
    <h1 class="heading">Example Namespace</h1>
    <para>
      This namespace is used in the following way:
    </para>

    <code source="Examples\Class.cs" lang="cs"></code>
    <code source="Examples\Class.vb" lang="vbnet"></code>

    <para>
      Hopefully this helps!
    </para>
  </summary>
</Documentation>

Включение документации в файл XML позволяет писать краткое резюме в коде и более подробное описание в отдельном файле XML для файла справки. Таким образом, код не загроможден всеми деталями и остается легко читаемым.

Ответ 3

Sandcastle Help File Builder поддерживает комментарии к пространствам имен. Откройте проект Sandcastle. В окне Project Properties перейдите к Summaries и нажмите кнопку Edit Namespace Summaries.

enter image description here

Ответ 4

Вы можете сделать это в doxygen, используя:

/// <summary>
/// description
/// </summary>
namespace name{};

Кроме того, рекомендуется объявить свои пространства имен в файле NameSpaces.cs и прокомментировать их только в этом файле.