程式碼文件¶

API 功能的文件可以直接寫在各功能定義之前的程式碼註解中。

預設情況下，所有公開的方法、巨集、類型和常數都被視為 API 文件的一部分。

提示

編譯器指令 crystal docs 會自動擷取 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

提示

通常建議使用描述性的第三人稱現在式：Returns the number of horns this unicorn has（而不是祈使句 Return the number of horns this unicorn has）。

標記¶

連結¶

對其他 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`¶

如果兩個連續定義的功能具有相同的說明文件，可以使用 :ditto: 從先前的定義複製相同的註解區塊。

# Returns the number of horns.
def horns
  horns
end

# :ditto:
def number_of_horns
  horns
end

指示詞需要單獨一行，但可以在其他行中新增其他說明文件。:ditto: 指示詞會簡單地由先前註解區塊的內容取代。

`nodoc`¶

可以使用 :nodoc: 指示詞從 API 文件中隱藏公開功能。私有和受保護的功能永遠隱藏。

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