# 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

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 34
    def initialize parent, title, comment
      @parent = parent
      @title = title ? title.strip : title

      @@sequence.succ!
      @sequence = @@sequence.dup

      @comment = nil
      @comment = extract_comment comment if 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 48
    def == other
      self.class === other and @title == other.title
    end

aref() click to toggle source

Anchor reference for linking to this section

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

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

comment=(comment) click to toggle source

Appends `comment` to the current comment separated by a rule.

    # File lib/rdoc/context/section.rb, line 64
    def comment= comment
      comment = extract_comment comment

      return if comment.empty?

      if @comment then
        # HACK should section comments get joined?
        @comment.text += "\n# ---\n#{comment.text}"
      else
        @comment = comment
      end
    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 86
    def extract_comment comment
      if comment.text =~ %r^#[ \t]*:section:.*\n/ then
        start = $`
        rest = $'

        comment.text = if start.empty? then
                         rest
                       else
                         rest.sub(%r#{start.chomp}\Z/, '')
                       end
      end

      comment
    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 110
    def plain_html
      @title || 'Top Section'
    end

sequence() click to toggle source

Section sequence number (deprecated)

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