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

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

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

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

Это предупреждение можно включить в файле проекта, добавив <WarnOn> элемент в <PropertyGroup> раздел:

<WarnOn>3390</WarnOn>

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

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

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

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

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

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

Замечание

При использовании комментариев без XML-тегов любая разметка, которую вы включаете (например, теги HTML или синтаксис XML), не будет анализироваться или проверяться средствами компилятора или F#. Некоторые внешние инструменты, такие как GitHub, могут попытаться проанализировать разметку, но они могут завершиться ошибкой, если синтаксис содержит ошибки. Если необходимо использовать XML-теги в документации, оставьте комментарии соответствующими XML-тегами, чтобы <summary> убедиться, что они проверяются компилятором при --warnon:3390 включении.

В следующем примере показан альтернативный метод без 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-файле документации. Ссылки 'См. также' обычно отображаются в нижней части страницы документации.
`<include file="path.xml" path="XPath"/>`	Начиная с компилятора F# 11, включает выбранные XML-элементы из внешнего файла в созданной документации.
`<inheritdoc/>`	Запрашивает унаследованную документацию от совместимых инструментов. Тег остается в XML-файле, созданном компилятором.

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

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

Повторное использование и наследование документации

Чтобы сохранить общие замечания один раз, поместите их shared.xml рядом с источником:

<docs>
  <tracking>
    <remarks>An unrecognized tracking identifier has status Unknown.</remarks>
  </tracking>
</docs>

Оба элемента выбирают эти элементы с одинаковым выражением XPath:

/// <summary>Find the latest status of a shipment.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let status trackingId =
    if trackingId = "SHP-1042" then "Dispatched" else "Unknown"

/// <summary>Find the latest statuses of several shipments.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let statuses trackingIds =
    trackingIds |> List.map (fun id -> id, status id)

Включение GenerateDocumentationFile или передача --doc:Tracking.xml. Начиная с F# 11, созданные записи содержат выбранные замечания и локальные сводки, а не только теги.

Пример проекта отслеживает XML как входные данные компиляции, чтобы изменить повторное создание триггера. Нет необходимости в выборе версии языка. Включает расширение в созданном XML, а не в реальном времени.

Включение разрешения и ошибок

Относительные имена файлов разрешаются сначала в каталоге исходного файла, а затем рабочем каталоге компилятора. Вложенные включают разрешение относительно их содержащего XML-файла. Выделите такие элементы, как /docs/tracking/*текст или узлы атрибутов.

Отсутствующие файлы, неправильно сформированные XML, недопустимые XPath и циклы создают диагностику. Допустимый XPath без совпадений сохраняет тег и добавляет комментарий без предупреждения. Обработка DTD и внешнее разрешение XML отключены; Элементы внешнего пространства include имен остаются обычным содержимым. См. справочник по синтаксису <include> XPath.

Унаследованная документация в инструментах

Чтобы избежать копирования описания базового элемента в каждое переопределение, используйте <inheritdoc/>:

[<AbstractClass>]
type TrackingBase() =
    /// <summary>Find the latest status of a shipment.</summary>
    abstract Status: trackingId: string -> string

type TrackingService() =
    inherit TrackingBase()
    /// <inheritdoc/>
    override _.Status trackingId = status trackingId

Средства F# 11 и FSharp.Compiler.Service предоставляют унаследованное описание.TrackingService.Status Компилятор покидает <inheritdoc/> создаваемый XML для интерпретации подчиненных инструментов. Обновление Core только не обновляет сопоставитель редактора.

Используйте верхний уровень <inheritdoc/>, а не тег, вложенный внутри <summary>. Явные cref, конструкторы и межязычные варианты сборки зависят от потребителя документации. Используйте полные идентификаторы XML-документации и проверьте целевое средство. См. <inheritdoc>справочную информацию.

Ограничения

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

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

См. также

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

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-11-06