Документация по пространству имен в проекте .Net(Sandcastle)?

Я начал использовать Sandcastle некоторое время назад, чтобы создать сайт Documentation для одного из наших проектов. Он работает очень хорошо, но мы всегда только писали документацию по классам, методам, свойствам (...) в нашем проекте и имели полностью отдельную документацию для общих частей проекта и проектов/модулей/пространств имен. Было бы неплохо, если бы я мог объединить эту документацию вместе и добавить соответствующую документацию к сгенерированным вспомогательным файлам, но я не могу понять, как это сделать.

Просто добавление комментариев к объявлению пространства имен не работает (С#):

/// <summary>
/// My short namespace description
/// </summary>
namespace MyNamespace { ... }

Кто-нибудь знает, как это сделать? Я знаю, что это возможно как-то, и было бы очень приятно иметь...:)

Ответы

Ответ 1

Sandcastle также поддерживает документацию по пространству имен ndoc, которая позволяет хранить документацию в исходных файлах:

Просто создайте непубличный класс под названием NamespaceDoc в пространстве имен, который вы хотите документировать, и комментарий xml doc для этого класса будет использоваться для пространства имен.

Украсьте его атрибутом [CompilerGenerated], чтобы предотвратить появление самого класса в документации.

Пример:

namespace Some.Test
{
    /// <summary>
    /// The <see cref="Some.Test"/> namespace contains classes for ....
    /// </summary>

    [System.Runtime.CompilerServices.CompilerGenerated]
    class NamespaceDoc
    {
    }
}

Рабочий элемент в SandCastle расположен здесь.

Ответ 2

Если вы используете Sandbule Help File Builder, появляется диалоговое окно для ввода кратких сводок пространства имен. (Видимо, также поддержка определения определенного класса, но я бы не предпочла его.)

Из списка функций:

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

Ответ 3

Используйте Builder Builder для Sandcastle. Он позволяет указывать описания пространств имен в файле проекта XML

Пример:

<namespaceSummaryItem name="System" isDocumented="True">
    Generic interfaces and helper classes.
</namespaceSummaryItem>

Ссылки:

пример проекта с открытым исходным кодом который генерирует документацию с каждая сборка (все скрипты находятся в ствол).
как документация по SHFB выглядит в Интернете (это развертывается при каждой принудительной сборке)

Ответ 4

Я знаю это старое сообщение, но это может помочь кому-то другому.

Следуя этой ссылке, вы можете установить описание пространств имен без необходимости добавления в проект непубличного класса.

Чтобы отредактировать сводки пространств имен, разверните раздел "Резюме" на вкладке "Свойства проекта" в SHFB. Вы увидите настройку с именем "NamespaceSummaries", которая изначально показывает значение "(Нет)". Нажмите эту настройку, чтобы выбрать его, и появится кнопка с символом многоточия (...). Нажмите эту кнопку, чтобы отобразить диалоговое окно Сводка пространства имен, изображенное ниже:

Ответ 5

Вы не можете добавлять ссылки таким образом - сделайте это через экземпляры NamespaceDoc.cs

то есть

/// <summary> /// Concrete implementation of see cref="IInterface" using see cref="Concrete" /// </summary> class NamespaceDoc { }

см. здесь