Документация XML (F#)

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

Создание документации из комментариев

Поддержка создания документации из комментариев в языке F# реализована так же, как и в других языках платформы .NET Framework.Как и в других языках платформы .NET Framework, параметр компилятора -doc позволяет создать XML-файл, информацию из которого можно преобразовать в документацию с помощью специальной программы, например Sandcastle.Документация, созданная с помощью средств, предназначенных для использования со сборками, написанными на других языках платформы .NET Framework, обычно содержит представление интерфейсов API, основанное на скомпилированном виде конструкций языка F#.Если в этих средствах не предусмотрена специальная поддержка языка F#, созданная ими документация не отражает представление интерфейса API на языке F#.

Дополнительные сведения о создании документации из XML-кода см. в разделе Комментарии к XML-документации (Руководство по программированию на C#).

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

Существует два способа написания комментариев для XML-документации.Один — просто писать документацию непосредственно в комментариях, обозначенных тремя косыми чертами, без использования XML-тегов.В таком случае весь текст комментария рассматривается как сводная документация к конструкции кода, которая следует непосредственно за комментарием.Этот способ используют, если требуется написать только краткую сводку по каждой конструкции.Другой способ заключается в использовании XML-тегов для создания более структурированной документации.Этот второй способ позволяет писать отдельные примечания — краткую сводку, дополнительные замечания, документацию для каждого параметра, параметра типа и создаваемых исключений, а также описание возвращаемого значения.В следующей таблице описаны XML-теги, распознаваемые в XML-комментариях к коду на языке F#.

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

Пример

Описание

Ниже приведен типичный комментарий 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-тегов.В этом примере весь текст примечания рассматривается как сводка.Обратите внимание, что если не был явно указан тег сводки, не следует указывать другие теги, такие как теги param или returns.

Код

/// 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

См. также

Другие ресурсы

Справочник по языку F#

Параметры компилятора (F#)