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

• Мы можем использовать 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 для обозначения значения чего-либо в блоке кода. # : 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.