В случаях, когда вы хотите полностью объявить устаревшим тип или метод, предлагается использовать устаревшую аннотацию (https://crystal-lang.org/api/Deprecated.html). Эта аннотация добавит для вас предупреждение DEPRECATED, а также предоставит предупреждения компилятора, чтобы конечному пользователю было более очевидно, что является устаревшим.
В дополнение к различным предупреждениям Crystal также включает несколько директив, которые можно использовать в комментариях к документации и влиять на ее создание. Давайте посмотрим на них дальше.
Директивы документации
Crystal также предоставляет несколько директив, которые сообщают генератору документации, как ему следует обращаться с документацией для конкретной функции. К ним относятся следующие:
• :ditto:
• :nodoc:
• :inherit:
Давайте подробнее посмотрим, что они делают.
Ditto
Директиву :ditto: можно использовать для копирования документации из предыдущего определения, например:
# Returns the number of items within this collection.
def size; end
# :ditto:
def length; end
# :ditto:
#
# Some information specific to this method.
def count; end
При создании документации #length будет иметь то же предложение, что и #size. #count также будет содержать это предложение в дополнение к другому предложению, специфичному для этого метода. Это может помочь уменьшить дублирование ряда связанных методов.
Nodoc
Документация создается только для общедоступного API. Это означает, что частные и защищенные функции по умолчанию скрыты. Однако в некоторых случаях тип или метод не могут быть частными, но их все равно не следует рассматривать как часть общедоступного API. Директиву :nodoc: можно использовать, чтобы скрыть общедоступные функции из документации, например:
# :nodoc:
#
# This is an internal method.
def internal_method; end
Эта директива должна находиться в первой строке. Следующие строки по-прежнему могут использоваться для внутренней документации.
Inherit
Наследование меняет способ обработки документации в некоторых контекстах. Например, если метод родительского типа имеет комментарий к документации, он автоматически копируется в дочерний метод, при условии, что дочерний метод имеет ту же сигнатуру и не имеет комментариев к документации. Ниже приведен пример этого:
abstract class Vehicle
# Returns the name of 'self'.
abstract def name
end
class Car < Vehicle
def name
"car"
end
end
Здесь документация Car#name будет следующей:
# def nameОписание скопировано из класса Vehicle.
Возвращает имя seif.
Рисунок 16.3 - Поведение наследования документации по умолчанию
Эта функция дает понять, откуда взята документация, но в некоторых случаях вы можете захотеть опустить текст «Описание, скопированное из...». Этого можно добиться, применив директиву :inherit: к дочернему методу, например:
class Truck < Vehicle
# Some documentation specific to *name*'s usage within 'Truck'.
#
# :inherit:
def name : String
"truck"
end
end
В этом случае, поскольку использовалась директива :inherit:, документация по Truck#name будет выглядеть следующим образом:
# def name : StringНекоторая документация, касающаяся использования имени в Truck.
Возвращает имя seif.
Рисунок 15.4 - Поведение наследования документации с помощью :inherit:
Наследование документации работает только с экземплярами и методами, не являющимися конструкторами.
Эта функция может быть невероятно полезна для уменьшения дублирования при наличии большого количества дочерних типов или реализаций интерфейса.
Хотя вся документация, которую мы написали, важна, она не принесет много пользы, если пользователю нужно будет взглянуть на сам код, чтобы увидеть его. Чтобы сделать его полезным и доступным для пользователей, его необходимо сгенерировать. Давайте научимся, как это сделать.