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

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

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

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

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

60
.net documentation sandcastle

6 ответов

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 находится здесь.

72

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

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

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

19

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

пример:

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

ссылки:

.

7

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

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

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

enter image description here

4

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

Я.е

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

посмотреть здесь

1

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

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

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

0