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

Статья
03/05/2024

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

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

По умолчанию комментарии xml-документации игнорируются компилятором. Чтобы изменить это, задайте --warnon:3390. Затем компилятор проверит синтаксис XML и параметров, указанных в <param> и <paramref> тегах.

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

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

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

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

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

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

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

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

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

Определяемые пользователем теги

Предыдущие теги представляют те, которые распознаются компилятором F# и типичными инструментами редактора F#. Однако пользователь может определить собственные теги. Такие инструменты, как fsdocs, поддерживают дополнительные теги, такие как <пространства имен>. Также можно использовать пользовательские или встроенные средства создания документации со стандартными тегами и несколькими форматами выходных данных из 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.

См. также

комментарии к XML-документации по C# (руководство по программированию на C#).
Справочник по языку F#
Параметры компилятора

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