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

comment [R]

Section comment

comments [R]

Section comments

parent [R]

Context this Section lives in

title [R]

Section title

Public Class Methods

new (parent, title, comment)

Source

# File lib/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

Creates a new section with title and comment

Public Instance Methods

== (other)

Source

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

Sections are equal when they have the same title

Also aliased as: eql?

add_comment (comment)

Source

# File lib/rdoc/code_object/context/section.rb, line 63
def add_comment comment
  comments = Array(comment)
  comments.each do |c|
    extracted_comment = extract_comment(c)
    @comments << extracted_comment unless extracted_comment.empty?
  end
end

Adds comment to this section

aref ()

Source

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

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

Anchor reference for linking to this section

eql? (other)

Alias for: ==

extract_comment (comment)

Source

# File lib/rdoc/code_object/context/section.rb, line 89
def extract_comment comment
  case comment
  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
  else
    raise TypeError, "unknown comment #{comment.inspect}"
  end
end

Extracts the comment for this section from the original comment block. If the first line contains :section:, strip it and use the rest. Otherwise remove lines up to the line containing :section:, and look for those lines again at the end and remove them. This lets us write

# :section: The title
# The body

in_files ()

Source

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

The files comments in this section come from

marshal_dump ()

Source

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

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

marshal_load (array)

Source

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

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

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

parse ()

Source

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

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

plain_html ()

Source

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

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.

remove_comment (target_comment)

Source

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

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