class RDoc::Context::Section

A section of documentation like:

# :section: The title
# The body

Sections can be referenced multiple times and will be collapsed into a single section.

Attributes

comments [R]

Section comments

parent [R]

Context this Section lives in

store [R]

The RDoc::Store for this object.

title [R]

Section title

Public Class Methods

new (parent, title, comment, store = nil)

Creates a new section with title and comment

# File lib/rdoc/code_object/context/section.rb, line 45
def initialize(parent, title, comment, store = nil)
  @parent = parent
  @title = title ? title.strip : title
  @store = store

  @comments = []

  add_comment comment
end

Public Instance Methods

== (other)

Sections are equal when they have the same title

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

Also aliased as: eql?

add_comment (comment)

Adds comment to this section

# File lib/rdoc/code_object/context/section.rb, line 67
def add_comment(comment)
  Array(comment).each do |c|
    next if c.nil?
    raise TypeError, "unknown comment #{c.inspect}" unless Comment === c
    @comments << c unless c.empty?
  end
end

aref ()

Anchor reference for linking to this section using GitHub-style format.

Examples:

"Section"     -> "section"
"One Two"     -> "one-two"
"[untitled]"  -> "untitled"

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

  Text.to_anchor(title)
end

comment ()

Section comment

# File lib/rdoc/code_object/context/section.rb, line 160
def comment
  return nil if @comments.empty?
  Comment.from_document(to_document)
end

description ()

# File lib/rdoc/code_object/context/section.rb, line 165
def description
  return '' if @comments.empty?
  markup comment
end

eql? (other)

Alias for: ==

in_files ()

The files comments in this section come from

# File lib/rdoc/code_object/context/section.rb, line 114
def in_files
  @comments.map(&:file)
end

language ()

# File lib/rdoc/code_object/context/section.rb, line 170
def language
  @comments.first&.language
end

legacy_aref ()

Legacy anchor reference for backward compatibility.

Examples:

"Section"     -> "section"
"One Two"     -> "one+two"
"[untitled]"  -> "5Buntitled-5D"

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

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

marshal_dump ()

Serializes this Section. The title and parsed comment are saved, but not the section parent which must be restored manually.

# File lib/rdoc/code_object/context/section.rb, line 122
def marshal_dump
  [
    MARSHAL_VERSION,
    @title,
    to_document,
  ]
end

marshal_load (array)

De-serializes this Section. The section parent must be restored manually.

# File lib/rdoc/code_object/context/section.rb, line 133
def marshal_load(array)
  @parent  = nil

  @title    = array[1]
  @comments = array[2].parts.map { |doc| Comment.from_document(doc) }
end

plain_html ()

The section’s title, or ‘Top Section’ if the title is nil.

This is used by the table of contents template so the name is silly.

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

remove_comment (target_comment)

Removes a comment from this section if it is from the same file as comment

# File lib/rdoc/code_object/context/section.rb, line 178
def remove_comment(target_comment)
  @comments.delete_if do |stored_comment|
    stored_comment.file == target_comment.file
  end
end

to_document ()

Parses comment_location into an RDoc::Markup::Document composed of multiple RDoc::Markup::Documents with their file set.

# File lib/rdoc/code_object/context/section.rb, line 144
def to_document
  Markup::Document.new(*@comments.map(&:parse))
end