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

StackOverflow https://stackoverflow.com/questions/156582

  •  03-07-2019
  •  | 
  •  

Вопрос

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

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

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

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

Это было полезно?

Решение

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

Другие советы

Если вы используете Конструктор файлов справки Sandcastle существует диалоговое окно для ввода сводки пространства имен.(Видимо, также поддерживается определение определенного класса, но я бы не предпочел этого..)

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

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

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

Пример:

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

Использованная литература:

.

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

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

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

enter image description here

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

то есть

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

глянь сюда

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

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

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top