Документирование кода с помощью XML-комментариев

Статья
03/05/2024

Документацию можно создать из примечаний с тройной косой чертой (//) в F#. Примечания XML могут предшествовать объявлениям в файлах кода (FS) или сигнатурах (FSI).

Комментарии к XML-документации — это особый тип комментария, добавляемого перед определением определяемого пользователем типа или члена. Их особенность в том, что компилятор может обрабатывать их для создания XML-файла документации во время компиляции. XML-файл, созданный компилятором, можно распространять вместе со сборкой .NET, чтобы идентификаторы удостоверений могли использовать подсказки для отображения быстрых сведений о типах или членах. Кроме того, XML-файл можно запускать с помощью таких средств, как fsdocs для создания эталонных веб-сайтов API.

Комментарии xml-документации, как и все остальные комментарии, игнорируются компилятором, если описанные ниже параметры не включены для проверка допустимости и полноты комментариев во время компиляции.

Можно создать XML-файл во время компиляции, выполнив одно из следующих действий.

Элемент можно добавить GenerateDocumentationFile<PropertyGroup> в раздел .fsproj файла проекта, который создает XML-файл в каталоге проекта с тем же корневым именем файла, что и сборка. Например:
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
Дополнительные сведения см. в разделе "Свойство GenerateDocumentationFile".
Если вы разрабатываете приложение с помощью Visual Studio, щелкните правой кнопкой мыши проект и выберите Свойства. В диалоговом окне свойств откройте вкладку Сборка и выберите XML-файл документации. Можно также изменить расположение, в котором компилятор записывает файл.

Существует два способа написания комментариев XML-документации: с тегами XML и без них. Оба используют примечания с тройной косой чертой.

Комментарии без XML-тегов

/// Если комментарий не начинается с<, весь текст комментария принимается в качестве сводной документации по конструкции кода, которая немедленно следует. Используйте этот метод, если вы хотите написать только краткую сводку для каждой конструкции.

Комментарий закодирован в XML во время подготовки документации, поэтому такие символы, как <, >и & не требуется экранировать. Если тег сводки явно не указан, не следует указывать другие теги, например param или возвращать теги.

В следующем примере показан альтернативный метод без xml-тегов. В этом примере весь текст в комментарии считается сводкой.

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

Комментарии с XML-тегами

Если текст комментария начинается с < (обычно <summary>), он рассматривается как xml-форматированный текст комментария с помощью XML-тегов. Этот второй способ позволяет указать отдельные заметки для краткой сводки, дополнительных примечаний, документации по каждому параметру и параметру типа и исключениям, а также описанию возвращаемого значения.

Ниже приведен типичный комментарий xml-документации в файле подписи:

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

Рекомендуемые теги

Если вы используете XML-теги, в следующей таблице описаны внешние теги, распознанные в комментариях кода F# XML.

Синтаксис тега	Описание
`<summary>`*text*`</summary>`	Указывает, что текст является кратким описанием элемента программы. Описание обычно является одним или двумя предложениями.
`<remarks>`*text*`</remarks>`	Указывает, что текст содержит дополнительные сведения об элементе программы.
`<param name="`*Описание имени*`"></param>`	Задает имя и описание параметра функции или метода.
`<typeparam name="`*Описание имени*`"></typeparam>`	Указывает имя и описание параметра типа.
`<returns>`*text*`</returns>`	Указывает, что текст описывает возвращаемое значение функции или метода.
`<exception cref="`*Описание типа*`"></exception>`	Указывает тип исключения, которое может быть создано, и обстоятельства, при которых он создается.
`<seealso cref="`*reference*`"/>`	Указывает ссылку "См. также" в документации для другого типа. Ссылка — это имя, как показано в XML-файле документации. См. также ссылки, как правило, отображаются в нижней части страницы документации.

В следующей таблице описываются теги для использования в разделах описания:

Синтаксис тега	Описание
`<para>`*text*`</para>`	Указывает абзац текста. Используется для разделения текста внутри тега примечаний .
`<code>`*text*`</code>`	Указывает, что текст состоит из нескольких строк кода. Этот тег можно использовать генераторами документации для отображения текста в шрифте, подходящем для кода.
`<paramref name="`*name*`"/>`	Указывает ссылку на параметр в том же комментарии документации.
`<typeparamref name="`*name*`"/>`	Указывает ссылку на параметр типа в том же комментарии документации.
`<c>`*text*`</c>`	Указывает, что текст является встроенным кодом. Этот тег можно использовать генераторами документации для отображения текста в шрифте, подходящем для кода.
`<see cref="`*справочный`">`текст*`</see>`	Указывает встроенную ссылку на другой элемент программы. Ссылка — это имя, как показано в XML-файле документации. Текст — это текст , отображаемый в ссылке.

Пользовательские теги

Предыдущие теги представляют те, которые распознаются компилятором F# и типичными инструментами редактора F#. Тем не менее пользователь может определять собственные теги. Такие инструменты, как fsdocs, поддерживают дополнительные теги, такие как namespacedoc>.< Средства создания пользовательской или внутренней документации также можно использовать со стандартными тегами. Кроме того, поддерживается несколько выходных форматов — от HTML до PDF.

Проверка компиляции

Если --warnon:3390 этот параметр включен, компилятор проверяет синтаксис XML и параметры, указанные в <param> и <paramref> тегах.

Документирование конструкций F#

Конструкции F#, такие как модули, члены, дела объединения и поля записей, документируются комментарием /// непосредственно перед объявлением. При необходимости неявные конструкторы классов документируются путем предоставления комментария перед списком /// аргументов. Например:

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

Ограничения

Некоторые функции XML-документации в C# и других языках .NET не поддерживаются в F#.

В F#перекрестные ссылки должны использовать полную XML-сигнатуру соответствующего символа, например cref="T:System.Console". Простые перекрестные ссылки на C#, такие как cref="Console" не разработаны для полной xml-подписи, и эти элементы не проверка компилятором F#. Некоторые средства документации могут позволить использовать эти перекрестные ссылки путем последующей обработки, но должны использоваться полные подписи.
Теги <include>, <inheritdoc> не поддерживаются компилятором F#. Ошибка не возникает, если они используются, но они просто копируются в созданный файл документации без влияния на созданную документацию.
Перекрестные ссылки не проверка компилятором F#, даже если -warnon:3390 используется.
Имена, используемые в тегах <typeparam> и <typeparamref> не проверка компилятором F#, даже если --warnon:3390 используется.
Предупреждения не предоставляются, если документация отсутствует, даже если --warnon:3390 она используется.

Поделиться через