文档指南¶ ↑

本指南讨论了在 Ruby 核心和 Ruby 标准库中记录类、模块和方法的建议。

生成文档¶ ↑

大多数 Ruby 文档都位于源文件中，并以 RDoc 格式编写。

某些页面位于 doc 文件夹下，可以使用 .rdoc 或 .md 格式编写，具体取决于文件扩展名。

要在 {build folder}/.ext/html 目录中生成 HTML 格式的文档更改输出，请在构建目录中运行以下命令

make html

如果您没有构建目录，请按照快速入门指南进行到第 4 步。

然后，您可以通过在浏览器中打开 {build folder}/.ext/html/index.html 文件来预览您的更改。

目标¶ ↑

Ruby 文档的目标是在最短的时间内传达最重要和最相关的信息。读者应该能够快速了解主题代码的用途以及如何使用它。

提供的信息太少是不好的，但是提供不重要的信息或不必要的示例也不好。请自行判断用户需要了解哪些信息。

通用准则¶ ↑

• 请记住，读者可能不精通英语。

• 编写简短的陈述句或祈使句。

• 将句子分组为（理想情况下是简短的）段落，每个段落涵盖一个主题。

• 使用标题组织材料。

• 使用链接引用权威和相关的来源。

• 使用简单动词时态：一般现在时、一般过去时、一般将来时。

• 使用简单的句子结构，而不是复合或复杂的结构。

• 避免

  • 过多的逗号分隔短语；考虑使用列表。

  • 习语和特定于文化的引用。

  • 过度使用标题。

  • 在 C 源文件中使用与 US-ASCII 不兼容的字符；请参阅下面的字符。

字符¶ ↑

在 C 源文件中仅使用与 US-ASCII 兼容的字符。（如果您使用其他字符，Ruby CI 会温和地提醒您。）

如果想将与 ASCII 不兼容的字符放入 C 编码的类、模块或方法的文档中，可以使用涉及新文件 doc/*.rdoc 的解决方法

• 对于类 Foo（在文件 foo.c 中定义），创建文件 doc/foo.rdoc，声明 class Foo; end，并将类文档放在该声明之上

  # Documentation for class Foo goes here.
  class Foo; end
  

• 同样，对于模块 Bar（在文件 bar.c 中定义），创建文件 doc/bar.rdoc，声明 module Bar; end，并将模块文档放在该声明之上

  # Documentation for module Bar goes here.
  module Bar; end
  

• 对于方法，情况有所不同。如上所述记录方法会禁用渲染文档中的“单击以切换源代码”功能。

  因此，最好使用文件包含

  • 保留 C 代码中的 call-seq。

  • 使用文件包含（:include:）从 .rdoc 文件中包含文本。

  示例

  /*
   *  call-seq:
   *    each_byte {|byte| ... } -> self
   *    each_byte               -> enumerator
   *
   *  :include: doc/string/each_byte.rdoc
   *
   */

RDoc¶ ↑

Ruby 使用 RDoc 进行文档化。有关 RDoc 语法和功能的信息，请参阅RDoc 标记参考。

来自 irb 的输出¶ ↑

对于代码示例，请考虑使用交互式 Ruby，irb。

对于包含 irb 输出的代码示例，请考虑在连续的行中对齐 # => ...。对齐有时可以帮助提高可读性

a = [1, 2, 3] #=> [1, 2, 3]
a.shuffle!    #=> [2, 3, 1]
a             #=> [2, 3, 1]

标题¶ ↑

使用标题组织类或模块的冗长讨论。

不要在方法或常量的文档中使用正式标题。

在极少数情况下，如果需要在方法或常量的文档中使用类似标题的结构，请使用粗体文本作为伪标题。

空行¶ ↑

空行开始一个新的段落。

代码块或列表的前后都应该有空行。这对于 HTML 输出是不必要的，但有助于 ri 输出。

方法名¶ ↑

对于文本中的方法名

• 对于当前类或模块中的方法，单例方法使用双冒号，实例方法使用井号标记：::bar，baz。

• 否则，请包含类或模块名称，并为单例方法使用点，为实例方法使用井号标记：Foo.bar，Foo#baz。

嵌入的代码和命令¶ ↑

嵌入在运行文本中的代码或命令（即，不在代码块中）应标记为等宽字体。

作为简单字符串的代码应包括引号。

自动链接¶ ↑

大多数情况下，类、模块或方法的名称是自动链接的

- Float.
- Enumerable.
- File.new
- File#read.

渲染为

• Float.

• Enumerable.

• File.new

• File#read.

一般来说，不应禁止 RDoc 的自动链接。例如，我们应该只编写普通的 *Float*（它是自动链接的）

Returns a Float.

渲染为

返回一个 Float。

但是，当所讨论的单词不引用 Ruby 实体时（例如，*Class* 或 *English* 的某些用法），*请务必*禁止自动链接

\Class variables can be tricky.

渲染为

Class 变量可能很棘手。

另外，当所讨论的单词引用当前文档时（例如，类 Float 的文档中的 *Float*），*请务必*禁止自动链接。

在这种情况下，您可以考虑强制该名称为等宽字体，这会禁止自动链接，并强调该词是一个类名

A +Float+ object represents ....

渲染为

Float 对象表示 ...

对于极少数、非常经常讨论的类，您可以考虑完全避免使用大写的类名。例如，对于某些关于数组的提及，您可以简单地写出小写的 *array*。

而不是

For an empty Array, ....

渲染为

对于一个空的 Array，....

您可以写

For an empty array, ....

渲染为

对于一个空数组，....

这种更随意的用法避免了自动链接和分散注意力的字体更改，并且不太可能引起混淆。

该原则可以特别有用地应用于

• 一个数组。

• 一个整数。

• 一个哈希。

• 一个字符串。

但是，只有在引用类的*实例*时才应应用它，并且*永远不要*在引用类本身时应用它。

显式链接¶ ↑

编写显式链接时，请遵循以下准则。

rdoc-ref 方案¶ ↑

使用 rdoc-ref 方案用于

• 核心文档中指向其他核心文档的链接。

• 核心文档中指向标准库包中文档的链接。

• 标准库包中指向同一标准库包中其他文档的链接。

请参阅链接中的“rdoc-ref 方案”部分。

基于 URL 的链接¶ ↑

使用完整的基于 URL 的链接用于

• 标准库文档中指向核心文档的链接。

• 标准库文档中指向不同标准库包中文档的链接。

这样做可确保即使在独立（与核心文档分开）构建包文档时，该链接也有效。

该链接应指向 docs.ruby-lang.org/en/master/ 中的目标。

对于指向站外文档的链接，也请使用完整的基于 URL 的链接。

变量名¶ ↑

变量的名称（在其 call-seq 中指定）应标记为等宽字体。

此外，对于临时变量的名称（即，仅在讨论中定义和使用的变量，例如 n），请使用等宽字体文本。

HTML 标签¶ ↑

一般来说，应避免使用 HTML 标签（即使在允许的格式中），因为 ri（Ruby 交互式参考工具）可能无法正确渲染它们。

表格¶ ↑

特别是，避免使用 HTML 标签 (<table> 等) 构建表格。

替代方案

• 使用空格和标点符号来格式化文本的原样文本块；请注意，文本标记将不会被识别。

  • 示例源代码。

  • 相应的输出。

• (仅限 Markdown 格式): Github Flavored Markdown (GFM) 表格，使用特殊格式化文本。

  • 示例 源代码。

  • 相应的输出。

文档化类和模块¶ ↑

类或模块文档的总体结构应为

• 概要

• 常见用法，附示例

• “此处内容”摘要（可选）

概要¶ ↑

概要是对类或模块的功能以及读者可能想要使用它的原因的简短描述。避免在概要中包含详细信息。

常见用法¶ ↑

展示类或模块的常见用法。根据类或模块的不同，此部分的长度和复杂性可能会有很大差异。

“此处内容”摘要¶ ↑

类或模块的文档可能包含“此处内容”部分。

指南

• 此部分标题为 What's Here。

• 考虑列出父类和任何包含的模块；如果存在，请考虑链接到它们的“此处内容”部分。

• 应列出左侧窗格目录中提到的所有方法（包括从另一个类扩展的任何方法）。

• 还可以列出属性（不包括在目录中）。

• 将方法显示为一个或多个项目符号列表中的项目

  • 以方法名称开头每个项目，后跟冒号和简短描述。

  • 如果该方法有别名，请在冒号前的括号中提及它们（并且不要单独列出别名）。

  • 检查渲染的文档以确定 RDoc 是否已识别该方法并链接到它；如果没有，请手动插入一个链接。

• 如果条目众多，请考虑将它们分组到带有标题的小节中。

• 如果有多个这样的小节，请考虑在主部分标题下方添加一个目录。

文档化方法¶ ↑

总体结构¶ ↑

方法文档的总体结构应为

• 调用序列（对于用 C 编写的方法）。

• 概要（简短描述）。

• 简短示例（可选）

• 详细信息和示例。

• 参数描述（如有必要）。

• 边界情况和异常。

• 相关方法（可选）。

调用序列（对于用 C 编写的方法）¶ ↑

对于用 Ruby 编写的方法，RDoc 会自动记录调用序列。

对于用 C 编写的方法，RDoc 无法确定该方法接受哪些参数，因此需要使用 RDoc 指令 {call-seq:}记录这些参数。

对于单例方法，请使用以下格式

class_name.method_name(method_args) {|block_args| ... } -> return_type

示例

*  call-seq:
*    Hash.new(default_value = nil) -> new_hash
*    Hash.new {|hash, key| ... } -> new_hash

对于实例方法，请使用以下格式（省略任何前缀，就像 RDoc 对 Ruby 编码的方法所做的那样）

method_name(method_args) {|block_args| ... } -> return_type

例如，在 Array 中，使用

*  call-seq:
*    count -> integer
*    count(obj) -> integer
*    count {|element| ... } -> integer

*  call-seq:
*    <=> other -> -1, 0, 1, or nil

对于二进制运算符风格的方法（例如，Array#&），请在 call-seq 中引用 self（例如，不是 array 或 receiver）

*  call-seq:
*    self & other_array -> new_array

参数

• 如果该方法不接受参数，请省略括号。

• 如果该方法接受可选参数

  • 使用 = （周围带空格的等号）分隔每个参数名称及其默认值。

  • 如果该方法在省略参数或使用显式参数时具有相同的行为，请使用带有可选参数的 call-seq。例如，使用

    *  call-seq:
    *    respond_to?(symbol, include_all = false) -> true or false

  • 如果省略参数或使用显式参数时行为不同，请使用带有单独行的 call-seq。例如，在 Enumerable 中，使用

    *  call-seq:
    *    max    -> element
    *    max(n) -> array

代码块

• 如果该方法不接受代码块，请省略代码块。

• 如果该方法接受代码块，则 call-seq 应包含 {|args| ... }，而不是 {|args| block } 或 {|args| code }。

• 如果该方法接受代码块，但在省略代码块时返回 Enumerator，则 call-seq 应同时显示两种形式

  *  call-seq:
  *    array.select {|element| ... } -> new_array
  *    array.select -> new_enumerator

返回类型

• 如果该方法可以返回多个不同的类型，请使用 “or” 分隔类型，并在必要时使用逗号。

• 如果该方法可以返回多个类型，请使用 object。

• 如果该方法返回接收器，请使用 self。

• 如果该方法返回相同类的对象，请仅当该对象不是 self 时才使用前缀 new_；示例：new_array。

别名

• 从 call-seq 中省略别名，除非该别名是运算符方法。如果在 call-seq 中同时列出常规方法和运算符方法，请在详细信息和示例部分中解释何时建议使用常规方法，何时建议使用运算符方法。

概要¶ ↑

接下来是概要，它是对方法的功能以及您为什么要使用它的简短描述。理想情况下，这是一个句子，但对于更复杂的方法，可能需要整段。

对于 Array#count，概要为

返回指定元素的计数。

这很棒，因为它简短且具有描述性。避免在概要中记录过多信息，坚持为读者提供最重要的信息。

简短示例¶ ↑

对于文档较长的方法，请考虑添加一个“简短”段落，显示总结该方法用法的示例。

该段落可以回答一些用户的问题（而无需阅读长篇文档）；请参阅 Array#[] 和 Array#[]=。

详细信息和示例¶ ↑

大多数非平凡的方法都受益于示例，以及超出概要中给出的详细信息。在详细信息和示例部分中，您可以记录该方法如何处理不同类型的参数，并提供有关正确用法的示例。在本节中，重点介绍如何正确使用该方法，而不是该方法如何处理不正确的参数或边界情况。

并非方法的每个行为都需要一个示例。如果文档记录该方法返回 self，则无需提供显示返回值与接收器相同的示例。如果文档记录该方法返回 nil，则无需提供显示它返回 nil 的示例。如果详细信息提到对于某种参数类型，将返回一个空数组，则无需为此提供示例。

仅当示例为用户提供额外信息时才添加示例，如果示例提供与概要或详细信息中相同的信息，则不要添加示例。示例的目的不是证明详细信息所陈述的内容。

许多可以接受可选代码块的方法在给定代码块时会调用该代码块，但如果未给定代码块，则返回新的 Enumerator；在这种情况下，不要提供示例，但要说明事实（使用自动链接的大写 Enumerator）

*  With no block given, returns a new Enumerator.

参数描述（如有必要）¶ ↑

对于需要参数的方法，如果不是显而易见的，并且未在详细信息中明确提及或在示例中隐式显示，则可以提供有关支持的参数类型的详细信息。在讨论参数类型时，请使用简单的语言，即使不够精确，例如“级别必须是整数”，而不是“级别必须是可以转换为整数的对象”。绝大多数用法将使用预期类型，而不是显式转换为预期类型的参数，记录差异并不重要。

对于使用代码块的方法，如果它不是显而易见的、未在详细信息中明确提及且未在示例中隐式显示，则记录传递的参数类型可能很有用。

如果存在多个参数或代码块参数，请使用带标签的列表。

边界情况和异常¶ ↑

对于方法的边界情况，例如非典型用法，请简要提及行为，但不要提供任何示例。

仅在不明显的情况下才记录引发的异常。例如，如果您之前声明过参数类型必须是整数，则无需记录如果传递非整数则会引发 TypeError。除非这是一个常见情况，否则不要提供引发异常的示例，例如 Hash#fetch 引发 KeyError。

相关方法（可选）¶ ↑

在某些情况下，记录哪些方法与当前方法相关很有用。例如，Hash#[] 的文档可能会提及 Hash#fetch 作为相关方法，并且 Hash#merge 可能会提及 Hash#merge! 作为相关方法。

• 考虑哪些方法可能与当前方法相关，如果您认为读者会从中受益，请在方法文档末尾添加以“Related: ”开头的一行（例如，“Related: fetch.”）。

• 不要列出超过三个相关方法。如果您认为有三个以上的方法相关，请列出您认为最重要的三个方法。

• 考虑添加

  • 一个短语，表明相关方法与当前方法相似或不同。请参阅 Time#getutc 中的示例。

  • 说明相似之处和差异的示例代码。请参阅 Time#ctime, Time#inspect, Time#to_s 中的示例。

接受多种参数类型的方法¶ ↑

对于接受多种参数类型的方法，在某些情况下，单独记录不同的参数类型可能很有用。最好为您讨论的每种情况使用单独的段落。