Class: RDoc::Comment

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

Overview

frozen_string_literal: false

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.



46
47
48
49
50
51
52
53
 
# File 'lib/rdoc/comment.rb', line 46

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



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

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

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:



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

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) 


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

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



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
 
# File 'lib/rdoc/comment.rb', line 84

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



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

def force_encoding encoding
  @text.force_encoding encoding
end

#initialize_copy(copy) ⇒ Object

– TODO deep copy @document



59
60
61
 
# File 'lib/rdoc/comment.rb', line 59

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

#inspect ⇒ Object

:nodoc:



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

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



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

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) 


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

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.



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

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



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

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) 


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

def tomdoc?
  @format == 'tomdoc'
end