Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI - Джордж Дитрих

Type также можно использовать для отображения типа определенного значения.

Другая причина использования синтаксиса значения # => — возможность использования будущих инструментов, которые могли бы запускать пример кода и гарантировать, что выходные данные соответствуют ожидаемым выходным данным, что в конечном итоге приведет к более надежной и надежной документации.

В некоторых случаях вы можете подчеркнуть конкретное предложение, чтобы обозначить, что что-то необходимо исправить, или предупредить читателя о чем-то. Для этой цели можно использовать несколько ключевых слов-предупреждений, например:

# Runs the application.

#

# DEPRECATED: Use '#execute' instead.

def run; end

В предыдущем примере будет создана документация, которая выглядит следующим образом:

Рисунок 15.2 - Пример использования относительно

Ключевое слово предупреждения должно быть первым словом в строке и должно быть написано заглавными буквами. Двоеточие не является обязательным, но рекомендуется для удобства чтения.

Совет

См. https://crystal-lang.org/reference/syntax_and_ semantics/documenting_code.html#admonitions для получения полного списка ключевых слов предупреждения.

В предыдущем примере мы использовали предупреждение DEPRECATED для обозначения устаревшего метода. Однако это влияет только на сгенерированную документацию и не поможет пользователям идентифицировать устаревшие методы/типы, если они не просматривают документацию.

В случаях, когда вы хотите полностью объявить устаревшим тип или метод, предлагается использовать устаревшую аннотацию (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:

Важное замечание

Наследование документации работает только с экземплярами и методами, не являющимися конструкторами.

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

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

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

Подобно команде crystal spec, о которой мы узнали в Главе 14 «Тестирование», существует также команда crystal docs. Наиболее распространенный сценарий генерации кода — в контексте сегмента. В этом случае все, что вам нужно сделать для создания документации, — это запустить crystal docs. Это обработает весь код в src/ и выведет сгенерированный веб-сайт в каталоге docs/ в корне проекта. Отсюда вы можете открыть docs/index.html в своем браузере, чтобы просмотреть созданный файл. Будущие вызовы crystal docs перезапишут предыдущие файлы.

Мы также можем передать этой команде явный список файлов; например, crystal docs one.cr two.cr three.cr. Это создаст документацию для кода внутри всех этих файлов или требуемую для них. Вы можете использовать это для включения внешнего кода в сгенерированную документацию. Например, предположим, что у вас есть проект, который зависит от двух других сегментов в том же пространстве имен. Вы можете передать основной файл точки входа для каждого проекта в crystal docs, в результате чего будет создан веб-сайт, содержащий документацию для всех трех проектов. Это будет выглядеть примерно так: crystal docs lib/project1/src/main.cr lib/project2/src/main.cr src/main.cr. Возможно, потребуется изменить порядок, чтобы он соответствовал требованиям project1 и project2 в src/main.cr.

Предоставление файлов для использования вручную требуется, если вы не используете команду в контексте сегмента,