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

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

В следующей главе мы рассмотрим еще одну вещь, которая не менее важна, чем тесты, — как документировать ваш код/проект.

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

Независимо от того, насколько хорошо реализован 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 для ссылки на метод класса.

• Мы можем использовать MyClass для ссылки на другой тип или константу.

Функции, определенные в других пространствах имен, должны использовать свои полные пути; то есть MyOtherClass#foo, MyOtherClass.new и MyOtherClass::CONST соответственно. Определенные перегрузки также можно связать с помощью полной подписи, например #increment или #increment(by).

Если метод имеет тип возвращаемого значения или параметр имеет ограничение типа, Crystal автоматически свяжет их со связанным типом, если эти типы определены в одном проекте. Типы, определенные в стандартной библиотеке Crystal или во внешних сегментах, по умолчанию не связаны.

Если вы хотите добавить дополнительную документацию к параметру метода, рекомендуется выделить имя параметра курсивом, например:

# Returns of sum of *value1* and *value2*.

def add(value1 : Int32, value : Int32); end

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

Форматирование

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

# ## Example

#

# '''

# value = 2 + 2 => 4

# value # : Int32

# '''

module MyModule; end

Приведенный выше код создает подзаголовок с границей кода. По умолчанию языком ограничения является Crystal, но его можно переопределить, явно пометив язык, который вы хотите использовать, например '''yaml. Также распространенной практикой является использование # => value для обозначения значения чего-либо в блоке кода. # :