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

Question

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

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

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

}

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

Answer 1

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

Edit: Например:

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

Answer 2

Sandcastle напрямую не поддерживает NamespaceDoc, но если вы используете Filecast Help 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 для файла справки. Таким образом, код не загроможден всеми деталями и остается легко читаемым.

Answer 3

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

Answer 4

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

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

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

Answer 5

Если вы используете Sandcastle и его «File File Builder», вы можете задокументировать пространства имен и группы пространств имен, используя следующий код в ваших проектах:

namespace Company.Product.Widgets
{
    /// <summary>
    /// These are the namespace comments for <c>Company.Product.Widgets</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceDoc
    {
    }
}

Если в проекте включена группировка пространства имен, вы также можете поддерживать комментарии к группе пространства имен, используя класс NamespaceGroupDoc аналогичным образом. Ниже приведен пример:

namespace Company.Product
{
    /// <summary>
    /// These are the group comments for namespaces in <c>Company.Product</c>.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGeneratedAttribute()]
    class NamespaceGroupDoc
    {
    }
}

Чтобы класс NamespaceDoc не появлялся в файле справки, не используйте ключевое слово public и пометьте его атрибутом CompilerGenerated.

Для справки см. Здесь: https://ewsoftware.github.io/SHFB/html/48f5a893-acde-4e50-8c17-72b83d9c3f9d.htm

Answer 6

Если используется система документации Mono mdoc , вы можете документировать элементы пространства имен, редактируя файлы документации ns - *. Xml.

Подробнее см. Документацию формата mdoc .

Answer 7

Невозможно оставлять комментарии к пространствам имен.

UseNamespaceDocSummaries на http://ndoc.sourceforge.net/content/documenters.htm