Class: RDoc::Comment

Inherits:
Object
  • Object
show all
Includes:
Text
Defined in:
lib/rdoc/comment.rb

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

Attributes included from Text

#language

Instance Method Summary collapse

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, language = nil) ⇒ Comment

Creates a new comment with text that is found in the RDoc::TopLevel location.



56
57
58
59
60
61
62
63
64
 
# File 'lib/rdoc/comment.rb', line 56

def initialize text = nil, location = nil, language = nil
  @location = location
  @text     = text.nil? ? nil : text.dup
  @language = language

  @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



50
51
52
 
# File 'lib/rdoc/comment.rb', line 50

def document=(value)
  @document = value
end

#format ⇒ Object

The format of this comment. Defaults to RDoc::Markup



19
20
21
 
# File 'lib/rdoc/comment.rb', line 19

def format
  @format
end

#line ⇒ Object

Line where this Comment was written



29
30
31
 
# File 'lib/rdoc/comment.rb', line 29

def line
  @line
end

#location ⇒ Object Also known as: file

The RDoc::TopLevel this comment was found in



24
25
26
 
# File 'lib/rdoc/comment.rb', line 24

def location
  @location
end

#text ⇒ Object Also known as: to_s

The text for this comment



39
40
41
 
# File 'lib/rdoc/comment.rb', line 39

def text
  @text
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



74
75
76
77
 
# File 'lib/rdoc/comment.rb', line 74

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.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/rdoc/comment.rb', line 144

def empty?
  @text.empty?
end

#encode!(encoding) ⇒ Object

HACK dubious



151
152
153
154
155
156
157
158
159
 
# File 'lib/rdoc/comment.rb', line 151

def encode! encoding
  # TODO: Remove this condition after Ruby 2.2 EOL
  if RUBY_VERSION < '2.3.0'
    @text = @text.force_encoding encoding
  else
    @text = String.new @text, encoding: encoding
  end
  self
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



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
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/rdoc/comment.rb', line 95

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

  else
    regexp = /^\s*:?call-seq:(.*?)(^\s*$|\z)/m
    if regexp =~ @text then
      @text = @text.sub(regexp, '')
      seq = $1
      seq.gsub!(/^\s*/, '')
      method.call_seq = seq
    end
  end

  method
end

#initialize_copy(copy) ⇒ Object

– TODO deep copy @document



70
71
72
 
# File 'lib/rdoc/comment.rb', line 70

def initialize_copy copy # :nodoc:
  @text = copy.text.dup
end

#inspect ⇒ Object

:nodoc:



169
170
171
172
173
 
# File 'lib/rdoc/comment.rb', line 169

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



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/rdoc/comment.rb', line 178

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?

Returns:

  • (Boolean) 


192
193
194
 
# File 'lib/rdoc/comment.rb', line 192

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.



200
201
202
203
204
205
206
 
# File 'lib/rdoc/comment.rb', line 200

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
 */



221
222
223
224
225
226
227
228
 
# File 'lib/rdoc/comment.rb', line 221

def remove_private
  # Workaround for gsub encoding for Ruby 1.9.2 and earlier
  empty = ''
  empty = RDoc::Encoding.change_encoding empty, @text.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.

Returns:

  • (Boolean) 


246
247
248
 
# File 'lib/rdoc/comment.rb', line 246

def tomdoc?
  @format == 'tomdoc'
end