Class: RDoc::Context::Section

### Home Classes Methods

### In Files

- lib/rdoc/context/section.rb
- lib/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

- RDoc::Text
- RDoc::Generator::Markup

### Files

- CVE-2013-0256.rdoc
- DEVELOPERS.rdoc
- LICENSE.rdoc
- Manifest.txt
- README.rdoc
- RI.rdoc
- Rakefile
- TODO.rdoc

### Class/Module Index

Quicksearch

- RDoc
- RDoc::Alias
- RDoc::AnonClass
- RDoc::AnyMethod
- RDoc::Attr
- RDoc::ClassModule
- RDoc::CodeObject
- RDoc::Comment
- RDoc::Constant
- RDoc::Context
- RDoc::Context::Section
- RDoc::CrossReference
- RDoc::ERBIO
- RDoc::ERBPartial
- RDoc::Encoding
- RDoc::Error
- RDoc::Extend
- RDoc::Gauntlet
- RDoc::Generator
- RDoc::Generator::Darkfish
- RDoc::Generator::JsonIndex
- RDoc::Generator::Markup
- RDoc::Generator::RI
- RDoc::GhostMethod
- RDoc::Include
- RDoc::Markdown
- RDoc::Markdown::Literals
- RDoc::Markup
- RDoc::Markup::AttrChanger
- RDoc::Markup::AttrSpan
- RDoc::Markup::AttributeManager
- RDoc::Markup::Attributes
- RDoc::Markup::BlankLine
- RDoc::Markup::BlockQuote
- RDoc::Markup::Document
- RDoc::Markup::Formatter
- RDoc::Markup::FormatterTestCase
- RDoc::Markup::HardBreak
- RDoc::Markup::Include
- RDoc::Markup::IndentedParagraph
- RDoc::Markup::List
- RDoc::Markup::ListItem
- RDoc::Markup::Paragraph
- RDoc::Markup::Parser
- RDoc::Markup::Parser::Error
- RDoc::Markup::Parser::ParseError
- RDoc::Markup::PreProcess
- RDoc::Markup::Raw
- RDoc::Markup::Rule
- RDoc::Markup::Special
- RDoc::Markup::TextFormatterTestCase
- RDoc::Markup::ToAnsi
- RDoc::Markup::ToBs
- RDoc::Markup::ToHtml
- RDoc::Markup::ToHtmlCrossref
- RDoc::Markup::ToHtmlSnippet
- RDoc::Markup::ToJoinedParagraph
- RDoc::Markup::ToLabel
- RDoc::Markup::ToMarkdown
- RDoc::Markup::ToRdoc
- RDoc::Markup::ToTableOfContents
- RDoc::Markup::ToTest
- RDoc::Markup::ToTtOnly
- RDoc::Markup::Verbatim
- RDoc::MetaMethod
- RDoc::MethodAttr
- RDoc::NormalClass
- RDoc::NormalModule
- RDoc::Options
- RDoc::Parser
- RDoc::Parser::C
- RDoc::Parser::ChangeLog
- RDoc::Parser::Markdown
- RDoc::Parser::RD
- RDoc::Parser::Ruby
- RDoc::Parser::RubyTools
- RDoc::Parser::Simple
- RDoc::Parser::Text
- RDoc::RD
- RDoc::RD::BlockParser
- RDoc::RD::Inline
- RDoc::RD::InlineParser
- RDoc::RDoc
- RDoc::RI
- RDoc::RI::Driver
- RDoc::RI::Driver::Error
- RDoc::RI::Driver::NotFoundError
- RDoc::RI::Error
- RDoc::RI::Paths
- RDoc::Require
- RDoc::RubyLex
- RDoc::RubyLex::Error
- RDoc::RubyToken
- RDoc::RubygemsHook
- RDoc::Servlet
- RDoc::SingleClass
- RDoc::Stats
- RDoc::Stats::Normal
- RDoc::Stats::Quiet
- RDoc::Stats::Verbose
- RDoc::Store
- RDoc::Store::Error
- RDoc::Store::MissingFileError
- RDoc::Task
- RDoc::Task
- RDoc::TestCase
- RDoc::TokenStream
- RDoc::TomDoc
- RDoc::TopLevel
- Object

No matching classes.

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

    # 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.