Спецификация. Документирование кода.

[Sorcus]

Документация для API функций может быть описана в коде с помощью комментариев перед определением самих функций.
По умолчанию все публичные методы, макросы, типы и константы являются основной частью API документации.

С помощью команды crystal docs можно сгенерировать сайт с API документацией.

Ассоциации​

Комментарии для документации должны располагаться перед определением функции.
Несколько строк комментариев объединяются в единый блок.
Пустая строка разрывает отношение между комментарием и функцией.

# Этот комментарий существует сам по себе

# Первая строка документации для класса Unicorn.
# Вторая строка документации для класса Unicorn.
class Unicorn
end

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

Поддерживается форматирование комментариев с помощью Markdown.
Первый параграф комментария описывает самую суть (назначение, функционал).
Подробности и примеры использования описываются в других параграфах.

Например:

# Возвращает кол-во рогов у единорога.
#
# Всегда возвращает `1`.
def horns
  1
end

Разметка​

Ссылки​

Ссылаться на другие API функции можно с помощью апострофа `.
Содержимое, заключённое в апострофы, будет автоматически преобразовано в ссылки на соответствующий функционал.

class Unicorn
  # Создаёт экземпляр класса `Unicorn`
  def initialize
  end
end

Функции в текущем, документируемом, пространстве имён могут быть доступны с помощью относительных имён:

• Методы экземпляра класса описываются как #horns
• Методы класса описываются как .new
• Константы и типы описываются своим именем Unicorn

Функции в других пространствах имён описываются с помощью полного пути: Unicorn#horns, Unicorn.new, Unicorn::CONST.
Перегрузка операторов может быть идентифицирована полным описанием метода: .new(name), .new(name, age).

Параметры​

Ссылаясь на параметры, рекомендуется делать их наклонным шрифтом с помощью *.

# Создаёт единорога с указанным кол-ом рогов (*horns*).
def initialize(@horns = 1)
  raise "Не единорог" if @horns != 1
end

Примеры кода​

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

# Пример:
# ```
# unicorn = Unicorn.new
# unicorn.horns # => 1
# ```
class Unicorn
end

Чтобы обозначить код как текст, нужно соответствующим образом его тегировать.

# Вывод:
# ```plain
# "Я единорожка"
# ```
def say
  puts "Я единорожка"
end

Тегировать можно любым другим языком.
Чтобы показать значение выражения внутри блока с кодом, используй # =>

1 + 2                       # => 3
Unicorn.new.speak # => "Я единорожка"

Предупреждения​

Несколько ключевых слов-предупреждений используется для визуальной подсветки проблем, заметок и/или каких-то вопросов.

• BUG
• DEPRECATED
• EXPERIMANTAL
• FIXME
• NOTE
• OPTIMIZE
• TODO
• WARNING

Слова-предупреждения должны быть первыми в строке и написаны в верхнем регистре.
Опциональный символ : желателен для повышения читабельности.

# Пусть единорог говорит в STDOUT
#
# NOTE: Обычно единороги не говорят, но этот особенный
# TODO: Проверить спит ли единорог. Выбросить исключение, если не может говорить
# TODO: Создать другой метод `speak`, который принимает на вход строку и печатает её
def speak
  puts "Я единорожка"
end

# Пусть единорог говорит в STDOUT
#
# DEPRECATED: Используй `speak`
def talk
  puts "Я единорожка"
end

Компилятор может сам добавлять некоторые слова-предупреждения в комментарии:

• Аннотация @[Deprecated] добавляет DEPRECATED.
• Аннотация @[Experimental] добавляет EXPERIMENTAL

Директивы​

Директивы указывают генератору документации, как интерпретировать документацию для определённых функций.

ditto​

Если 2 последовательные функции имеют одинаковое описание, :ditto: может использоваться для копирования комментария из предыдущего определения.

# Возвращает кол-во рогов.
def horns
  horns
end

# :ditto:
def number_of_horns
  horns
end

Директива должна располагаться на отдельной строке, но дополнительная документация может быть добавлена на другой строке.
Директива :ditto: заменяется содержимым предыдущего комментария.

nodoc​

Публичные функции могут быть скрыты из документации API с помощью директивы :nodoc:.
Приватные и защищённые функции всегда скрыты.

# :nodoc:
class InternalHelper
end

Эта директива должна быть расположена на первой строке в комментарии.
Ведущий пробел опционален. Следующие строки с комментариями могут использоваться для внутренней документации.

inherit​

См. `Наследование документации`

Наследование документации​

Если метод экземпляра класса не имеет комментария, но у родительского класса есть метод с такой же сигнатурой, документация наследуется из родительского метода.
Например:

abstract class Animal
  # Возвращает имя для `self`
  abstract def name : String
end

class Unicorn < Animal
  def name : String
    "единорог"
  end
end

Документация для Unicorn#name будет следующей:

Description copied from class `Animal`

Возвращает имя для `self`.

Дочерний метод может использовать :inherit: для принудительного копирования родительского комментария без "Description copied from ...".
:inherit: так же может использоваться для вставки родительского комментария в качестве дополнения к текущему.
Например:

abstract class Parent
  # Некоторая общая информация для каждого *id*.
  abstract def id : Int32
end

class Child < Parent
  # Некоторая специфичная информация для *id* внутри `Child`.
  #
  # :inherit:
  def id : Int32
    -1
  end
end

Результат для Child#id:

Некоторая специфичная информация для *id* внутри `Child`.

Некоторая общая информация для каждого *id*.

Наследование документации работает только для экземпляров класса.

Полный пример​

# Единорог это **легендарное животное** (смотри модуль `Legendary`), который
# был описан в античные времена как существо с длинным, закрученным
# рогом, растущим из его лба.
#
# Создать единорога:
#
# ```
# unicorn = Unicorn.new
# unicorn.speak
# ```
#
# Результат вызова метода:
#
# ```text
# "Я единорожка"
# ```
#
# Проверить кол-во рогов можно с помощью `#horns`.
class Unicorn
  include Legendary

  # Создать единорога с указанным кол-ом рогов (*horns*).
  def initialize(@horns = 1)
    raise "Не единорог" if @horns != 1
  end

  # Возвращает кол-во рогов у единорога
  #
  # ```
  # Unicorn.new.horns # => 1
  # ```
  def horns
    @horns
  end

  # :ditto:
  def number_of_horns
    horns
  end

  # Пусть единорог говорит в STDOUT
  def speak
    puts "Я единорожка"
  end

  # :nodoc:
  class Helper
  end
end