RDoc::Comment

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 Other directives at RDoc::Markup for instructions on adding an alternate format.

Attributes

document[W]

Overrides the content returned by parse. Use when there is no text source for this comment

file[RW]

The RDoc::TopLevel this comment was found in

format[R]

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

location[RW]

The RDoc::TopLevel this comment was found in

text[R]

The text for this comment

Public Class Methods

new(text = nil, location = nil) click to toggle source

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

 
               # File rdoc/comment.rb, line 45
def initialize text = nil, location = nil
  @location = location
  @text     = text

  @document   = nil
  @format     = 'rdoc'
  @normalized = false
end

Public Instance Methods

empty?() click to toggle source

A comment is empty if its text String is empty.

 
               # File rdoc/comment.rb, line 131
def empty?
  @text.empty?
end

extract_call_seq(method) click to toggle source

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

 
               # File 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*$/ 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+)/ then
      leading = $2 # ' *    ARGF' in the example above
      re = %r
        \A(
           (^\s*\n)+
           (^#{Regexp.escape leading}.*?\n)+
          )+
        ^\s*$
      %m

      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)/, '\1')
    @text.slice! all_start...all_stop

    method.call_seq = seq.chomp

  elsif @text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/, '') 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) click to toggle source

HACK dubious

 
               # File rdoc/comment.rb, line 138
def force_encoding encoding
  @text.force_encoding encoding
end

format=(format) click to toggle source

Sets the format of this comment and resets any parsed document

 
               # File rdoc/comment.rb, line 145
def format= format
  @format = format
  @document = nil
end

normalize() click to toggle source

Normalizes the text. See RDoc::Text#normalize_comment for details

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

parse() click to toggle source

Parses the comment into an RDoc::Markup::Document. The parsed document is cached until the text is changed.

 
               # File rdoc/comment.rb, line 181
def parse
  return @document if @document

  @document = super @text, @format
  @document.file = @location
  @document
end

remove_private() click to toggle source

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

 
               # File 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?%, empty)
  @text = @text.sub(%r^\s*[#*]?--.*%, '')
end

text=(text) click to toggle source

Replaces this comment’s text with text and resets the parsed document.

An error is raised if the comment contains a document but no text.

 
               # File rdoc/comment.rb, line 216
def text= text
  raise RDoc::Error, 'replacing document-only comment is not allowed' if
    @text.nil? and @document

  @document = nil
  @text = text
end

tomdoc?() click to toggle source

Returns true if this comment is in TomDoc format.

 
               # File rdoc/comment.rb, line 227
def tomdoc?
  @format == 'tomdoc'
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please see Improve the docs, or visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Included Modules

Class/Module Index

RDoc::Comment

Attributes

Public Class Methods

Public Instance Methods