class RDoc::TomDoc

基于 TomDoc 1.0.0-rc1 (02adef9b5a) 的 TomDoc 解析器。

TomDoc 规范可以在 tomdoc.org 找到。

要选择 TomDoc 作为您的唯一默认格式，请参阅 RDoc::Options 的“已保存选项”，了解有关设置 .rdoc_options 文件以存储项目默认值的说明。

此解析器和规范之间存在一些差异。我们尽力遵循规范，但做出了一些偏离的选择。

未来版本的 RDoc 将在违反 MUST 或 MUST NOT 时发出警告，并可能在违反 SHOULD 或 SHOULD NOT 时发出警告。RDoc 将始终尝试发出文档，即使给定的 TomDoc 无效。

以下是此解析器当前做出的一些实现选择：

此解析器允许 rdoc 风格的内联标记，但您不应依赖它。

此解析器允许注释和方法体之间存在空格。

此解析器不要求描述可选参数的默认值。

此解析器不检查章节的顺序。“示例”章节可能出现在“参数”章节之前。

此类以 TomDoc 格式记录。由于这是 RDoc 标记解析器的子类，因此遗憾的是这里没有什么可看的。

公开

↑ 顶部

公共类方法

new() 点击切换源代码

创建一个新的 TomDoc 解析器。另请参见 RDoc::Markup::parse

调用父类方法 RDoc::Markup::Parser::new

# File rdoc/tom_doc.rb, line 124
def initialize
  super

  @section      = nil
  @seen_returns = false
end

parse(text) 点击切换源代码

从文本中解析 TomDoc

text: 包含 TomDoc 格式文本的字符串。

示例¶ ↑

RDoc::TomDoc.parse <<-TOMDOC
This method does some things

Returns nothing.
TOMDOC
# => #<RDoc::Markup::Document:0xXXX @parts=[...], @file=nil>

返回值¶ ↑

返回一个表示 TomDoc 格式的 RDoc::Markup::Document。

# File rdoc/tom_doc.rb, line 78
def self.parse text
  parser = new

  parser.tokenize text
  doc = RDoc::Markup::Document.new
  parser.parse doc
  doc
end

内部

↑ 顶部

属性

tokens[R]

令牌访问器

公共类方法

signature(comment) 点击切换源代码

提取“签名”章节的方法签名

comment: 要解析并提取签名的 RDoc::Comment

返回值¶ ↑

返回一个包含签名的字符串，如果不存在则返回 nil

# File rdoc/tom_doc.rb, line 94
def self.signature comment
  return unless comment.tomdoc?

  document = comment.parse

  signature = nil
  found_heading = false
  found_signature = false

  document.parts.delete_if do |part|
    next false if found_signature

    found_heading ||=
      RDoc::Markup::Heading === part && part.text == 'Signature'

    next false unless found_heading

    next true if RDoc::Markup::BlankLine === part

    if RDoc::Markup::Verbatim === part then
      signature = part
      found_signature = true
    end
  end

  signature and signature.text
end

公共实例方法

build_heading(level) 点击切换源代码

从令牌流构建标题

level: 要创建的标题级别

返回值¶ ↑

返回一个 RDoc::Markup::Heading

调用父类方法 RDoc::Markup::Parser#build_heading

# File rdoc/tom_doc.rb, line 137
def build_heading level
  heading = super

  @section = heading.text

  heading
end

build_paragraph(margin) 点击切换源代码

从令牌流构建段落

margin: 未使用

返回值¶ ↑

返回一个 RDoc::Markup::Paragraph。

# File rdoc/tom_doc.rb, line 167
def build_paragraph margin
  p :paragraph_start => margin if @debug

  paragraph = RDoc::Markup::Paragraph.new

  until @tokens.empty? do
    type, data, = get

    case type
    when :TEXT then
      @section = 'Returns' if data =~ /\A(Returns|Raises)/

      paragraph << data
    when :NEWLINE then
      if :TEXT == peek_token[0] then
        # Lines beginning with 'Raises' in the Returns section should not be
        # treated as multiline text
        if 'Returns' == @section and
          peek_token[1].start_with?('Raises') then
          break
        else
          paragraph << ' '
        end
      else
        break
      end
    else
      unget
      break
    end
  end

  p :paragraph_end => margin if @debug

  paragraph
end

build_verbatim(margin) 点击切换源代码

从令牌流构建逐字记录。“示例”章节中的逐字记录将被标记为 Ruby 格式。

margin: 属于此逐字记录章节的行的边距缩进。

返回值¶ ↑

返回一个 RDoc::Markup::Verbatim

调用父类方法 RDoc::Markup::Parser#build_verbatim

# File rdoc/tom_doc.rb, line 153
def build_verbatim margin
  verbatim = super

  verbatim.format = :ruby if @section == 'Examples'

  verbatim
end

tokenize(text) 点击切换源代码

将文本转换为令牌数组

text: 包含 TomDoc 格式文本的字符串。

返回值¶ ↑

返回 self。

# File rdoc/tom_doc.rb, line 225
def tokenize text
  text = text.sub(/\A(Public|Internal|Deprecated):\s+/, '')

  setup_scanner text

  until @s.eos? do
    pos = @s.pos

    # leading spaces will be reflected by the column of the next token
    # the only thing we loose are trailing spaces at the end of the file
    next if @s.scan(/ +/)

    @tokens << case
               when @s.scan(/\r?\n/) then
                 token = [:NEWLINE, @s.matched, *pos]
                 @s.newline!
                 token
               when @s.scan(/(Examples|Signature)$/) then
                 @tokens << [:HEADER, 3, *pos]

                 [:TEXT, @s[1], *pos]
               when @s.scan(/([:\w][\w\[\]]*)[ ]+- /) then
                 [:NOTE, @s[1], *pos]
               else
                 @s.scan(/.*/)
                 [:TEXT, @s.matched.sub(/\r$/, ''), *pos]
               end
  end

  self
end