Документация по пространству имен в проекте .Net (Sandcastle)?
-
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 в Интернете (Это развернуто на каждой принудительной сборке)
.
Я знаю, что это старый пост, но это может помочь кому-то еще.
По этой ссылке, вы можете задать описание пространств имен без необходимости добавления в проект закрытого класса.
Чтобы изменить сводку пространства имен, разверните раздел «Сводки» на вкладке «Свойства проекта» в SHFB.Вы увидите параметр с именем «NamespaceSummaries», который изначально отображает значение «(Нет)».Щелкните параметр, чтобы выбрать его, после чего появится кнопка со знаком многоточия (...).Нажмите эту кнопку, чтобы отобразить диалоговое окно «Сводка пространства имен», изображенное ниже:
Вы не можете добавлять ссылки таким образом — делайте это через экземпляры 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?