class RDoc::Context::Section

类似这样的文档的节

# :section: The title
# The body

节可以被多次引用，并会被合并成一个单独的节。

属性

comment[R]

Section 注释

comments[R]

Section 注释

parent[R]

此Section所在的上下文

title[R]

Section 标题

公共类方法

new(parent, title, comment) 点击切换源代码

创建一个新的节，带有 title 和 comment

# File rdoc/code_object/context/section.rb, line 42
def initialize parent, title, comment
  @parent = parent
  @title = title ? title.strip : title

  @comments = []

  add_comment comment
end

公共实例方法

==(other) 点击切换源代码

当节具有相同的 title 时，它们是相等的

# File rdoc/code_object/context/section.rb, line 54
def == other
  self.class === other and @title == other.title
end

也别名为: eql?

add_comment(comment) 点击切换源代码

将 comment 添加到此节

# File rdoc/code_object/context/section.rb, line 63
def add_comment comment
  comment = extract_comment comment

  return if comment.empty?

  case comment
  when RDoc::Comment then
    @comments << comment
  when RDoc::Markup::Document then
    @comments.concat comment.parts
  when Array then
    @comments.concat comment
  else
    raise TypeError, "unknown comment type: #{comment.inspect}"
  end
end

aref() 点击切换源代码

链接到此节的锚点引用

# File rdoc/code_object/context/section.rb, line 83
def aref
  title = @title || '[untitled]'

  CGI.escape(title).gsub('%', '-').sub(/^-/, '')
end

eql?(other)

别名为: ==

extract_comment(comment) 点击切换源代码

从此节的原始注释块中提取注释。如果第一行包含 :section:，则将其剥离并使用其余部分。否则，删除直到包含 :section: 的行，然后在末尾再次查找这些行并删除它们。这允许我们这样写

# :section: The title
# The body

# File rdoc/code_object/context/section.rb, line 98
def extract_comment comment
  case comment
  when Array then
    comment.map do |c|
      extract_comment c
    end
  when nil
    RDoc::Comment.new ''
  when RDoc::Comment then
    if comment.text =~ /^#[ \t]*:section:.*\n/ then
      start = $`
      rest = $'

      comment.text = if start.empty? then
                       rest
                     else
                       rest.sub(/#{start.chomp}\Z/, '')
                     end
    end

    comment
  when RDoc::Markup::Document then
    comment
  else
    raise TypeError, "unknown comment #{comment.inspect}"
  end
end

in_files() 点击切换源代码

此节中的注释来自的文件

# File rdoc/code_object/context/section.rb, line 137
def in_files
  return [] if @comments.empty?

  case @comments
  when Array then
    @comments.map do |comment|
      comment.file
    end
  when RDoc::Markup::Document then
    @comment.parts.map do |document|
      document.file
    end
  else
    raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
  end
end

marshal_dump() 点击切换源代码

序列化此 Section。将保存标题和解析后的注释，但不保存节的父级，必须手动恢复。

# File rdoc/code_object/context/section.rb, line 158
def marshal_dump
  [
    MARSHAL_VERSION,
    @title,
    parse,
  ]
end

marshal_load(array) 点击切换源代码

反序列化此 Section。必须手动恢复节的父级。

# File rdoc/code_object/context/section.rb, line 169
def marshal_load array
  @parent  = nil

  @title    = array[1]
  @comments = array[2]
end

parse() 点击切换源代码

将 comment_location 解析为由多个设置了文件的 RDoc::Markup::Documents 组成的 RDoc::Markup::Document。

调用超类方法 RDoc::Text#parse

# File rdoc/code_object/context/section.rb, line 180
def parse
  case @comments
  when String then
    super
  when Array then
    docs = @comments.map do |comment, location|
      doc = super comment
      doc.file = location if location
      doc
    end

    RDoc::Markup::Document.new(*docs)
  when RDoc::Comment then
    doc = super @comments.text, comments.format
    doc.file = @comments.location
    doc
  when RDoc::Markup::Document then
    return @comments
  else
    raise ArgumentError, "unknown comment class #{comments.class}"
  end
end

plain_html() 点击切换源代码

该节的标题，如果标题为 nil，则为“顶层节”。

这被目录模板使用，所以名称很傻。

# File rdoc/code_object/context/section.rb, line 208
def plain_html
  @title || 'Top Section'
end

remove_comment(comment) 点击切换源代码

如果注释与 comment 来自同一文件，则从此节删除注释

# File rdoc/code_object/context/section.rb, line 216
def remove_comment comment
  return if @comments.empty?

  case @comments
  when Array then
    @comments.delete_if do |my_comment|
      my_comment.file == comment.file
    end
  when RDoc::Markup::Document then
    @comments.parts.delete_if do |document|
      document.file == comment.file.name
    end
  else
    raise RDoc::Error, "BUG: unknown comment class #{@comments.class}"
  end
end