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

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

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

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

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

6 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