Документация о пространстве имен в проекте .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 находится here.

Answer 2

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

В списке функций:

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

Answer 3

Sandcastle Help File Builder. Это позволяет указать описания пространства имен в файле XML проекта

Пример:

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

Ссылки:

• example of Open Source project , который генерирует документацию с каждой сборки (все сценарии в багажник).
• Вот how the documentation by SHFB looks like on the Web (он развернут на каждой вынужденной сборки)

.

Answer 4

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

т.е.

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

see here

Answer 5

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

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

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

Answer 6

Я вижу документацию для «внешнего XML Комментариев файлов». Отображение схемы, как:

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

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