Документирование кода

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

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

Связь с определением

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

# This comment is not associated with the class.

# First line of documentation for class Unicorn.
# Second line of documentation for class Unicorn.
class Unicorn
end

Формат

Комментарии к документации поддерживают форматирование Markdown.

Первый абзац комментария к документации считается кратким описанием. В нем следует лаконично изложить назначение и функциональность.

Дополнительные сведения и инструкции по использованию следует приводить в следующих абзацах.

Например:

# Returns the number of horns this unicorn has.
#
# Always returns `1`.
def horns
  1
end

Разметка

Ссылки

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

class Unicorn
  # Creates a new `Unicorn` instance.
  def initialize
  end
end

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

• На методы экземпляра ссылаются с помощью префикса в виде решетки: #horns.
• На методы класса ссылаются с помощью префикса в виде точки: .new.
• На константы и типы ссылаются по имени: Unicorn.

На функции в других пространствах имен ссылаются по полному пути к типу: Unicorn#horns, Unicorn.new, Unicorn::CONST.

Разные перегрузки метода можно различать по полной сигнатуре .new(name), .new(name, age).

Параметры

При упоминании параметров рекомендуется писать их имена курсивом (*italicized*):

# Creates a unicorn with the specified number of *horns*.
def initialize(@horns = 1)
  raise "Not a unicorn" if @horns != 1
end

Примеры кода

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

# Example:
# ```
# unicorn = Unicorn.new
# unicorn.horns # => 1
# ```
class Unicorn
end

Чтобы обозначить блок кода как обычный текст, необходимо явно указать соответствующий тег.

# Output:
# ```plain
# "I'm a unicorn"
# ```
def say
  puts "I'm a unicorn"
end

Можно также использовать теги других языков.

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

1 + 2             # => 3
Unicorn.new.speak # => "I'm a unicorn"

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

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

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

Ключевые слова предупреждений должны быть первым словом в соответствующей строке и записываться заглавными буквами. Для удобства чтения рекомендуется ставить после них двоеточие.

# Makes the unicorn speak to STDOUT
#
# NOTE: Although unicorns don't normally talk, this one is special
# TODO: Check if unicorn is asleep and raise exception if not able to speak
# TODO: Create another `speak` method that takes and prints a string
def speak
  puts "I'm a unicorn"
end

# Makes the unicorn talk to STDOUT
#
# DEPRECATED: Use `speak`
def talk
  puts "I'm a unicorn"
end

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

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

Директивы

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

ditto

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

# Returns the number of horns.
def horns
  horns
end

# :ditto:
def number_of_horns
  horns
end

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

nodoc

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

# :nodoc:
class InternalHelper
end

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

inherit

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

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

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

Например:

abstract class Animal
  # Returns the name of `self`.
  abstract def name : String
end

class Unicorn < Animal
  def name : String
    "unicorn"
  end
end

Документация для Unicorn#name будет выглядеть так:

Description copied from class `Animal`

Returns the name of `self`.

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

Например:

abstract class Parent
  # Some documentation common to every *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 будет выглядеть так:

Some documentation specific to *id*'s usage within `Child`.

Some documentation common to every *id*.

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

# 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*.
  def initialize(@horns = 1)
    raise "Not a unicorn" if @horns != 1
  end

  # Returns the number of horns this unicorn has
  #
  # ```
  # Unicorn.new.horns # => 1
  # ```
  def horns
    @horns
  end

  # :ditto:
  def number_of_horns
    horns
  end

  # Makes the unicorn speak to STDOUT
  def speak
    puts "I'm a unicorn"
  end

  # :nodoc:
  class Helper
  end
end