Class: RDoc::Context::Section
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
|
|
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
-
MARSHAL_VERSION =
Internal use only
# File 'lib/rdoc/code_object/context/section.rb', line 170
::RDoc::Text
- Included
MARKUP_FORMAT, SPACE_SEPARATED_LETTER_CLASS, TO_HTML_CHARACTERS
Class Method Summary
- .new(parent, title, comment) ⇒ Section constructor
Instance Attribute Summary
-
#comment
readonly
Section
comment. -
#comments
readonly
Section
comments. -
#parent
readonly
::RDoc::Context
thisSection
lives in. -
#title
readonly
Section
title.
::RDoc::Text
- Included
#language | The language for this text. |
Instance Method Summary
-
#==(other)
(also: #eql?)
Sections are equal when they have the same #title
-
#add_comment(comment)
Adds #comment to this section.
-
#aref
Anchor reference for linking to this section.
-
#eql?(other)
::RDoc::Alias
for #==. -
#extract_comment(comment)
Extracts the comment for this section from the original comment block.
-
#in_files
The files comments in this section come from.
-
#marshal_dump
Serializes this
Section
. -
#marshal_load(array)
De-serializes this
Section
. -
#parse
Parses
comment_location
into an::RDoc::Markup::Document
composed of multipleRDoc::Markup::Documents
with their file set. -
#plain_html
The section’s title, or ‘Top Section’ if the title is nil.
-
#remove_comment(comment)
Removes a comment from this section if it is from the same file as #comment
- #hash Internal use only
- #inspect Internal use only
::RDoc::Generator::Markup
- Included
#aref_to | Generates a relative URL from this object’s path to |
#as_href | Generates a relative URL from |
#cvs_url | Build a webcvs URL starting for the given |
#description | Handy wrapper for marking up this object’s comment. |
#formatter | Creates an |
::RDoc::Text
- Included
#expand_tabs | Expands tab characters in |
#flush_left | Flush |
#markup | Convert a string in markup format into HTML. |
#normalize_comment | Strips hashes, expands tabs then flushes |
#parse | Normalizes |
#snippet | The first |
#strip_hashes | Strips leading # characters from |
#strip_newlines | Strips leading and trailing n characters from |
#strip_stars | Strips /* */ style comments. |
#to_html | Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in |
#wrap | Wraps |
Constructor Details
.new(parent, title, comment) ⇒ Section
[ GitHub ]
Instance Attribute Details
#comment (readonly)
Section
comment
# File 'lib/rdoc/code_object/context/section.rb', line 22
attr_reader :comment
#comments (readonly)
Section
comments
# File 'lib/rdoc/code_object/context/section.rb', line 27
attr_reader :comments
#parent (readonly)
::RDoc::Context
this Section
lives in
# File 'lib/rdoc/code_object/context/section.rb', line 32
attr_reader :parent
#title (readonly)
Section
title
# File 'lib/rdoc/code_object/context/section.rb', line 37
attr_reader :title
Instance Method Details
#==(other) Also known as: #eql?
Sections are equal when they have the same #title
# File 'lib/rdoc/code_object/context/section.rb', line 54
def == other self.class === other and @title == other.title end
#add_comment(comment)
Adds #comment to this section
# File 'lib/rdoc/code_object/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
Anchor reference for linking to this section
#eql?(other)
::RDoc::Alias
for #==.
# File 'lib/rdoc/code_object/context/section.rb', line 58
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
# File 'lib/rdoc/code_object/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
#hash
# File 'lib/rdoc/code_object/context/section.rb', line 130
def hash # :nodoc: @title.hash end
#in_files
The files comments in this section come from
# File 'lib/rdoc/code_object/context/section.rb', line 137
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
#inspect
# File 'lib/rdoc/code_object/context/section.rb', line 126
def inspect # :nodoc: "#<%s:0x%x %p>" % [self.class, object_id, title] end
#marshal_dump
Serializes this Section
. The title and parsed comment are saved, but not the section parent which must be restored manually.
# File 'lib/rdoc/code_object/context/section.rb', line 158
def marshal_dump [ MARSHAL_VERSION, @title, parse, ] end
#marshal_load(array)
De-serializes this Section
. The section parent must be restored manually.
# File 'lib/rdoc/code_object/context/section.rb', line 169
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.
# File 'lib/rdoc/code_object/context/section.rb', line 180
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.
# File 'lib/rdoc/code_object/context/section.rb', line 208
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
# File 'lib/rdoc/code_object/context/section.rb', line 216
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