Бөлісу құралы:

Документируйте код с помощью 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-файле документации. Ссылки 'См. также' обычно отображаются в нижней части страницы документации.

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

Синтаксис тега Описание
<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

Ограничения

Некоторые функции 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-документации в коде F#.

  • Включите параметр --warnon:3390 в коде, чтобы обеспечить допустимость XML-документации.

  • Рассмотрите возможность добавления файлов подписи для разделения длинных комментариев xml-документации от реализации.

  • Для обеспечения согласованности все общедоступные типы и их члены должны быть задокументированы. Если вы должны сделать это, сделайте все это.

  • Как минимум, модули, типы и их члены должны иметь обычный /// комментарий или тег <summary>. Откроется окно подсказки автозаполнения в средствах редактирования F#.

  • Текст документации должен быть написан с использованием полных предложений, заканчивающихся полными точками.

См. также

  • Last updated on