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 для обозначения значения чего-либо в блоке кода. # : 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 для обозначения устаревшего метода. Однако это влияет только на сгенерированную документацию и не поможет пользователям идентифицировать устаревшие методы/типы, если они не просматривают документацию.