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

Независимо от того, насколько хорошо реализован shard, если пользователь не знает, как его использовать, он не сможет использовать его в полной мере или полностью откажется. Хорошо документированный код может быть так же важен, как и хорошо написанный или хорошо протестированный код. Как предлагает https://documentation.divio.com, правильная документация для программного продукта должна охватывать четыре отдельные области:

• Учебники

• Практические руководства

• Пояснения

• Использованная литература

Каждая из этих областей позволяет вам использовать документацию в зависимости от того, что вы хотите сделать — например, хотите решить конкретную проблему или выяснить параметры конкретного метода. Хотя первые три лучше всего реализуются с помощью кода, Crystal поставляется с некоторыми простыми в использовании функциями документирования кода, которые могут сделать создание справочной документации довольно безболезненным.

В этой главе мы рассмотрим следующие темы:

• Документирование кода Crystal.

• Директивы документации

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

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

Технические требования

Для этой главы вам понадобится работающая установка Crystal.

Инструкции по настройке Crystal см. в Главе 1 «Введение в Crystal».

Все примеры кода для этой главы можно найти в папке Chapter 15 репозитория GitHub этой книги: https://github.com/PacktPublishing/Crystal-Programming/tree/main/Chapter15.

Документирование кода Crystal

Комментарии к коду, добавляемые к типам, методам, макросам и константам, считаются комментариями к документации. Компилятор позволяет нам извлечь документацию для создания веб-сайта HTML и ее представления. Мы вернемся к этому позже в этой главе.

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

# This comment is not associated with MyClass.

# A summary of what MyClass does.

class MyClass; end

В этом примере есть два комментария: один связан с MyClass, а другой — нет. Первый абзац следует использовать в качестве резюме, определяющего назначение и функциональность элемента. Первый абзац включает в себя весь текст, вплоть до точки или пустой строки комментария, как показано здесь:

# This is the summary

# this is still the summary

#

# This is not the summary.

def foo; end

# This is the summary.

# This is no longer the summary.

def bar; end

Здесь метод #foo имеет многострочное резюме, которое заканчивается пустой новой строкой. С другой стороны, метод #bar использует точку для обозначения конца сводки и начала тела. Crystal генерирует документацию HTML и JSON на основе комментариев к документу. Подробнее о том, как на самом деле генерировать документацию, читайте далее в этой главе, а пока давайте просто посмотрим, как она будет выглядеть:

Краткое описание метода

bar

   Это краткое изложение.

foo

   Это резюме, это все еще резюме

Подробности метода

# def bar

   Это краткое изложение. Это уже не резюме.

# def foo

   Это краткое изложение, это еще не краткое изложение

   Это не резюме.

Рисунок 15.1 - Созданная документация метода

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

Привязка функции API

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

# Creates and returns a default instance of 'MyClass'.

def create : MyClass; end

Эти элементы затем автоматически разрешаются и преобразуются в ссылки при создании документации. Объекты в одном пространстве имен могут быть связаны с относительными именами:

• Мы можем использовать #foo для ссылки на метод экземпляра.

• Мы можем использовать .new для ссылки на метод класса.