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

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) ⇒ 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.

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/rdoc/comment.rb', line 128

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

  method
end

#force_encoding(encoding) ⇒ Object

HACK dubious



135
136
137
 
# File 'lib/rdoc/comment.rb', line 135

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:



147
148
149
150
151
 
# File 'lib/rdoc/comment.rb', line 147

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



156
157
158
159
160
161
162
163
164
165
 
# File 'lib/rdoc/comment.rb', line 156

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) 


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

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.



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

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



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

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.

Returns:

  • (Boolean) 


224
225
226
 
# File 'lib/rdoc/comment.rb', line 224

def tomdoc?
  @format == 'tomdoc'
end