Документация 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