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) click to toggle source

Creates a new section with title and comment

# File lib/rdoc/context/section.rb, line 41
def initialize parent, title, comment
 @parent = parent
 @title = title ? title.strip : title
 @@sequence.succ!
 @sequence = @@sequence.dup
 @comments = []
 add_comment comment
end

Public Instance Methods

==(other) click to toggle source

Sections are equal when they have the same title

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

add_comment(comment) click to toggle source

Adds comment to this section

# File lib/rdoc/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() click to toggle source

Anchor reference for linking to this section

# File lib/rdoc/context/section.rb, line 83
def aref
 title = @title || '[untitled]'
 CGI.escape(title).gsub('%', '-').sub(/^-/, '')
end

extract_comment(comment) click to toggle source

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

# File lib/rdoc/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() click to toggle source

The files comments in this section come from

# File lib/rdoc/context/section.rb, line 133
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() click to toggle source

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

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

marshal_load(array) click to toggle source

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

# File lib/rdoc/context/section.rb, line 165
def marshal_load array
 @parent = nil
 @title = array[1]
 @comments = array[2]
end

parse() click to toggle source

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

Calls superclass method RDoc::Text#parse

# File lib/rdoc/context/section.rb, line 176
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() click to toggle source

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/context/section.rb, line 204
def plain_html
 @title || 'Top Section'
end

remove_comment(comment) click to toggle source

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

# File lib/rdoc/context/section.rb, line 212
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

sequence() click to toggle source

Section sequence number (deprecated)

# File lib/rdoc/context/section.rb, line 232
def sequence
 warn "RDoc::Context::Section#sequence is deprecated, use #aref"
 @sequence
end