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.



51
52
53
54
55
56
57
58
59
 
# File 'lib/rdoc/comment.rb', line 51

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



45
46
47
 
# File 'lib/rdoc/comment.rb', line 45

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

#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



34
35
36
 
# File 'lib/rdoc/comment.rb', line 34

def text
  @text
end

Instance Method Details

#==(other) ⇒ Object

:nodoc:



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

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) 


139
140
141
 
# File 'lib/rdoc/comment.rb', line 139

def empty?
  @text.empty?
end

#encode!(encoding) ⇒ Object

HACK dubious



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

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



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
127
128
129
130
131
132
133
134
 
# File 'lib/rdoc/comment.rb', line 90

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



65
66
67
 
# File 'lib/rdoc/comment.rb', line 65

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

#inspect ⇒ Object

:nodoc:



164
165
166
167
168
 
# File 'lib/rdoc/comment.rb', line 164

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



173
174
175
176
177
178
179
180
181
182
 
# File 'lib/rdoc/comment.rb', line 173

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) 


187
188
189
 
# File 'lib/rdoc/comment.rb', line 187

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.



195
196
197
198
199
200
201
 
# File 'lib/rdoc/comment.rb', line 195

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



216
217
218
219
220
221
222
223
 
# File 'lib/rdoc/comment.rb', line 216

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) 


241
242
243
 
# File 'lib/rdoc/comment.rb', line 241

def tomdoc?
  @format == 'tomdoc'
end