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 42
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 57
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 64
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

##
# Anchor reference for linking to this section

def aref
  title = @title || '[untitled]'

  CGI.escape(title).gsub('%', '-').sub(/^-/, '')
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

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

def inspect # :nodoc:
  "#<%s:0x%x %p>" % [self.class, object_id, title]
end

##
# The files comments in this section come from

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

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

def marshal_dump
  [
    MARSHAL_VERSION,
    @title,
    parse,
  ]
end

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

def marshal_load array
  @parent  = nil

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

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

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

##
# 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.

def plain_html
  @title || 'Top Section'
end

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

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

##
# Section sequence number (deprecated)

def sequence
  warn "RDoc::Context::Section#sequence is deprecated, use #aref"
  @sequence
end

aref() click to toggle source

Anchor reference for linking to this section

# File lib/rdoc/context/section.rb, line 84
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 99
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 134
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 155
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 166
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 177
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 205
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 213
  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

  ##
  # Section sequence number (deprecated)

  def sequence
    warn "RDoc::Context::Section#sequence is deprecated, use #aref"
    @sequence
  end

end
sequence() click to toggle source

Section sequence number (deprecated)

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