Первый абзац комментария к документу считается его кратким изложением.
В нем должно быть кратко определено назначение и функциональность.
Дополнительные сведения и инструкции по использованию должны содержаться в последующих параграфах.
Напрмиер:
```crystal
# Возвращает количество рогов, которые есть у этого единорога.
#
# Всегда возвращает `1`.
def horns
1
end
```
Рекомендуется использовать в написании комментариев настоящее время от третьего лица:
"_Возвращает количество рогов, которые есть у этого единорога_".
## Разметка
### Linking
Ссылки на другие функции API могут быть заключены в знаки апострофа.
Они автоматически преобразуются в ссылки на соответствующую функцию.
```crystal
class Unicorn
# Создает новый экземпляр `Unicorn`.
def initialize
end
end
```
Правила поиска применяются те же, что и в Crystal code. К функциям в задокументированном в настоящее время пространстве имен можно получить доступ по относительными именами:
*На методы экземпляра ссылаются с помощью хэш-префикса: `#horns`.
*На методы класса ссылаются с помощью префикса точки: `.new`.
*На константы и типы ссылаются по их имени: `Unicorn`.
На объекты в других пространствах имен ссылаются с помощью полного пути к типу: `Unicorn#horns`, `Unicorn.new`, `Unicorn::CONST`.
Различные перегрузки метода могут быть идентифицированы по полной сигнатуре `.new(name)`, `.new(name, age)`.
### Параметры
При обращении к параметрам рекомендуется писать их название курсивом (`*выделено_курсивом*`):
```crystal
# Создает единорога с указанным количеством *рогов*.
def initialize(@horns = 1)
raise "Не единорог" if @horns != 1
end
```
### Примеры кода
Примеры кода могут быть размещены в блоках кода Markdown.
Если языковой тег не указан, блок кода считается кодом на языке Crystal.
```crystal
# Пример:
# ```
# unicorn = Unicorn.new
# unicorn.horns # => 1
# ```
class Unicorn
end
```
Чтобы обозначить блок кода как обычный текст, он должен быть явно помечен тегом.
```crystal
# Вывод:
# ```plain
# "Я единорог"
# ```
def say
puts "Я единорог"
end
```
Также можно использовать другие языковые теги.
Чтобы отобразить значение выражения внутри блоков кода, используйте `# =>`.
```crystal
1 + 2 # => 3
Unicorn.new.speak # => "Я единорог"
```
### Предупреждения
Поддерживаются несколько ключевых слов-предупреждений для визуального выделения проблем,
заметок и/или возможных проблем.
*`BUG`
*`DEPRECATED`
*`EXPERIMENTAL`
*`FIXME`
*`NOTE`
*`OPTIMIZE`
*`TODO`
*`WARNING`
Ключевые слова с предупреждением должны быть первыми в соответствующей строке и должны быть написаны заглавными буквами. Необязательное завершающее двоеточие предпочтительнее для удобства чтения.
```crystal
# Заставляет единорога говорить в STDOUT
#
# NOTE: Хотя единороги обычно не разговаривают, этот особенный
# TODO: Проверить, спит ли единорог, и вызвать исключение, если он не может говорить
# TODO: Создать другой метод `speak`, который принимает и печатает строку
def speak
puts "Я единорог"
end
# Заставляет единорога говорить в STDOUT
#
# DEPRECATED: Используйте `speak`
def talk
puts "Я единорог"
end
```
Компилятор неявно добавляет некоторые предостережения к комментариям документации:
Когда метод экземпляра не имеет комментария документации,
но метод с такой же сигнатурой существует в родительском типе,
документация наследуется от родительского метода.
Пример:
```crystal
abstract class Animal
# Возвращает имя из `self`.
abstract def name : String
end
class Unicorn <Animal
def name : String
"единорог"
end
end
```
Документация для `Unicorn#name` была бы:
```text
Описание скопировано из класса `Animal`
Возвращает имя из `self`.
```
The child method can use `:inherit:` to explicitly copy the parent's documentation, without the `Description copied from ...` text. `:inherit:` can also be used to inject the parent's documentation into additional documentation on the child.
Пример:
```crystal
abstract class Parent
# Некоторая документация, общая для каждого *id*.
abstract def id : Int32
end
class Child <Parent
# Some documentation specific to *id*'s usage within `Child`.
#
# :inherit:
def id : Int32
-1
end
end
```
Документация для `Child#id` была бы:
```text
Some documentation specific to *id*'s usage within `Child`.
Some documentation common to every *id*.
```
> Наследование документации работает только с методами экземпляра, не являющимися конструкторами.
## Полный пример
```crystal
# A unicorn is a **legendary animal** (see the `Legendary` module) that has been
# described since antiquity as a beast with a large, spiraling horn projecting
# from its forehead.
#
# To create a unicorn:
#
# ```
# unicorn = Unicorn.new
# unicorn.speak
# ```
#
# The above produces:
#
# ```text
# "I'm a unicorn"
# ```
#
# Check the number of horns with `#horns`.
class Unicorn
include Legendary
# Creates a unicorn with the specified number of *horns*.
