class RDoc::MarkupReference

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

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

关于示例 ↑

  • 此参考中的示例是 Ruby 代码和注释；其中指出与其他来源（例如 C 代码和注释）的某些差异。

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

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

    一些东西

RDoc 来源 ↑

RDoc 文档的来源因文件类型而异

  • .rb（Ruby 代码文件）

    • 可以在 Ruby 注释中找到标记：紧接在 Ruby 类、模块、方法、别名、常量或属性定义之前的注释将成为该已定义对象的文档。

    • 可以在以下位置找到 RDoc 指令

      • 尾随注释（与代码在同一行）；请参阅 :nodoc:、:doc: 和 :notnew:。

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

    • 文档可以从 Ruby 代码本身派生；请参阅 从 Ruby 代码派生的文档。

  • .c (C 代码文件)：标记从 C 注释中解析。紧接在实现 Ruby 方法的函数之前的注释，或者紧接在 Ruby 对象定义之前的注释，将成为该对象的文档。

  • .rdoc (RDoc 标记文本文件) 或 .md (RDoc Markdown 文本文件)：标记从整个文件中解析。该文本未与任何代码对象关联，但可以（取决于文档的构建方式）成为单独的页面。

一个RDoc 文档

  • Ruby 或 C 文件中生成 RDoc 文档的（可能是多行的）注释（如上所述）。

  • 整个标记 (.rdoc) 文件或 Markdown (.md) 文件（通常是多行的）。

块 ↑

可以将 RDoc 文档视为各种类型块的序列（链接中的详细信息）

  • 段落：普通段落。

  • 原样文本块：要按字面呈现的文本块。

  • 代码块：包含 Ruby 代码的原样文本块，以代码高亮显示呈现。

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

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

  • 标题：标题。

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

  • 指令：各种特殊的呈现方向。

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

关于块

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

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

  • 在多行块中，RDoc 查找块的自然左边距，该边距成为块的基本边距，并且是块的初始当前边距。

段落 ↑

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

注意：此处，“普通文本”是指没有通过缩进或不寻常的初始或嵌入字符标识的文本。请参见下文。

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

示例输入

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

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

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

  • # :nodoc::

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

    • 指定应记录已定义的对象，即使它本来不会被记录。

  • # :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: 类型:

    • 单独出现在一行上。

    • 指定 RDoc 输入的格式；参数 type 是以下之一：rdoc（默认）、markdown、rd、tomdoc。请参阅 标记格式。

用于 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。

协议 ftp
协议 mailto
协议 irc
图像文件扩展名

  • 链接：https://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::MarkupReference#dummy_instance_method] 生成 foo。

  • 常量：bar[rdoc-ref:RDoc::MarkupReference::DUMMY_CONSTANT] 生成 bar。

  • 属性：baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute] 生成 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

带返回

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

  • {go to addressee}[rdoc-label:addressee:sender]

  • {return to sender}[rdoc-label:sender:addressee]

因此

go to addressee

一些文本。

return to sender

link: 方案
rdoc-image 方案

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

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

  • 链接：{rdoc-image:https://ruby-lang.org.cn/images/[email protected]}[https://ruby-lang.org.cn] 将图像 https://ruby-lang.org.cn/images/[email protected] 显示为链接到 https://ruby-lang.org.cn。

作为目标的相对路径也有效

  • 链接：{rdoc-image:https://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 会记录

  • 方法名称。

  • 参数。

  • 产生的值。

请参阅 method。

别名

默认情况下，RDoc 会记录

  • 别名名称。

  • 别名名称。

请参阅 dummy_instance_alias 和 dummy_instance_method。

常量

默认情况下，RDoc 会记录

  • 常量名称。

请参阅 DUMMY_CONSTANT。

属性

默认情况下，RDoc 会记录

  • 属性名称。

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

请参阅 dummy_attribute。

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

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

关于示例 ↑

  • 此参考中的示例是 Ruby 代码和注释；其中指出与其他来源（例如 C 代码和注释）的某些差异。

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

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

    一些东西

RDoc 来源 ↑

RDoc 文档的来源因文件类型而异

  • .rb（Ruby 代码文件）

    • 可以在 Ruby 注释中找到标记：紧接在 Ruby 类、模块、方法、别名、常量或属性定义之前的注释将成为该已定义对象的文档。

    • 可以在以下位置找到 RDoc 指令

      • 尾随注释（与代码在同一行）；请参阅 :nodoc:、:doc: 和 :notnew:。

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

    • 文档可以从 Ruby 代码本身派生；请参阅 从 Ruby 代码派生的文档。

  • .c (C 代码文件)：标记从 C 注释中解析。紧接在实现 Ruby 方法的函数之前的注释，或者紧接在 Ruby 对象定义之前的注释，将成为该对象的文档。

  • .rdoc (RDoc 标记文本文件) 或 .md (RDoc Markdown 文本文件)：标记从整个文件中解析。该文本未与任何代码对象关联，但可以（取决于文档的构建方式）成为单独的页面。

一个RDoc 文档

  • Ruby 或 C 文件中生成 RDoc 文档的（可能是多行的）注释（如上所述）。

  • 整个标记 (.rdoc) 文件或 Markdown (.md) 文件（通常是多行的）。

块 ↑

可以将 RDoc 文档视为各种类型块的序列（链接中的详细信息）

  • 段落：普通段落。

  • 原样文本块：要按字面呈现的文本块。

  • 代码块：包含 Ruby 代码的原样文本块，以代码高亮显示呈现。

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

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

  • 标题：标题。

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

  • 指令：各种特殊的呈现方向。

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

关于块

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

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

  • 在多行块中，RDoc 查找块的自然左边距，该边距成为块的基本边距，并且是块的初始当前边距。

段落 ↑

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

注意：此处，“普通文本”是指没有通过缩进或不寻常的初始或嵌入字符标识的文本。请参见下文。

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

示例输入

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

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

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

  • # :nodoc::

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

    • 指定应记录已定义的对象，即使它本来不会被记录。

  • # :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: 类型:

    • 单独出现在一行上。

    • 指定 RDoc 输入的格式；参数 type 是以下之一：rdoc（默认）、markdown、rd、tomdoc。请参阅 标记格式。

用于 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。

协议 ftp
协议 mailto
协议 irc
图像文件扩展名

  • 链接：https://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::MarkupReference#dummy_instance_method] 生成 foo。

  • 常量：bar[rdoc-ref:RDoc::MarkupReference::DUMMY_CONSTANT] 生成 bar。

  • 属性：baz[rdoc-ref:RDoc::MarkupReference#dummy_attribute] 生成 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

带返回

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

  • {go to addressee}[rdoc-label:addressee:sender]

  • {return to sender}[rdoc-label:sender:addressee]

因此

go to addressee

一些文本。

return to sender

link: 方案
rdoc-image 方案

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

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

  • 链接：{rdoc-image:https://ruby-lang.org.cn/images/[email protected]}[https://ruby-lang.org.cn] 将图像 https://ruby-lang.org.cn/images/[email protected] 显示为链接到 https://ruby-lang.org.cn。

作为目标的相对路径也有效

  • 链接：{rdoc-image:https://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 会记录

  • 方法名称。

  • 参数。

  • 产生的值。

请参阅 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 1205
def self.dummy_singleton_method(foo, bar); end

公共实例方法

args_directive(baz) 单击以切换源代码

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

单击调用序列以查看代码。

# File rdoc/markup_reference.rb, line 1253
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 1245
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 1208
def dummy_instance_method(foo, bar); end
也别名为：dummy_instance_alias, dummy_instance_alias
method(foo, bar) { |'baz'| ... } 单击以切换源代码

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

单击调用序列以查看代码。

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

:yields: 指令会覆盖在 Ruby 代码中找到的实际 yield。

单击调用序列以查看代码。

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