コードのドキュメント化¶

API機能のドキュメントは、それぞれの機能の定義の直前のコードコメントに記述できます。

デフォルトでは、すべてのpublicメソッド、マクロ、型、定数がAPIドキュメントの一部とみなされます。

ヒント

コンパイラコマンドcrystal docsは、APIドキュメントを自動的に抽出し、それを表示するためのウェブサイトを生成します。

書式¶

ドキュメントコメントは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)で識別できます。

パラメータ¶

パラメータを参照する場合、名前をイタリック体（*イタリック体*）で記述することをお勧めします。

# 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`¶

連続して定義された2つの機能が同じドキュメントを持っている場合、:ditto:を使用して、前の定義から同じドキュメントコメントをコピーできます。

# Returns the number of horns.
def horns
  horns
end

# :ditto:
def number_of_horns
  horns
end

ディレクティブは別の行にある必要がありますが、他の行にさらにドキュメントを追加できます。:ditto:ディレクティブは、前のドキュメントコメントの内容に置き換えられます。

`nodoc`¶

public機能は、:nodoc:ディレクティブを使用してAPIドキュメントから非表示にできます。privateおよびprotected機能は常に非表示になります。

# :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