Home Classes Methods

In Files

rdoc/context/section.rb
rdoc/generator/markup.rb

Parent

Object

Methods

::new
#==
#add_comment
#aref
#extract_comment
#in_files
#marshal_dump
#marshal_load
#parse
#plain_html
#remove_comment
#sequence

Included Modules

Class/Module Index

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

 
               # File 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 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 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 rdoc/context/section.rb, line 232
def sequence
  warn "RDoc::Context::Section#sequence is deprecated, use #aref"
  @sequence
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.