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/code_object/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, SPACE_SEPARATED_LETTER_CLASS

Class Method Summary

Instance Attribute Summary

::RDoc::Text - Included

#language

The language for this text.

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

The preferred URL for this object.
#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

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

Wraps txt to line_len

Constructor Details

.new(parent, title, comment, store = nil) ⇒ Section

Creates a new section with #title and #comment

[ GitHub ] 

  


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



def initialize(parent, title, comment, store = nil)
  @parent = parent
  @title = title ? title.strip : title
  @store = store

  @comments = []

  add_comment comment
end


  







Instance Attribute Details



  

    #comments   (readonly)
  



  

    
Section comments

  



  [ GitHub ]


  

  


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



attr_reader :comments


  








  

    #parent   (readonly)
  



  

    
::RDoc::Context this Section lives in

  



  [ GitHub ]


  

  


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



attr_reader :parent


  








  

    #store   (readonly)
  



  

    
The ::RDoc::Store for this object.

  



  [ GitHub ]


  

  


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



attr_reader :store


  








  

    #title   (readonly)
  



  

    
Section title

  



  [ GitHub ]


  

  


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



attr_reader :title


  







Instance Method Details



  

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



  

    
Sections are equal when they have the same #title

  



  [ GitHub ]


  

  


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



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


  








  

    #add_comment(comment)  
  



  

    
Adds #comment to this section

  



  [ GitHub ]


  

  


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



def add_comment(comment)
  Array(comment).each do |c|
    next if c.nil?
    raise TypeError, "unknown comment #{c.inspect}" unless RDoc::Comment === c
    @comments << c unless c.empty?
  end
end


  








  

    #aref  
  



  

    
Anchor reference for linking to this section using GitHub-style format.


Examples:


"Section"     -> "section"
"One Two"     -> "one-two"
"[untitled]"  -> "untitled"

  



  [ GitHub ]


  

  


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



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

  RDoc::Text.to_anchor(title)
end


  








  

    #comment  
  



  

    
Section comment

  



  [ GitHub ]


  

  


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



def comment
  return nil if @comments.empty?
  RDoc::Comment.from_document(to_document)
end


  








  

    #description  
  

  [ GitHub ]


  

  


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



def description
  return '' if @comments.empty?
  markup comment
end


  








  

    #eql?(other)  
  



  

    
::RDoc::Alias for #==.

  



  [ GitHub ]


  

  


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



alias eql? ==


  








  

    #hash  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



def hash # :nodoc:
  @title.hash
end


  








  

    #in_files  
  



  

    
The files comments in this section come from

  



  [ GitHub ]


  

  


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



def in_files
  @comments.map(&:file)
end


  








  

    #inspect  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


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



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


  








  

    #language  
  

  [ GitHub ]


  

  


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



def language
  @comments.first&.language
end


  








  

    #legacy_aref  
  



  

    
Legacy anchor reference for backward compatibility.


Examples:


"Section"     -> "section"
"One Two"     -> "one+two"
"[untitled]"  -> "5Buntitled-5D"

  



  [ GitHub ]


  

  


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



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

  CGI.escape(title).gsub('%', '-').sub(/^-/, '')
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/code_object/context/section.rb', line 120



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


  








  

    #marshal_load(array)  
  



  

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

  



  [ GitHub ]


  

  


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



def marshal_load(array)
  @parent  = nil

  @title    = array[1]
  @comments = array[2].parts.map { |doc| RDoc::Comment.from_document(doc) }
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/code_object/context/section.rb', line 151



def plain_html
  @title || 'Top Section'
end


  








  

    #remove_comment(target_comment)  
  



  

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

  



  [ GitHub ]


  

  


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



def remove_comment(target_comment)
  @comments.delete_if do |stored_comment|
    stored_comment.file == target_comment.file
  end
end


  








  

    #to_document  
  



  

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

  



  [ GitHub ]


  

  


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



def to_document
  RDoc::Markup::Document.new(*@comments.map(&:parse))
end