123456789_123456789_123456789_123456789_123456789_

Class: RDoc::Context::Section

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::RDoc::Generator::Markup, ::RDoc::Text
Inherits: Object
Defined in: lib/rdoc/context/section.rb,
lib/rdoc/generator/markup.rb

Overview

A section of documentation like:

# :section: The title
# The body

Sections can be referenced multiple times and will be collapsed into a single section.

Constant Summary

::RDoc::Text - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Method Summary

Instance Attribute Summary

Instance Method Summary

::RDoc::Generator::Markup - Included

#aref_to

Generates a relative URL from this object's path to target_path
#as_href

Generates a relative URL from from_path to this object's path.
#cvs_url

Build a webcvs URL starting for the given url with full_path appended as the destination path.
#description

Handy wrapper for marking up this object's comment.
#formatter

Creates an ::RDoc::Markup::ToHtmlCrossref formatter.

::RDoc::Text - Included

#expand_tabs

Expands tab characters in text to eight spaces.
#flush_left

Flush text left based on the shortest line.
#markup

Convert a string in markup format into HTML.
#normalize_comment

Strips hashes, expands tabs then flushes text to the left.
#parse

Normalizes text then builds a ::RDoc::Markup::Document from it.
#snippet

The first limit characters of text as HTML.
#strip_hashes

Strips leading # characters from text
#strip_newlines

Strips leading and trailing n characters from text
#strip_stars

Strips /* */ style comments.
#to_html

Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in text to properly encoded characters.
#wrap

Wraps txt to line_len

Constructor Details

.new(parent, title, comment) ⇒ Section

Creates a new section with #title and #comment

[ GitHub ] 

  


# 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


  







Instance Attribute Details



  

    #comment   (readonly)
  



  

    

Section comment


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 20



attr_reader :comment


  








  

    #comments   (readonly)
  



  

    

Section comments


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 25



attr_reader :comments


  








  

    #parent   (readonly)
  



  

    

::RDoc::Context this Section lives in


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 30



attr_reader :parent


  








  

    #title   (readonly)
  



  

    

Section title


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 35



attr_reader :title


  







Instance Method Details



  

    #==(other)  
    Also known as: #eql?
  



  

    

Sections are equal when they have the same #title


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 57



def == other
  self.class === other and @title == other.title
end


  








  

    #add_comment(comment)  
  



  

    

Adds #comment to this section


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 66



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  
  



  

    

Anchor reference for linking to this section


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 86



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

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


  








  

    #eql?(other)  
  



  

    

::RDoc::Alias for #==.


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 61



alias eql? ==


  








  

    #extract_comment(comment)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 101



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  
  



  

    

The files comments in this section come from


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 140



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  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 161



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


  








  

    #marshal_load(array)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 172



def marshal_load array
  @parent  = nil

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


  








  

    #parse  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 183



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  
  



  

    

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.


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 211



def plain_html
  @title || 'Top Section'
end


  








  

    #remove_comment(comment)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 219



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  
  



  

    

Section sequence number (deprecated)


  



  [ GitHub ]


  

  


# File 'lib/rdoc/context/section.rb', line 239



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