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

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.