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

  • Статья

Документацию можно создать из примечаний с тройной косой чертой (//) в 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 она используется.

Рекомендации

Документирование кода рекомендуется по многим причинам. Ниже приведены некоторые рекомендации, общие сценарии использования и сведения, которые следует знать при использовании тегов xml-документации в коде F#.

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

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

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

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

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

См. также