Документы

В этой главе описывается, как правильно писать строки документации и как использовать все доступные функции scaladoc. Scaladoc расширяет возможности Markdown дополнительными функциями, такими как ссылки на определения API. Это можно использовать из статической документации и постов в блогах для создания смешиваемого контента.

Куда поместить строки документации

Комментарии Scaladoc идут перед элементами, к которым они относятся, в специальном блоке комментариев, который начинается с /** и заканчивается */, например:

/** Комментарий начинается здесь.
  * Левая "звезда", за которой следует пробел в каждой строке,
  * позволяет продолжить комментарий.
  *
  * Даже на пустых строках разрыва абзаца.
  *
  * Обратите внимание, что '*' в каждой строке выровнена
  * со вторым '*' в '/**' так, чтобы
  * левое поле находилось в том же столбце, где
  * первая строка и последующие.
  *
  * Комментарий закрывается с помощью '*' и обратного слэша.
  *
  * Если используются теги Scaladoc (@param, @group и т.д.),
  * не забудьте поместить их в отдельные строки без предшествующих им строк.
  *
  * Например:
  *
  * Рассчитать квадрат заданного числа
  *
  * @param d the Double to square
  * @return the result of squaring d
  */
 def square(d: Double): Double = d * d

В приведенном выше примере комментарий Scaladoc связан с методом square, поскольку он находится в исходном коде прямо перед ним.

Комментарии Scoladoc могут идти перед полями, методами, классами, трейтами, объектами. На данный момент scaladoc не поддерживает прямое решение для документирования пакетов. На гитхабе есть специальный issue, где можно проверить текущий статус проблемы.

Для первичных конструкторов класса, которые в Scala совпадают с определением самого класса, тег @constructor используется для указания комментария, помещаемого в документацию первичных конструкторов, а не в обзор класса.

Теги

Scoladoc использует теги @<tagname> для предоставления определенных подробностей полей в комментариях. Теги включают:

Теги, специфичные для класса

@constructor помещенный в комментарий класса, будет описывать первичный конструктор.

Теги, специфичные для метода

@return для детализации возвращаемого значения из метода (по одному на метод).

Теги метода, конструктора и/или класса

@throws какие исключения (если есть) может генерировать метод или конструктор.
@param детализация параметра метода или конструктора, предоставляется по одному @param для каждого параметра метода/конструктора.
@tparam детализация параметра типа для метода, конструктора или класса. Указывается по одному для каждого параметра типа.

Теги использования

@see ссылки на другие источники информации, такие как ссылки на внешние документы или связанные объекты в документации.
@note добавление примечания о предварительных или последующих условиях или любых других заметных ограничениях или ожиданиях.
@example предоставление примера кода или соответствующей документации.

Теги группировки

Эти теги хорошо подходят для больших типов или пакетов со многими элементами. Они позволяют организовать страницу Scoladoc в отдельные разделы, каждый из которых отображается отдельно в выбранном порядке.

Эти теги не включены по умолчанию! Необходимо передать флаг -groups в Scaladoc, чтобы включить их. В sbt это обычно выглядит примерно так:

Compile / doc / scalacOptions ++= Seq(
  "-groups"
)

Каждый раздел должен иметь идентификатор из одного слова, который используется во всех этих тегах, как показано ниже в group. По умолчанию этот идентификатор отображается как заголовок раздела документации, но можно использовать @groupname, чтобы указать более длинный заголовок.

Как правило, необходимо поместить @groupprio (и, возможно, @groupname и @groupdesc) в Scaladoc для самого пакета/trait/класса/объекта, описывая все группы и их порядок. Затем поместить @group в Scoladoc для каждого члена, указав, в какой группе он находится.

Члены, у которых нет тега @group, будут перечислены в результирующей документации как "Ungrouped".

@group <group> - пометить сущность как члена <group> группы.
@groupname <group> <name> - указание необязательного имени для группы. <name> отображается как заголовок группы перед её описанием.
@groupdesc <group> <description> - добавление необязательного описания для отображения под именем группы. Поддерживает многострочный форматированный текст.
@groupprio <group> <priority> - управление порядком группы на странице. По умолчанию 0. Несгруппированные элементы имеют неявный приоритет 1000. Используются значения от 0 до 999, чтобы задать положение относительно других групп. Низкие значения появятся перед высокими значениями.

Другие теги

@author - предоставление информации об авторе для следующего объекта.
@version - версия системы или API, частью которой является этот объект.
@since - похож на @version, но определяет систему или API, в котором эта сущность была впервые определена.
@deprecated - помечает объект как устаревший, предоставляя как замену реализации, которую следует использовать, так и версию/дату, когда этот объект устарел.
@syntax <name> - позволяет изменить парсер для docstring. Синтаксис по умолчанию — markdown, однако можно изменить его с помощью этой директивы. В настоящее время доступны синтаксисы markdown или wiki. Пример использования: @syntax wiki.

Макросы

@define <name> <definition> позволяет использовать $name в других комментариях Scaladoc в том же исходном файле, который будет заменен на <definition>.

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

Аналогично, если @param, @tparam, @return и другие теги сущностей опущены, но доступны из суперкласса, эти комментарии будут использоваться.

Явный

Для явного наследования комментариев используется тег @inheritdoc.

Разметка

Scaladoc предоставляет два анализатора синтаксиса: markdown (по умолчанию) или wikidoc. В Scaladoc по-прежнему можно встраивать теги HTML (как и в Javadoc), но в большинстве случаев это не обязательно, поскольку вместо этого может использоваться разметка.

Markdown

Markdown использует вариант commonmark с двумя пользовательскими расширениями:

wikidoc - ссылки для удобства
wikidoc - кодовые блоки с синтаксисом фигурных скобок

Wikidoc

Wikidoc — это синтаксис, используемый для scala2 scaladoc. Он поддерживается из-за многих существующих исходных кодов, однако не рекомендуется его использование в новых проектах. Синтаксис вики можно включить с помощью глобального флага -comment-syntax wiki или с помощью @syntax wiki директивы в строке документации.

Некоторые из стандартных доступных разметки:

`monospace`
''italic text''
'''bold text'''
__underline__
^superscript^
,,subscript,,
[[entity link]], e.g. [[scala.collection.Seq]]
[[https://external.link External Link]], e.g. [[https://scala-lang.org Scala Language Site]]

Другие примечания по форматированию

Абзацы начинаются с одной (или нескольких) пустых строк. * на полях для комментария допустимо (и должно быть включено), но в противном случае строка должна быть пустой.
Заголовки определяются окружающими символами = с большим количеством = для обозначающих подзаголовков. Например =Heading=, ==Sub-Heading== и т.д.
Блоки списка представляют собой последовательность элементов списка с одинаковым стилем и уровнем, без прерываний от других стилей блоков. Неупорядоченные списки можно маркировать с помощью -, нумерованные списки можно обозначать с помощью 1., i., I. или a. для различных стилей нумерации. В обоих случаях должно быть дополнительное пространство впереди, а большее пространство создает подуровень.

Разметка для блоков списка выглядит так:

/** Вот неупорядоченный список:
  *
  *   - Первый элемент
  *   - Второй элемент
  *     - Подпункт ко второму
  *     - Еще один подпункт
  *   - Третий пункт
  *
  * Вот упорядоченный список:
  *
  *   1. Первый пронумерованный элемент
  *   1. Второй номер позиции
  *     i. Подпункт ко второму
  *     i. Еще один подпункт
  *   1. Третий пункт
  */

Связывание с API

Scaladoc позволяет ссылаться на документацию по API с помощью ссылок в стиле Wiki. Связать с scala.collection.immutable.List так же просто, как [[scala.collection.immutable.List]]. Для получения дополнительной информации о точном синтаксисе см. Ссылки.

Ссылки:

Scaladoc Guide