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

Question

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

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

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

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

Answer 1

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

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

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

Пример:

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

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

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

Answer 2

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

Из списка возможностей:

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

Answer 3

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

Пример:

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

Рекомендации:

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

.

Answer 4

Я знаю, что это старый пост, но это может помочь кому-то еще.

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

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

Answer 5

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

* 1003 т.е. *

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

см. Здесь

Answer 6

Я вижу документацию для "Внешних XML-файлов комментариев". Отображение схемы вроде:

<doc>
    <assembly/>
    <members>
        <member/>
    </members>
</doc>

Если это помещено в отдельный файл, какое расширение будет (xml / aml) и может ли это использоваться в проекте Visual Studio?