类 RDoc::MarkupReference

类 RDoc::MarkupReference 仅存在是为了提供一个合适的场所来存放 RDoc 标记的参考文档。

此类中定义的所有对象（类、模块、方法、别名、属性和常量）仅用于说明 RDoc 标记，没有其他合法用途。

RDoc 标记参考 ↑

注意

  • 此参考中的示例是 Ruby 代码和注释；某些与其他来源（如 C 代码和注释）的不同之处已注明。

  • 显示渲染后的 HTML 输出的示例在块引用中显示该输出

    渲染后的 HTML

    一些内容

RDoc 生成的文档源自并受以下内容控制

  • 在某些定义之前出现的单行或多行注释；请参阅 注释中的标记。

  • 尾部注释中的 RDoc 指令（与代码在同一行）；请参阅 :nodoc:、:doc: 和 :notnew:。

  • 单行注释中的 RDoc 指令；请参阅其他 指令。

  • Ruby 代码本身（但不包括 C 代码）；请参阅 从 Ruby 代码派生的文档。

注释中的标记 ↑

注释中标记的处理方式因文件类型而异

  • .rb（Ruby 代码文件）：标记从 Ruby 注释中解析。

  • .c（C 代码文件）：标记从 C 注释中解析。

  • .rdoc（RDoc 文本文件）：标记从整个文件中解析。

与 Ruby 类、模块、方法、别名、常量或属性关联的注释将成为该定义对象的文档。

  • 在 Ruby 文件中，该注释紧接在对象定义之前。

  • 在 C 文件中，该注释紧接在实现方法的函数之前，或者紧接在对象定义之前。

在 Ruby 或 C 文件中，RDoc 忽略不位于对象定义之前的注释。

在 RDoc 文件中，文本与任何代码对象无关，但可能会（取决于文档的构建方式）成为一个单独的页面。

此页面上的几乎所有示例都是 RDoc 样式的；也就是说，它们没有像 Ruby # 或 C /* ... */ 这样的注释标记。

边距 ↑

在多行注释中，RDoc 会查找注释的自然左边界，该边界将成为注释的基准边界，也是注释的初始当前边界。

当前边界可能会发生变化，例如在列表中。

块 ↑

将 RDoc 标记输入视为一系列不同类型的块（详细信息请参见链接）会很方便。

  • 段落：普通段落。

  • 逐字文本块：要按字面意思呈现的文本块。

  • 代码块：包含 Ruby 代码的逐字文本块，将使用代码突出显示进行呈现。

  • 块引用：较长的引用段落，将使用缩进而不是引号进行呈现。

  • 列表：项目符号列表、编号列表、字母列表或标签列表的项目。

  • 标题：节标题。

  • 水平线：横跨渲染页面的线。

  • 指令：渲染的各种特殊指令。

  • 文本标记: 以特殊方式呈现的文本。

关于块

  • 除了段落之外，块通过其缩进或不寻常的初始或嵌入字符来区分。

  • 任何块都可以独立出现（即，不嵌套在另一个块中）；一些块可以嵌套，如下所述。

段落 ↑

段落由一个或多个非空行普通文本组成，每行都从当前边距开始。

注意：这里，普通文本是指未识别的文本，即未通过缩进或不寻常的初始或嵌入字符识别的文本。见下文。

段落之间用一个或多个空行分隔。

示例输入

\RDoc produces HTML and command-line documentation for Ruby projects.
\RDoc includes the rdoc and ri tools for generating and displaying
documentation from the command-line.

You'll love it.

渲染后的 HTML

RDoc 为 Ruby 项目生成 HTML 和命令行文档。RDoc 包括 rdoc 和 ri 工具，用于从命令行生成和显示文档。

你会喜欢的。

段落可以包含嵌套块，包括

逐字文本块 ↑

缩进超出当前边距的文本将成为逐字文本块（或代码块，将在下一节中介绍）。在渲染的 HTML 中，此类文本

  • 被缩进。

  • 具有对比鲜明的背景颜色。

逐字文本块在第一行从当前边距开始的地方结束。

示例输入

This is not verbatim text.

  This is verbatim text.
    Whitespace is honored.     # See?
      Whitespace is honored.     # See?

  This is still the same verbatim text block.

This is not verbatim text.

渲染后的 HTML

这不是逐字文本。

This is verbatim text.
  Whitespace is honored.     # See?
    Whitespace is honored.     # See?

This is still the same verbatim text block.

这不是逐字文本。

逐字文本块不能包含任何类型的嵌套块——它是逐字的。

代码块 ↑

逐字文本的一种特殊情况是代码块，它仅仅是 RDoc 识别为 Ruby 代码的逐字文本

在渲染的 HTML 中，代码块

  • 被缩进。

  • 具有对比鲜明的背景颜色。

  • 具有语法高亮。

示例输入

Consider this method:

  def foo(name = '', value = 0)
    @name = name      # Whitespace is still honored.
    @value = value
  end

渲染后的 HTML

考虑这个方法

def foo(name = '', value = 0)
  @name = name      # Whitespace is still honored.
  @value = value
end

专业提示：如果缩进的 Ruby 代码没有被高亮显示，它可能包含语法错误。

代码块不能包含任何类型的嵌套块——它是逐字的。

块引用 ↑

您可以使用字符>>>（未缩进），后跟缩进文本，将文本视为块引用

示例输入

Here's a block quote:
.
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
  commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
  Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

  Aenean congue ligula eu ligula molestie, eu pellentesque purus
  faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
  diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
  purus magna ut tortor.

渲染后的 HTML

这是一个块引用

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer commodo quam iaculis massa posuere, dictum fringilla justo pulvinar. Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

Aenean congue ligula eu ligula molestie, eu pellentesque purus faucibus。In id leo non ligula condimentum lobortis。Duis vestibulum, diam in pellentesque aliquet, mi tellus placerat sapien, id euismod purus magna ut tortor。

请注意，与逐字文本不同，单行换行符不会被识别，但双行换行符会在块引用中开始一个新段落。

块引用可以包含嵌套的块，包括

列表 ↑

每种类型的列表项都以一个特殊的开头标记

  • 无序列表项：以连字符或星号开头。

  • 有序列表项：以数字和句点开头。

  • 字母列表项：以字母和句点开头。

  • 标记列表项：以以下之一开头

    • 方括号文本。

    • 一个词后面跟着两个冒号。

列表以一个列表项开头，并继续，即使跨越空行，只要在相同缩进级别找到相同类型的列表项。

一个新列表会将当前边距向内重置。对齐到该边距的额外文本行是继续列表项的一部分。

列表项可以在与第一行对齐的额外行上继续。请参见下面的示例。

列表项可以包含嵌套的块，包括

无序列表 ↑

无序列表项以连字符或星号开头。

示例输入

- An item.
- Another.
- An item spanning
  multiple lines.

* Yet another.
- Last one.

渲染后的 HTML

  • 一个项目。

  • 另一个。

  • 一个跨越多行的项目。

  • 另一个。

  • 最后一个。

有序列表 ↑

有序列表项以数字和句点开头。

项目会自动重新编号。

示例输入

100. An item.
10. Another.
1. An item spanning
   multiple lines.

1. Yet another.
1000. Last one.

渲染后的 HTML

  1. 一个项目。

  2. 另一个。

  3. 一个跨越多行的项目。

  4. 另一个。

  5. 最后一个。

字母列表 ↑

字母列表项以字母和句点开头。

项目会自动“重新字母化”。

示例输入

z. An item.
y. Another.
x. An item spanning
   multiple lines.

x. Yet another.
a. Last one.

渲染后的 HTML

  1. 一个项目。

  2. 另一个。

  3. 另一个。

  4. 最后一个。

标记列表 ↑

标记列表项以以下之一开头

  • 方括号文本：标签和文本在两行上。

  • 一个词后面跟着两个冒号：标签和文本在同一行上。

示例输入

[foo] An item.
bat:: Another.
[bag] An item spanning
      multiple lines.

[bar baz] Yet another.
bam:: Last one.

渲染后的 HTML

foo

一个项目。

bat

另一个。

bag

一个跨越多行的项目。

bar baz

另一个。

bam

最后一个。

标题 ↑

标题以最多六个等号开头，后面跟着标题文本。等号和标题文本之间的空格是可选的。

示例

= Section 1
== Section 1.1
=== Section 1.1.1
=== Section 1.1.2
== Section 1.2
= Section 2
= Foo
== Bar
=== Baz
==== Bam
===== Bat
====== Bad
============Still a Heading (Level 6)
\== Not a Heading

标题可能只包含一种类型的嵌套块

水平线 ↑

水平线由一条包含三个或更多连字符的线组成，除此之外没有其他内容。

示例输入

---
--- Not a horizontal rule.

-- Also not a horizontal rule.
---

渲染后的 HTML

— 不是水平线。

– 也不是水平线。

指令 ↑

允许或抑制文档的指令 ↑

  • # :stopdoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该忽略标记，直到下一个 :startdoc: 指令或文件末尾。

  • # :startdoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该恢复解析标记。

  • # :enddoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该忽略标记到文件末尾，无论其他指令如何。

  • # :nodoc:

    • 附加到定义类、模块、方法、别名、常量或属性的代码行。

    • 指定定义的对象不应被记录。

    • 对于 C 代码中的方法定义，它必须放在实现之前

      /* :nodoc: */
static VALUE
some_method(VALUE self)
{
    return self;
}

      请注意，此指令在方法定义处完全没有效果。例如，

      /* :nodoc: */
rb_define_method(cMyClass, "do_something", something_func, 0);

      上面的注释只是一个注释，与 RDoc 无关。因此，do_something 方法将被报告为“未记录”，除非该方法或函数在其他地方有记录。

    • 对于 C 代码中的常量定义，此指令无法工作，因为常量没有“实现”位置。

  • # :nodoc: all:

    • 附加到定义类或模块的代码行。

    • 指定类或模块不应被记录。但是，默认情况下，嵌套类或模块将被记录。

  • # :doc:

    • 附加到定义类、模块、方法、别名、常量或属性的代码行。

    • 指定定义的对象应该被记录，即使在其他情况下不会被记录。

  • # :notnew:（别名为 :not_new: 和 :not-new:）

    • 附加到定义实例方法 initialize 的代码行。

    • 指定单例方法new不应该被记录。默认情况下，Ruby 会伪造一个对应的单例方法new，RDoc 会将其包含在文档中。请注意，实例方法initialize是私有的，因此默认情况下不会被记录。

对于 Ruby 代码，但不是其他 RDoc 源代码，存在:stopdoc:和:startdoc:的简写形式。

# Documented.
#--
# Not documented.
#++
# Documented.

对于 C 代码，指令:startdoc:、:stopdoc:和:enddoc:可以出现在独立的注释中。

/* :startdoc: */
/* :stopdoc: */
/* :enddoc: */
指定 RDoc 源代码格式的指令 ↑

  • # :markup: type:

    • 出现在单独一行上。

    • 指定 RDoc 输入的格式；参数type是markdown、rd、rdoc、tomdoc之一。

HTML 输出的指令 ↑

  • # :title: text:

    • 出现在单独一行上。

    • 指定 HTML 输出的标题。

  • # :main: filename:

    • 出现在单独一行上。

    • 指定要首先显示的 HTML 文件。

针对Method文档的指令 ↑

  • # :call-seq:

    • 出现在单独一行上。

    • 指定在 HTML 中报告的调用序列，覆盖代码中的实际调用序列。参见方法call_seq_directive。

    请注意，RDoc 可以构建 Ruby 代码方法的调用序列，但不能构建其他语言的调用序列。如果您想包含，则可能需要通过显式给出:call-seq:指令来覆盖它。

    • 返回值类型，不会自动推断。

    • 多个调用序列。

    对于 C 代码，指令可以出现在独立的注释中。

  • # :args: arg_names（别名为:arg:）

    • 出现在单独一行上。

    • 指定在 HTML 中报告的参数，覆盖代码中的实际参数。参见方法args_directive。

  • # :yields: arg_names（别名为:yield:）

    • 出现在单独一行上。

    • 指定在 HTML 中报告的 yield 参数，覆盖代码中的实际 yield。参见方法yields_directive。

组织文档的指令 ↑

默认情况下，RDoc 将

  • 单例方法按字母顺序分组在一起。

  • 实例方法及其别名按字母顺序分组在一起。

  • 属性及其别名按字母顺序分组在一起。

您可以使用指令来修改这些行为。

  • # :section: section_title:

    • 出现在单独一行上。

    • 指定以下方法将分组到具有给定section_title的部分中，或者如果未给出标题，则分组到默认部分中。该指令一直有效，直到给出另一个此类指令，但可能被指令:category:临时覆盖。见下文。

    包含此指令的注释块

    • 必须与下一项的文档之间用空行隔开。

    • 可能在指令之前有一行或多行。这些将被删除，以及与它们匹配的任何尾随行。这些行可能在视觉上很有帮助。

    • 未被删除的文本行成为该部分的描述性文本。

    示例

    # ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------

##
# Comment for some_method
def some_method
  # ...
end

    您可以使用指令:category:临时覆盖当前部分。

  • # :category: section_title:

    • 出现在单独一行上。

    • 指定仅将一个后续方法包含在给定部分中，或者如果未给出标题，则包含在默认部分中。后续方法将分组到当前部分中。

用于包含File的指令 ↑

  • # :include: filepath:

    • 出现在单独一行上。

    • 指定将在此处包含给定文件的内容。文件内容将被移位以具有与指令开头的冒号相同的缩进。

      在使用--include命令行选项给出的目录中或默认情况下在当前目录中搜索该文件。

    对于 C 代码，该指令可能出现在独立的注释中

文本标记 ↑

文本标记是影响 HTML 渲染的元文本

  • 字体：斜体、粗体、等宽字体。

  • 字符转换：版权、商标、某些标点符号。

  • 链接。

  • 转义：将文本标记为“非标记”。

字体标记 ↑

字体标记可以指定文本以斜体、粗体或等宽字体呈现。

字体标记只能包含一种类型的嵌套块。

  • 更多字体标记：斜体、粗体、等宽字体。

斜体 ↑

文本可以通过 HTML 标签 <i> 或 <em> 标记为斜体。

示例输入

<i>Italicized words</i> in a paragraph.

.
  <i>Italicized words in a block quote</i>.

- <i>Italicized words</i> in a list item.

====== <i>Italicized words</i> in a Heading

<i>Italicized passage containing *bold* and +monofont+.</i>

渲染后的 HTML

斜体字 在段落中。

斜体字 在块引用中。.

  • 斜体字 在列表项中。

斜体字 在标题中 ↑

包含 粗体 和 等宽字体 的斜体段落。

单个单词可以通过简写标记为斜体：前缀和后缀下划线。

示例输入

_Italic_ in a paragraph.

.
  _Italic_ in a block quote.

- _Italic_ in a list item.

====== _Italic_ in a Heading

渲染后的 HTML

斜体 在段落中。

斜体 在块引用中。

  • 斜体 在列表项中。

斜体 在标题中 ↑
粗体 ↑

文本可以通过 HTML 标签 <b> 标记为粗体。

示例输入

<b>Bold words</b> in a paragraph.

.
  <b>Bold words</b> in a block quote.

- <b>Bold words</b> in a list item.

====== <b>Bold words</b> in a Heading

<b>Bold passage containing _italics_ and +monofont+.</b>

渲染后的 HTML

粗体字 在段落中。

粗体字 在块引用中。

  • 粗体字 在列表项中。

粗体字 在标题中 ↑

包含 斜体 和 等宽字体 的粗体段落。

单个单词可以通过简写标记为粗体：前缀和后缀星号。

示例输入

*Bold* in a paragraph.

.
  *Bold* in a block quote.

- *Bold* in a list item.

===== *Bold* in a Heading

渲染后的 HTML

粗体 在段落中。

粗体 在块引用中。

  • 粗体 在列表项中。

粗体 在标题中 ↑
等宽字体 ↑

文本可以通过 HTML 标签 <tt> 或 <code> 标记为等宽字体，有时也称为“打字机字体”。

示例输入

<tt>Monofont words</tt> in a paragraph.

.
  <tt>Monofont words</tt> in a block quote.

- <tt>Monofont words</tt> in a list item.

====== <tt>Monofont words</tt> in heading

<tt>Monofont passage containing _italics_ and *bold*.</tt>

渲染后的 HTML

等宽字体字 在段落中。

等宽字体字 在块引用中。

  • 等宽字体字 在列表项中。

等宽字体字 在标题中 ↑

包含 斜体 和 粗体 的等宽字体段落。

单个单词可以通过简写标记为等宽字体：前缀和后缀加号。

示例输入

+Monofont+ in a paragraph.

.
  +Monofont+ in a block quote.

- +Monofont+ in a list item.

====== +Monofont+ in a Heading

渲染后的 HTML

等宽字体 在段落中。

等宽字体 在块引用中。

  • 等宽字体 在列表项中。

等宽字体 在标题中 ↑

字符转换 ↑

某些字符组合可以转换为特殊字符；是否进行转换取决于当前编码中是否提供特殊字符。

  • (c) 转换为 ©（版权字符）；必须为小写。

  • (r) 转换为 ®（注册商标字符）；必须为小写。

  • 'foo' 转换为 ‘foo’（智能单引号）。

  • "foo" 转换为 “foo”（智能双引号）。

  • foo ... bar 转换为 foo … bar（1 个字符省略号）。

  • foo -- bar 转换为 foo – bar（1 个字符短破折号）。

  • foo --- bar 转换为 foo — bar（1 个字符长破折号）。

RDoc 文本中的某些字符串将转换为链接。任何此类链接都可以通过在前面添加反斜杠来抑制。本节介绍如何链接到各种目标。

类

  • 页面内：DummyClass 链接到 DummyClass。

  • 页面外：RDoc::Alias 链接到 RDoc::Alias。

模块

  • 页面内：DummyModule 链接到 DummyModule。

  • 页面外：RDoc 链接到 RDoc。

常量

  • 页面内：DUMMY_CONSTANT 链接到 DUMMY_CONSTANT。

  • 页面外：RDoc::Text::MARKUP_FORMAT 链接到 RDoc::Text::MARKUP_FORMAT。

单例 Method

  • 页面内：::dummy_singleton_method 链接到 ::dummy_singleton_method。

  • 页面外RDoc::TokenStream::to_html 链接到 RDoc::TokenStream::to_html。

注意：有时 RDoc 不会链接到名称仅包含特殊字符的方法。请检查您期望的链接是否确实存在。如果没有，您需要添加一个显式链接；请参见下文。

提示：任何方法的链接都可以在页面左侧的类或模块的字母索引中找到。

实例 Method

  • 页面内：#dummy_instance_method 链接到 dummy_instance_method。

  • 页面外：RDoc::Alias#html_name 链接到 RDoc::Alias#html_name。

    请参阅上面的“注意”和“提示”。

属性

  • 页面内：#dummy_attribute 链接到 dummy_attribute。

  • 页面外：RDoc::Alias#name 链接到 RDoc::Alias#name。

别名

  • 页面内：#dummy_instance_alias 链接到 dummy_instance_alias。

  • 页面外：RDoc::Alias#new_name 链接到 RDoc::Alias#new_name。

协议 http

  • 链接：http://yahoo.com 链接到 yahoo.com。

协议 https

  • 链接：https://github.com 链接到 github.com。

协议 www
协议 ftp
协议 mailto
协议 irc
图片文件名扩展名

  • 链接：https://www.ruby-lang.org.cn/images/[email protected] 被转换为内联 HTML img 标签，并在 HTML 中显示图片。

    也适用于 bmp、gif、jpeg 和 jpg 文件。

    注意：仅适用于完整限定的 URL。

标题

  • 链接：RDoc::RD@LICENSE 链接到 RDoc::RDoc::RD 中的 LICENSE。

注意，实际标题中的空格在可链接文本中用 + 字符表示。

  • 链接：RDoc::Options@Saved+Options 链接到 RDoc::Options 中的 Saved Options。

标点符号和其他特殊字符必须像 CGI.escape 一样进行转义。

提示：任何标题的链接都可以在页面左侧的类或模块的字母索引表中找到。

章节

参见 组织文档的指令。

  • 链接：RDoc::Markup::ToHtml@Visitor 链接到 RDoc::Markup::ToHtml 中的 Visitor。

如果章节和标题名称相同，则链接目标为章节。

单字文本链接

使用方括号创建单字文本链接

  • GitHub[https://github.com] 链接到 GitHub。

多字文本链接

使用方括号和花括号创建多字文本链接。

rdoc-ref 方案

使用 rdoc-ref: 方案的链接会链接到引用的项目，如果该项目存在。引用的项目可以是类、模块、方法、文件等。

  • 类: Alias[rdoc-ref:RDoc::Alias] 链接到 RDoc::Alias。

  • 模块: RDoc[rdoc-ref:RDoc] 链接到 RDoc.

  • 方法: foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK] 链接到 foo。

  • 常量: bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML] 链接到 bar。

  • 属性: baz[rdoc-ref:RDoc::Markup::ToHtml#code_object] 链接到 baz。

  • 别名: bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] 链接到 bad.

如果引用的项目不存在，则不会生成链接，并且整个 rdoc-ref: 方括号子句将从生成的文本中删除。

  • Nosuch[rdoc-ref:RDoc::Nosuch] 呈现为 Nosuch。

rdoc-label 方案
简单

您可以使用此形式指定链接目标，其中第二部分引用 HTML 元素的 ID。

此链接引用此页面上的常量 DUMMY_CONSTANT

  • {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]

因此

DUMMY_CONSTANT

带返回

您可以同时指定链接目标和本地标签，该标签可用作返回链接的目标。这两个链接相互引用

  • {转到收件人}[rdoc-label:addressee:sender]

  • {返回发件人}[rdoc-label:sender:addressee]

因此

转到收件人

一些文本。

返回发件人

link: 方案
rdoc-image 方案

使用 rdoc-image 方案显示也是链接的图像

# {rdoc-image:path/to/image}[link_target]

  • 链接: {rdoc-image:https://www.ruby-lang.org.cn/images/[email protected]}[https://www.ruby-lang.org.cn] 显示图像 https://www.ruby-lang.org.cn/images/[email protected] 作为指向 https://www.ruby-lang.org.cn 的链接。

相对路径作为目标也可以工作

  • 链接: {rdoc-image:https://www.ruby-lang.org.cn/images/[email protected]}[./Alias.html] 链接到 ./Alias.html

转义文本 ↑

否则将被解释为标记的文本可以“转义”，以便它不被解释为标记；转义字符是反斜杠 ('\')。

在逐字文本块或代码块中，转义字符始终保留

示例输入

This is not verbatim text.

  This is verbatim text, with an escape character \.

This is not a code block.

  def foo
    'String with an escape character.'
  end

渲染后的 HTML

这不是逐字文本。

This is verbatim text, with an escape character \.

这不是代码块。

def foo
  'This is a code block with an escape character \.'
end

在字形标记（斜体、粗体或等宽字体）中，转义字符将保留，除非它紧跟在嵌套的字形标记之后。

示例输入

This list is about escapes; it contains:

- <tt>Monofont text with unescaped nested _italic_</tt>.
- <tt>Monofont text with escaped nested \_italic_</tt>.
- <tt>Monofont text with an escape character \</tt>.

渲染后的 HTML

此列表是关于转义的；它包含

  • 带有未转义嵌套斜体的等宽字体文本.

  • 带有转义嵌套_斜体_的等宽字体文本.

  • 包含转义字符 \ 的单字体文本 .

在其他包含文本的块（段落、块引用、列表项、标题）中

  • 单个转义字符紧跟在标记后面，会转义该标记。

  • 单个转义字符后跟空格，将被保留。

  • 其他位置的单个转义字符将被忽略。

  • 双转义字符将被渲染为单个反斜杠。

    示例输入

    This list is about escapes; it contains:

- An unescaped class name, RDoc, that will become a link.
- An escaped class name, \RDoc, that will not become a link.
- An escape character followed by whitespace \ .
- An escape character \that is ignored.
- A double escape character \\ that is rendered
  as a single backslash.

    渲染后的 HTML

    此列表是关于转义的；它包含

    • 未转义的类名，RDoc，将成为链接。

    • 转义的类名，RDoc，不会成为链接。

    • 转义字符后跟空格 \ 。

    • 被忽略的转义字符。

    • 双转义字符 \ 被渲染为单个反斜杠。

从 Ruby 代码派生的文档 ↑

类

默认情况下，RDoc 文档

  • 类名。

  • 父类。

  • 单例方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

模块

默认情况下，RDoc 文档

  • 模块名。

  • 单例方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

方法

默认情况下，RDoc 文档

  • 方法名。

  • 参数。

  • yield 的值。

参见 method。

别名

默认情况下，RDoc 文档

  • 别名。

  • 别名后的名称。

参见 dummy_instance_alias 和 dummy_instance_method。

常量

默认情况下，RDoc 文档

  • 常量名。

参见 DUMMY_CONSTANT。

属性

默认情况下，RDoc 文档

  • 属性名。

  • 属性类型 ([R], [W], 或 [RW])

参见 dummy_attribute。

类 RDoc::MarkupReference 仅存在是为了提供一个合适的场所来存放 RDoc 标记的参考文档。

此类中定义的所有对象（类、模块、方法、别名、属性和常量）仅用于说明 RDoc 标记，没有其他合法用途。

RDoc 标记参考 ↑

注意

  • 此参考中的示例是 Ruby 代码和注释；某些与其他来源（如 C 代码和注释）的不同之处已注明。

  • 显示渲染后的 HTML 输出的示例在块引用中显示该输出

    渲染后的 HTML

    一些内容

RDoc 生成的文档源自并受以下内容控制

  • 在某些定义之前出现的单行或多行注释；请参阅 注释中的标记。

  • 尾部注释中的 RDoc 指令（与代码在同一行）；请参阅 :nodoc:、:doc: 和 :notnew:。

  • 单行注释中的 RDoc 指令；请参阅其他 指令。

  • Ruby 代码本身（但不包括 C 代码）；请参阅 从 Ruby 代码派生的文档。

注释中的标记 ↑

注释中标记的处理方式因文件类型而异

  • .rb（Ruby 代码文件）：标记从 Ruby 注释中解析。

  • .c（C 代码文件）：标记从 C 注释中解析。

  • .rdoc（RDoc 文本文件）：标记从整个文件中解析。

与 Ruby 类、模块、方法、别名、常量或属性关联的注释将成为该定义对象的文档。

  • 在 Ruby 文件中，该注释紧接在对象定义之前。

  • 在 C 文件中，该注释紧接在实现方法的函数之前，或者紧接在对象定义之前。

在 Ruby 或 C 文件中，RDoc 忽略不位于对象定义之前的注释。

在 RDoc 文件中，文本与任何代码对象无关，但可能会（取决于文档的构建方式）成为一个单独的页面。

此页面上的几乎所有示例都是 RDoc 样式的；也就是说，它们没有像 Ruby # 或 C /* ... */ 这样的注释标记。

边距 ↑

在多行注释中，RDoc 会查找注释的自然左边界，该边界将成为注释的基准边界，也是注释的初始当前边界。

当前边界可能会发生变化，例如在列表中。

块 ↑

将 RDoc 标记输入视为一系列不同类型的块（详细信息请参见链接）会很方便。

  • 段落：普通段落。

  • 逐字文本块：要按字面意思呈现的文本块。

  • 代码块：包含 Ruby 代码的逐字文本块，将使用代码突出显示进行呈现。

  • 块引用：较长的引用段落，将使用缩进而不是引号进行呈现。

  • 列表：项目符号列表、编号列表、字母列表或标签列表的项目。

  • 标题：节标题。

  • 水平线：横跨渲染页面的线。

  • 指令：渲染的各种特殊指令。

  • 文本标记: 以特殊方式呈现的文本。

关于块

  • 除了段落之外，块通过其缩进或不寻常的初始或嵌入字符来区分。

  • 任何块都可以独立出现（即，不嵌套在另一个块中）；一些块可以嵌套，如下所述。

段落 ↑

段落由一个或多个非空行普通文本组成，每行都从当前边距开始。

注意：这里，普通文本是指未识别的文本，即未通过缩进或不寻常的初始或嵌入字符识别的文本。见下文。

段落之间用一个或多个空行分隔。

示例输入

\RDoc produces HTML and command-line documentation for Ruby projects.
\RDoc includes the rdoc and ri tools for generating and displaying
documentation from the command-line.

You'll love it.

渲染后的 HTML

RDoc 为 Ruby 项目生成 HTML 和命令行文档。RDoc 包括 rdoc 和 ri 工具，用于从命令行生成和显示文档。

你会喜欢的。

段落可以包含嵌套块，包括

逐字文本块 ↑

缩进超出当前边距的文本将成为逐字文本块（或代码块，将在下一节中介绍）。在渲染的 HTML 中，此类文本

  • 被缩进。

  • 具有对比鲜明的背景颜色。

逐字文本块在第一行从当前边距开始的地方结束。

示例输入

This is not verbatim text.

  This is verbatim text.
    Whitespace is honored.     # See?
      Whitespace is honored.     # See?

  This is still the same verbatim text block.

This is not verbatim text.

渲染后的 HTML

这不是逐字文本。

This is verbatim text.
  Whitespace is honored.     # See?
    Whitespace is honored.     # See?

This is still the same verbatim text block.

这不是逐字文本。

逐字文本块不能包含任何类型的嵌套块——它是逐字的。

代码块 ↑

逐字文本的一种特殊情况是代码块，它仅仅是 RDoc 识别为 Ruby 代码的逐字文本

在渲染的 HTML 中，代码块

  • 被缩进。

  • 具有对比鲜明的背景颜色。

  • 具有语法高亮。

示例输入

Consider this method:

  def foo(name = '', value = 0)
    @name = name      # Whitespace is still honored.
    @value = value
  end

渲染后的 HTML

考虑这个方法

def foo(name = '', value = 0)
  @name = name      # Whitespace is still honored.
  @value = value
end

专业提示：如果缩进的 Ruby 代码没有被高亮显示，它可能包含语法错误。

代码块不能包含任何类型的嵌套块——它是逐字的。

块引用 ↑

您可以使用字符>>>（未缩进），后跟缩进文本，将文本视为块引用

示例输入

Here's a block quote:
.
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer
  commodo quam iaculis massa posuere, dictum fringilla justo pulvinar.
  Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

  Aenean congue ligula eu ligula molestie, eu pellentesque purus
  faucibus. In id leo non ligula condimentum lobortis. Duis vestibulum,
  diam in pellentesque aliquet, mi tellus placerat sapien, id euismod
  purus magna ut tortor.

渲染后的 HTML

这是一个块引用

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer commodo quam iaculis massa posuere, dictum fringilla justo pulvinar. Quisque turpis erat, pharetra eu dui at, sollicitudin accumsan nulla.

Aenean congue ligula eu ligula molestie, eu pellentesque purus faucibus。In id leo non ligula condimentum lobortis。Duis vestibulum, diam in pellentesque aliquet, mi tellus placerat sapien, id euismod purus magna ut tortor。

请注意，与逐字文本不同，单行换行符不会被识别，但双行换行符会在块引用中开始一个新段落。

块引用可以包含嵌套的块，包括

列表 ↑

每种类型的列表项都以一个特殊的开头标记

  • 无序列表项：以连字符或星号开头。

  • 有序列表项：以数字和句点开头。

  • 字母列表项：以字母和句点开头。

  • 标记列表项：以以下之一开头

    • 方括号文本。

    • 一个词后面跟着两个冒号。

列表以一个列表项开头，并继续，即使跨越空行，只要在相同缩进级别找到相同类型的列表项。

一个新列表会将当前边距向内重置。对齐到该边距的额外文本行是继续列表项的一部分。

列表项可以在与第一行对齐的额外行上继续。请参见下面的示例。

列表项可以包含嵌套的块，包括

无序列表 ↑

无序列表项以连字符或星号开头。

示例输入

- An item.
- Another.
- An item spanning
  multiple lines.

* Yet another.
- Last one.

渲染后的 HTML

  • 一个项目。

  • 另一个。

  • 一个跨越多行的项目。

  • 另一个。

  • 最后一个。

有序列表 ↑

有序列表项以数字和句点开头。

项目会自动重新编号。

示例输入

100. An item.
10. Another.
1. An item spanning
   multiple lines.

1. Yet another.
1000. Last one.

渲染后的 HTML

  1. 一个项目。

  2. 另一个。

  3. 一个跨越多行的项目。

  4. 另一个。

  5. 最后一个。

字母列表 ↑

字母列表项以字母和句点开头。

项目会自动“重新字母化”。

示例输入

z. An item.
y. Another.
x. An item spanning
   multiple lines.

x. Yet another.
a. Last one.

渲染后的 HTML

  1. 一个项目。

  2. 另一个。

  3. 另一个。

  4. 最后一个。

标记列表 ↑

标记列表项以以下之一开头

  • 方括号文本：标签和文本在两行上。

  • 一个词后面跟着两个冒号：标签和文本在同一行上。

示例输入

[foo] An item.
bat:: Another.
[bag] An item spanning
      multiple lines.

[bar baz] Yet another.
bam:: Last one.

渲染后的 HTML

foo

一个项目。

bat

另一个。

bag

一个跨越多行的项目。

bar baz

另一个。

bam

最后一个。

标题 ↑

标题以最多六个等号开头，后面跟着标题文本。等号和标题文本之间的空格是可选的。

示例

= Section 1
== Section 1.1
=== Section 1.1.1
=== Section 1.1.2
== Section 1.2
= Section 2
= Foo
== Bar
=== Baz
==== Bam
===== Bat
====== Bad
============Still a Heading (Level 6)
\== Not a Heading

标题可能只包含一种类型的嵌套块

水平线 ↑

水平线由一条包含三个或更多连字符的线组成，除此之外没有其他内容。

示例输入

---
--- Not a horizontal rule.

-- Also not a horizontal rule.
---

渲染后的 HTML

— 不是水平线。

– 也不是水平线。

指令 ↑

允许或抑制文档的指令 ↑

  • # :stopdoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该忽略标记，直到下一个 :startdoc: 指令或文件末尾。

  • # :startdoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该恢复解析标记。

  • # :enddoc:

    • 出现在单独一行上。

    • 指定 RDoc 应该忽略标记到文件末尾，无论其他指令如何。

  • # :nodoc:

    • 附加到定义类、模块、方法、别名、常量或属性的代码行。

    • 指定定义的对象不应被记录。

    • 对于 C 代码中的方法定义，它必须放在实现之前

      /* :nodoc: */
static VALUE
some_method(VALUE self)
{
    return self;
}

      请注意，此指令在方法定义处完全没有效果。例如，

      /* :nodoc: */
rb_define_method(cMyClass, "do_something", something_func, 0);

      上面的注释只是一个注释，与 RDoc 无关。因此，do_something 方法将被报告为“未记录”，除非该方法或函数在其他地方有记录。

    • 对于 C 代码中的常量定义，此指令无法工作，因为常量没有“实现”位置。

  • # :nodoc: all:

    • 附加到定义类或模块的代码行。

    • 指定类或模块不应被记录。但是，默认情况下，嵌套类或模块将被记录。

  • # :doc:

    • 附加到定义类、模块、方法、别名、常量或属性的代码行。

    • 指定定义的对象应该被记录，即使在其他情况下不会被记录。

  • # :notnew:（别名为 :not_new: 和 :not-new:）

    • 附加到定义实例方法 initialize 的代码行。

    • 指定单例方法new不应该被记录。默认情况下，Ruby 会伪造一个对应的单例方法new，RDoc 会将其包含在文档中。请注意，实例方法initialize是私有的，因此默认情况下不会被记录。

对于 Ruby 代码，但不是其他 RDoc 源代码，存在:stopdoc:和:startdoc:的简写形式。

# Documented.
#--
# Not documented.
#++
# Documented.

对于 C 代码，指令:startdoc:、:stopdoc:和:enddoc:可以出现在独立的注释中。

/* :startdoc: */
/* :stopdoc: */
/* :enddoc: */
指定 RDoc 源代码格式的指令 ↑

  • # :markup: type:

    • 出现在单独一行上。

    • 指定 RDoc 输入的格式；参数type是markdown、rd、rdoc、tomdoc之一。

HTML 输出的指令 ↑

  • # :title: text:

    • 出现在单独一行上。

    • 指定 HTML 输出的标题。

  • # :main: filename:

    • 出现在单独一行上。

    • 指定要首先显示的 HTML 文件。

针对Method文档的指令 ↑

  • # :call-seq:

    • 出现在单独一行上。

    • 指定在 HTML 中报告的调用序列，覆盖代码中的实际调用序列。参见方法call_seq_directive。

    请注意，RDoc 可以构建 Ruby 代码方法的调用序列，但不能构建其他语言的调用序列。如果您想包含，则可能需要通过显式给出:call-seq:指令来覆盖它。

    • 返回值类型，不会自动推断。

    • 多个调用序列。

    对于 C 代码，指令可以出现在独立的注释中。

  • # :args: arg_names（别名为:arg:）

    • 出现在单独一行上。

    • 指定在 HTML 中报告的参数，覆盖代码中的实际参数。参见方法args_directive。

  • # :yields: arg_names（别名为:yield:）

    • 出现在单独一行上。

    • 指定在 HTML 中报告的 yield 参数，覆盖代码中的实际 yield。参见方法yields_directive。

组织文档的指令 ↑

默认情况下，RDoc 将

  • 单例方法按字母顺序分组在一起。

  • 实例方法及其别名按字母顺序分组在一起。

  • 属性及其别名按字母顺序分组在一起。

您可以使用指令来修改这些行为。

  • # :section: section_title:

    • 出现在单独一行上。

    • 指定以下方法将分组到具有给定section_title的部分中，或者如果未给出标题，则分组到默认部分中。该指令一直有效，直到给出另一个此类指令，但可能被指令:category:临时覆盖。见下文。

    包含此指令的注释块

    • 必须与下一项的文档之间用空行隔开。

    • 可能在指令之前有一行或多行。这些将被删除，以及与它们匹配的任何尾随行。这些行可能在视觉上很有帮助。

    • 未被删除的文本行成为该部分的描述性文本。

    示例

    # ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------

##
# Comment for some_method
def some_method
  # ...
end

    您可以使用指令:category:临时覆盖当前部分。

  • # :category: section_title:

    • 出现在单独一行上。

    • 指定仅将一个后续方法包含在给定部分中，或者如果未给出标题，则包含在默认部分中。后续方法将分组到当前部分中。

用于包含File的指令 ↑

  • # :include: filepath:

    • 出现在单独一行上。

    • 指定将在此处包含给定文件的内容。文件内容将被移位以具有与指令开头的冒号相同的缩进。

      在使用--include命令行选项给出的目录中或默认情况下在当前目录中搜索该文件。

    对于 C 代码，该指令可能出现在独立的注释中

文本标记 ↑

文本标记是影响 HTML 渲染的元文本

  • 字体：斜体、粗体、等宽字体。

  • 字符转换：版权、商标、某些标点符号。

  • 链接。

  • 转义：将文本标记为“非标记”。

字体标记 ↑

字体标记可以指定文本以斜体、粗体或等宽字体呈现。

字体标记只能包含一种类型的嵌套块。

  • 更多字体标记：斜体、粗体、等宽字体。

斜体 ↑

文本可以通过 HTML 标签 <i> 或 <em> 标记为斜体。

示例输入

<i>Italicized words</i> in a paragraph.

.
  <i>Italicized words in a block quote</i>.

- <i>Italicized words</i> in a list item.

====== <i>Italicized words</i> in a Heading

<i>Italicized passage containing *bold* and +monofont+.</i>

渲染后的 HTML

斜体字 在段落中。

斜体字 在块引用中。.

  • 斜体字 在列表项中。

斜体字 在标题中 ↑

包含 粗体 和 等宽字体 的斜体段落。

单个单词可以通过简写标记为斜体：前缀和后缀下划线。

示例输入

_Italic_ in a paragraph.

.
  _Italic_ in a block quote.

- _Italic_ in a list item.

====== _Italic_ in a Heading

渲染后的 HTML

斜体 在段落中。

斜体 在块引用中。

  • 斜体 在列表项中。

斜体 在标题中 ↑
粗体 ↑

文本可以通过 HTML 标签 <b> 标记为粗体。

示例输入

<b>Bold words</b> in a paragraph.

.
  <b>Bold words</b> in a block quote.

- <b>Bold words</b> in a list item.

====== <b>Bold words</b> in a Heading

<b>Bold passage containing _italics_ and +monofont+.</b>

渲染后的 HTML

粗体字 在段落中。

粗体字 在块引用中。

  • 粗体字 在列表项中。

粗体字 在标题中 ↑

包含 斜体 和 等宽字体 的粗体段落。

单个单词可以通过简写标记为粗体：前缀和后缀星号。

示例输入

*Bold* in a paragraph.

.
  *Bold* in a block quote.

- *Bold* in a list item.

===== *Bold* in a Heading

渲染后的 HTML

粗体 在段落中。

粗体 在块引用中。

  • 粗体 在列表项中。

粗体 在标题中 ↑
等宽字体 ↑

文本可以通过 HTML 标签 <tt> 或 <code> 标记为等宽字体，有时也称为“打字机字体”。

示例输入

<tt>Monofont words</tt> in a paragraph.

.
  <tt>Monofont words</tt> in a block quote.

- <tt>Monofont words</tt> in a list item.

====== <tt>Monofont words</tt> in heading

<tt>Monofont passage containing _italics_ and *bold*.</tt>

渲染后的 HTML

等宽字体字 在段落中。

等宽字体字 在块引用中。

  • 等宽字体字 在列表项中。

等宽字体字 在标题中 ↑

包含 斜体 和 粗体 的等宽字体段落。

单个单词可以通过简写标记为等宽字体：前缀和后缀加号。

示例输入

+Monofont+ in a paragraph.

.
  +Monofont+ in a block quote.

- +Monofont+ in a list item.

====== +Monofont+ in a Heading

渲染后的 HTML

等宽字体 在段落中。

等宽字体 在块引用中。

  • 等宽字体 在列表项中。

等宽字体 在标题中 ↑

字符转换 ↑

某些字符组合可以转换为特殊字符；是否进行转换取决于当前编码中是否提供特殊字符。

  • (c) 转换为 ©（版权字符）；必须为小写。

  • (r) 转换为 ®（注册商标字符）；必须为小写。

  • 'foo' 转换为 ‘foo’（智能单引号）。

  • "foo" 转换为 “foo”（智能双引号）。

  • foo ... bar 转换为 foo … bar（1 个字符省略号）。

  • foo -- bar 转换为 foo – bar（1 个字符短破折号）。

  • foo --- bar 转换为 foo — bar（1 个字符长破折号）。

RDoc 文本中的某些字符串将转换为链接。任何此类链接都可以通过在前面添加反斜杠来抑制。本节介绍如何链接到各种目标。

类

  • 页面内：DummyClass 链接到 DummyClass。

  • 页面外：RDoc::Alias 链接到 RDoc::Alias。

模块

  • 页面内：DummyModule 链接到 DummyModule。

  • 页面外：RDoc 链接到 RDoc。

常量

  • 页面内：DUMMY_CONSTANT 链接到 DUMMY_CONSTANT。

  • 页面外：RDoc::Text::MARKUP_FORMAT 链接到 RDoc::Text::MARKUP_FORMAT。

单例 Method

  • 页面内：::dummy_singleton_method 链接到 ::dummy_singleton_method。

  • 页面外RDoc::TokenStream::to_html 链接到 RDoc::TokenStream::to_html。

注意：有时 RDoc 不会链接到名称仅包含特殊字符的方法。请检查您期望的链接是否确实存在。如果没有，您需要添加一个显式链接；请参见下文。

提示：任何方法的链接都可以在页面左侧的类或模块的字母索引中找到。

实例 Method

  • 页面内：#dummy_instance_method 链接到 dummy_instance_method。

  • 页面外：RDoc::Alias#html_name 链接到 RDoc::Alias#html_name。

    请参阅上面的“注意”和“提示”。

属性

  • 页面内：#dummy_attribute 链接到 dummy_attribute。

  • 页面外：RDoc::Alias#name 链接到 RDoc::Alias#name。

别名

  • 页面内：#dummy_instance_alias 链接到 dummy_instance_alias。

  • 页面外：RDoc::Alias#new_name 链接到 RDoc::Alias#new_name。

协议 http

  • 链接：http://yahoo.com 链接到 yahoo.com。

协议 https

  • 链接：https://github.com 链接到 github.com。

协议 www
协议 ftp
协议 mailto
协议 irc
图片文件名扩展名

  • 链接：https://www.ruby-lang.org.cn/images/[email protected] 被转换为内联 HTML img 标签，并在 HTML 中显示图片。

    也适用于 bmp、gif、jpeg 和 jpg 文件。

    注意：仅适用于完整限定的 URL。

标题

  • 链接：RDoc::RD@LICENSE 链接到 RDoc::RDoc::RD 中的 LICENSE。

注意，实际标题中的空格在可链接文本中用 + 字符表示。

  • 链接：RDoc::Options@Saved+Options 链接到 RDoc::Options 中的 Saved Options。

标点符号和其他特殊字符必须像 CGI.escape 一样进行转义。

提示：任何标题的链接都可以在页面左侧的类或模块的字母索引表中找到。

章节

参见 组织文档的指令。

  • 链接：RDoc::Markup::ToHtml@Visitor 链接到 RDoc::Markup::ToHtml 中的 Visitor。

如果章节和标题名称相同，则链接目标为章节。

单字文本链接

使用方括号创建单字文本链接

  • GitHub[https://github.com] 链接到 GitHub。

多字文本链接

使用方括号和花括号创建多字文本链接。

rdoc-ref 方案

使用 rdoc-ref: 方案的链接会链接到引用的项目，如果该项目存在。引用的项目可以是类、模块、方法、文件等。

  • 类: Alias[rdoc-ref:RDoc::Alias] 链接到 RDoc::Alias。

  • 模块: RDoc[rdoc-ref:RDoc] 链接到 RDoc.

  • 方法: foo[rdoc-ref:RDoc::Markup::ToHtml#handle_regexp_RDOCLINK] 链接到 foo。

  • 常量: bar[rdoc-ref:RDoc::Markup::ToHtml::LIST_TYPE_TO_HTML] 链接到 bar。

  • 属性: baz[rdoc-ref:RDoc::Markup::ToHtml#code_object] 链接到 baz。

  • 别名: bad[rdoc-ref:RDoc::MarkupReference#dummy_instance_alias] 链接到 bad.

如果引用的项目不存在，则不会生成链接，并且整个 rdoc-ref: 方括号子句将从生成的文本中删除。

  • Nosuch[rdoc-ref:RDoc::Nosuch] 呈现为 Nosuch。

rdoc-label 方案
简单

您可以使用此形式指定链接目标，其中第二部分引用 HTML 元素的 ID。

此链接引用此页面上的常量 DUMMY_CONSTANT

  • {DUMMY_CONSTANT}[rdoc-label:DUMMY_CONSTANT]

因此

DUMMY_CONSTANT

带返回

您可以同时指定链接目标和本地标签，该标签可用作返回链接的目标。这两个链接相互引用

  • {转到收件人}[rdoc-label:addressee:sender]

  • {返回发件人}[rdoc-label:sender:addressee]

因此

转到收件人

一些文本。

返回发件人

link: 方案
rdoc-image 方案

使用 rdoc-image 方案显示也是链接的图像

# {rdoc-image:path/to/image}[link_target]

  • 链接: {rdoc-image:https://www.ruby-lang.org.cn/images/[email protected]}[https://www.ruby-lang.org.cn] 显示图像 https://www.ruby-lang.org.cn/images/[email protected] 作为指向 https://www.ruby-lang.org.cn 的链接。

相对路径作为目标也可以工作

  • 链接: {rdoc-image:https://www.ruby-lang.org.cn/images/[email protected]}[./Alias.html] 链接到 ./Alias.html

转义文本 ↑

否则将被解释为标记的文本可以“转义”，以便它不被解释为标记；转义字符是反斜杠 ('\')。

在逐字文本块或代码块中，转义字符始终保留

示例输入

This is not verbatim text.

  This is verbatim text, with an escape character \.

This is not a code block.

  def foo
    'String with an escape character.'
  end

渲染后的 HTML

这不是逐字文本。

This is verbatim text, with an escape character \.

这不是代码块。

def foo
  'This is a code block with an escape character \.'
end

在字形标记（斜体、粗体或等宽字体）中，转义字符将保留，除非它紧跟在嵌套的字形标记之后。

示例输入

This list is about escapes; it contains:

- <tt>Monofont text with unescaped nested _italic_</tt>.
- <tt>Monofont text with escaped nested \_italic_</tt>.
- <tt>Monofont text with an escape character \</tt>.

渲染后的 HTML

此列表是关于转义的；它包含

  • 带有未转义嵌套斜体的等宽字体文本.

  • 带有转义嵌套_斜体_的等宽字体文本.

  • 包含转义字符 \ 的单字体文本 .

在其他包含文本的块（段落、块引用、列表项、标题）中

  • 单个转义字符紧跟在标记后面，会转义该标记。

  • 单个转义字符后跟空格，将被保留。

  • 其他位置的单个转义字符将被忽略。

  • 双转义字符将被渲染为单个反斜杠。

    示例输入

    This list is about escapes; it contains:

- An unescaped class name, RDoc, that will become a link.
- An escaped class name, \RDoc, that will not become a link.
- An escape character followed by whitespace \ .
- An escape character \that is ignored.
- A double escape character \\ that is rendered
  as a single backslash.

    渲染后的 HTML

    此列表是关于转义的；它包含

    • 未转义的类名，RDoc，将成为链接。

    • 转义的类名，RDoc，不会成为链接。

    • 转义字符后跟空格 \ 。

    • 被忽略的转义字符。

    • 双转义字符 \ 被渲染为单个反斜杠。

从 Ruby 代码派生的文档 ↑

类

默认情况下，RDoc 文档

  • 类名。

  • 父类。

  • 单例方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

模块

默认情况下，RDoc 文档

  • 模块名。

  • 单例方法。

  • 实例方法。

  • 别名。

  • 常量。

  • 属性。

方法

默认情况下，RDoc 文档

  • 方法名。

  • 参数。

  • yield 的值。

参见 method。

别名

默认情况下，RDoc 文档

  • 别名。

  • 别名后的名称。

参见 dummy_instance_alias 和 dummy_instance_method。

常量

默认情况下，RDoc 文档

  • 常量名。

参见 DUMMY_CONSTANT。

属性

默认情况下，RDoc 文档

  • 属性名。

  • 属性类型 ([R], [W], 或 [RW])

参见 dummy_attribute。

常量

DUMMY_CONSTANT

示例常量

属性

dummy_attribute[RW]

示例属性

dummy_attribute_alias[RW]

示例属性

公共类方法

dummy_singleton_method(foo, bar) 点击切换源代码

示例单例方法

# File rdoc/markup_reference.rb, line 1226
def self.dummy_singleton_method(foo, bar); end

公共实例方法

args_directive(baz) 点击切换源代码

:args: 指令会覆盖在 Ruby 代码中找到的实际参数。

点击调用序列查看代码。

# File rdoc/markup_reference.rb, line 1274
def args_directive(foo, bar) # :args: baz
  nil
end
call_seq_directive(foo, bar) 点击切换源代码
可以是任何东西 → bar
还有更多东西 → baz 或 bat

:call-seq: 指令会覆盖在 Ruby 代码中找到的实际调用序列。

  • 它可以指定任何东西。

  • 它可以有多个调用序列。

这个包括 Can be anything -> foo，这是无意义的。

注意，“箭头”是两个字符，连字符和右尖括号，在 HTML 中被合并成一个字符。

点击调用序列查看代码。

以下是方法的:call-seq: 指令

:call-seq:
  call_seq_directive(foo, bar)
  Can be anything -> bar
  Also anything more -> baz or bat
# File rdoc/markup_reference.rb, line 1266
def call_seq_directive
  nil
end
dummy_instance_alias(foo, bar)
别名：dummy_instance_method
dummy_instance_method(foo, bar) 点击切换源代码

示例实例方法

# File rdoc/markup_reference.rb, line 1229
def dummy_instance_method(foo, bar); end
也称为：dummy_instance_alias, dummy_instance_alias
method(foo, bar) { |'baz'| ... } 点击切换源代码

此方法仅由 RDoc 文档化，除了这些注释。

点击调用序列查看代码。

# File rdoc/markup_reference.rb, line 1290
def method(foo, bar)
  yield 'baz'
end
yields_directive(foo, bar) { |'bat'| ... } 点击切换源代码

:yields: 指令覆盖了 Ruby 代码中实际的 yield。

点击调用序列查看代码。

# File rdoc/markup_reference.rb, line 1282
def yields_directive(foo, bar) # :yields: 'bat'
  yield 'baz'
end