Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI - Джордж Дитрих
Шрифт:
Интервал:
Закладка:
В следующей главе мы рассмотрим еще одну вещь, которая не менее важна, чем тесты, — как документировать ваш код/проект.
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 для обозначения значения чего-либо в блоке кода. # :
