代码文档¶
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
提示
通常建议使用描述性、第三人称现在时：返回这只独角兽的角的数量（而不是命令式 返回这只独角兽的角的数量）。
标记¶
链接¶
对其他 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"
警示¶
支持几个警示关键字来视觉上突出显示问题、笔记和/或可能出现的问题。
BUGDEPRECATEDEXPERIMENTALFIXMENOTEOPTIMIZETODOWARNING
警示关键字必须是其所在行的第一个词，并且必须全部大写。为了可读性，建议在后面添加可选的冒号。
# 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