Class: RDoc::Comment
Overview
A comment holds the text comment for a RDoc::CodeObject and provides a unified way of cleaning it up and parsing it into an RDoc::Markup::Document.
Each comment may have a different markup format set by #format=. By default ‘rdoc’ is used. The :markup: directive tells RDoc which format to use.
See RDoc::Markup@Other+directives for instructions on adding an alternate format.
Constant Summary
Constants included from Text
Text::MARKUP_FORMAT, Text::TO_HTML_CHARACTERS
Instance Attribute Summary collapse
-
#document ⇒ Object
writeonly
Overrides the content returned by #parse.
-
#format ⇒ Object
The format of this comment.
-
#location ⇒ Object
(also: #file)
The RDoc::TopLevel this comment was found in.
-
#text ⇒ Object
The text for this comment.
Instance Method Summary collapse
-
#==(other) ⇒ Object
:nodoc:.
-
#empty? ⇒ Boolean
A comment is empty if its text String is empty.
-
#extract_call_seq(method) ⇒ Object
Look for a ‘call-seq’ in the comment to override the normal parameter handling.
-
#force_encoding(encoding) ⇒ Object
HACK dubious.
-
#initialize(text = nil, location = nil) ⇒ Comment
constructor
Creates a new comment with
text
that is found in the RDoc::TopLevellocation
. -
#initialize_copy(copy) ⇒ Object
– TODO deep copy @document.
-
#inspect ⇒ Object
:nodoc:.
-
#normalize ⇒ Object
Normalizes the text.
-
#normalized? ⇒ Boolean
Was this text normalized?.
-
#parse ⇒ Object
Parses the comment into an RDoc::Markup::Document.
-
#remove_private ⇒ Object
Removes private sections from this comment.
-
#tomdoc? ⇒ Boolean
Returns true if this comment is in TomDoc format.
Methods included from Text
encode_fallback, #expand_tabs, #flush_left, #markup, #normalize_comment, #snippet, #strip_hashes, #strip_newlines, #strip_stars, #to_html, #wrap
Constructor Details
#initialize(text = nil, location = nil) ⇒ Comment
Creates a new comment with text
that is found in the RDoc::TopLevel location
.
45 46 47 48 49 50 51 52 |
# File 'lib/rdoc/comment.rb', line 45 def initialize text = nil, location = nil @location = location @text = text @document = nil @format = 'rdoc' @normalized = false end |
Instance Attribute Details
#document=(value) ⇒ Object (writeonly)
Overrides the content returned by #parse. Use when there is no #text source for this comment
39 40 41 |
# File 'lib/rdoc/comment.rb', line 39 def document=(value) @document = value end |
#format ⇒ Object
The format of this comment. Defaults to RDoc::Markup
18 19 20 |
# File 'lib/rdoc/comment.rb', line 18 def format @format end |
#location ⇒ Object Also known as: file
The RDoc::TopLevel this comment was found in
23 24 25 |
# File 'lib/rdoc/comment.rb', line 23 def location @location end |
#text ⇒ Object
The text for this comment
33 34 35 |
# File 'lib/rdoc/comment.rb', line 33 def text @text end |
Instance Method Details
#==(other) ⇒ Object
:nodoc:
62 63 64 65 |
# File 'lib/rdoc/comment.rb', line 62 def == other # :nodoc: self.class === other and other.text == @text and other.location == @location end |
#empty? ⇒ Boolean
A comment is empty if its text String is empty.
131 132 133 |
# File 'lib/rdoc/comment.rb', line 131 def empty? @text.empty? end |
#extract_call_seq(method) ⇒ Object
Look for a ‘call-seq’ in the comment to override the normal parameter handling. The :call-seq: is indented from the baseline. All lines of the same indentation level and prefix are consumed.
For example, all of the following will be used as the :call-seq:
# :call-seq:
# ARGF.readlines(sep=$/) -> array
# ARGF.readlines(limit) -> array
# ARGF.readlines(sep, limit) -> array
#
# ARGF.to_a(sep=$/) -> array
# ARGF.to_a(limit) -> array
# ARGF.to_a(sep, limit) -> array
83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 |
# File 'lib/rdoc/comment.rb', line 83 def extract_call_seq method # we must handle situations like the above followed by an unindented first # comment. The difficulty is to make sure not to match lines starting # with ARGF at the same indent, but that are after the first description # paragraph. if @text =~ /^\s*:?call-seq:(.*?(?:\S).*?)^\s*$/m then all_start, all_stop = $~.offset(0) seq_start, seq_stop = $~.offset(1) # we get the following lines that start with the leading word at the # same indent, even if they have blank lines before if $1 =~ /(^\s*\n)+^(\s*\w+)/m then leading = $2 # ' * ARGF' in the example above re = %r% \A( (^\s*\n)+ (^#{Regexp.escape leading}.*?\n)+ )+ ^\s*$ %xm if @text[seq_stop..-1] =~ re then all_stop = seq_stop + $~.offset(0).last seq_stop = seq_stop + $~.offset(1).last end end seq = @text[seq_start..seq_stop] seq.gsub!(/^\s*(\S|\n)/m, '\1') @text.slice! all_start...all_stop method.call_seq = seq.chomp elsif @text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/m, '') then seq = $1 seq.gsub!(/^\s*/, '') method.call_seq = seq end #elsif @text.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then # method.call_seq = $1.strip #end method end |
#force_encoding(encoding) ⇒ Object
HACK dubious
138 139 140 |
# File 'lib/rdoc/comment.rb', line 138 def force_encoding encoding @text.force_encoding encoding end |
#initialize_copy(copy) ⇒ Object
– TODO deep copy @document
58 59 60 |
# File 'lib/rdoc/comment.rb', line 58 def initialize_copy copy # :nodoc: @text = copy.text.dup end |
#inspect ⇒ Object
:nodoc:
150 151 152 153 154 |
# File 'lib/rdoc/comment.rb', line 150 def inspect # :nodoc: location = @location ? @location.relative_name : '(unknown)' "#<%s:%x %s %p>" % [self.class, object_id, location, @text] end |
#normalize ⇒ Object
Normalizes the text. See RDoc::Text#normalize_comment for details
159 160 161 162 163 164 165 166 167 168 |
# File 'lib/rdoc/comment.rb', line 159 def normalize return self unless @text return self if @normalized # TODO eliminate duplicate normalization @text = normalize_comment @text @normalized = true self end |
#normalized? ⇒ Boolean
Was this text normalized?
173 174 175 |
# File 'lib/rdoc/comment.rb', line 173 def normalized? # :nodoc: @normalized end |
#parse ⇒ Object
Parses the comment into an RDoc::Markup::Document. The parsed document is cached until the text is changed.
181 182 183 184 185 186 187 |
# File 'lib/rdoc/comment.rb', line 181 def parse return @document if @document @document = super @text, @format @document.file = @location @document end |
#remove_private ⇒ Object
Removes private sections from this comment. Private sections are flush to the comment marker and start with --
and end with ++
. For C-style comments, a private marker may not start at the opening of the comment.
/*
*--
* private
*++
* public
*/
202 203 204 205 206 207 208 209 |
# File 'lib/rdoc/comment.rb', line 202 def remove_private # Workaround for gsub encoding for Ruby 1.9.2 and earlier empty = '' empty.force_encoding @text.encoding if Object.const_defined? :Encoding @text = @text.gsub(%r%^\s*([#*]?)--.*?^\s*(\1)\+\+\n?%m, empty) @text = @text.sub(%r%^\s*[#*]?--.*%m, '') end |
#tomdoc? ⇒ Boolean
Returns true if this comment is in TomDoc format.
227 228 229 |
# File 'lib/rdoc/comment.rb', line 227 def tomdoc? @format == 'tomdoc' end |