Home Classes Methods

In Files

rdoc/generator/markup.rb
rdoc/method_attr.rb

Parent

RDoc::CodeObject

Included Modules

Comparable

Class/Module Index

RDoc::MethodAttr

Abstract class representing either a method or an attribute.

Attributes

add_line_numbers[RW]

Allows controlling whether #markup_code adds line numbers to the source code.

aliases[R]

Array of other names for this method/attribute

arglists[R]

The #call_seq or the #param_seq with method name, if there is no call_seq.

block_params[R]

Parameters yielded by the called block

call_seq[RW]

Different ways to call this method

is_alias_for[RW]

The method/attribute we’re aliasing

name[RW]

Name of this method/attribute.

param_seq[R]

Pretty parameter list for this method

params[RW]

Parameters for this method

singleton[RW]

Is this a singleton method/attribute?

text[R]

Source file token stream

visibility[RW]

public, protected, private

Public Class Methods

new(text, name) click to toggle source

Creates a new MethodAttr from token stream text and method or attribute name name.

Usually this is called by super from a subclass.

 
               # File rdoc/method_attr.rb, line 77
def initialize text, name
  super()

  @text = text
  @name = name

  @aliases      = []
  @is_alias_for = nil
  @parent_name  = nil
  @singleton    = nil
  @visibility   = :public
  @see = false

  @arglists     = nil
  @block_params = nil
  @call_seq     = nil
  @param_seq    = nil
  @params       = nil
end

Public Instance Methods

<=>(other) click to toggle source

Order by singleton then name

 
               # File rdoc/method_attr.rb, line 100
def <=>(other)
  [     @singleton ? 0 : 1,       name] <=>
  [other.singleton ? 0 : 1, other.name]
end

add_alias(an_alias, context) click to toggle source

Abstract method. Contexts in their building phase call this to register a new alias for this known method/attribute.

creates a new AnyMethod/Attribute named an_alias.new_name;
adds self as an alias for the new method or attribute
adds the method or attribute to aliases
adds the method or attribute to context.

 
               # File rdoc/method_attr.rb, line 193
def add_alias(an_alias, context)
  raise NotImplementedError
end

add_line_numbers(src) click to toggle source

Prepend src with line numbers. Relies on the first line of a source code listing having:

# File xxxxx, line dddd

If it has this comment then line numbers are added to src and the , line dddd portion of the comment is removed.

 
               # File rdoc/generator/markup.rb, line 86
def add_line_numbers(src)
  return unless src.sub!(/\A(.*)(, line (\d+))/, '\1')
  first = $3.to_i - 1
  last  = first + src.count("\n")
  size = last.to_s.length

  line = first
  src.gsub!(/^/) do
    res = if line == first then
            " " * (size + 1)
          else
            "<span class=\"line-num\">%2$*1$d</span> " % [size, line]
          end

    line += 1
    res
  end
end

aref() click to toggle source

HTML fragment reference for this method

 
               # File rdoc/method_attr.rb, line 200
def aref
  type = singleton ? 'c' : 'i'
  # % characters are not allowed in html names => dash instead
  "#{aref_prefix}-#{type}-#{html_name}"
end

aref_prefix() click to toggle source

Prefix for aref, defined by subclasses.

 
               # File rdoc/method_attr.rb, line 209
def aref_prefix
  raise NotImplementedError
end

block_params=(value) click to toggle source

Attempts to sanitize the content passed by the ruby parser: remove outer parentheses, etc.

 
               # File rdoc/method_attr.rb, line 217
def block_params=(value)
  # 'yield.to_s' or 'assert yield, msg'
  return @block_params = '' if value =~ /^[\.,]/

  # remove trailing 'if/unless ...'
  return @block_params = '' if value =~ /^(if|unless)\s/

  value = $1.strip if value =~ /^(.+)\s(if|unless)\s/

  # outer parentheses
  value = $1 if value =~ /^\s*\((.*)\)\s*$/
  value = value.strip

  # proc/lambda
  return @block_params = $1 if value =~ /^(proc|lambda)(\s*\{|\sdo)/

  # surrounding +...+ or [...]
  value = $1.strip if value =~ /^\+(.*)\+$/
  value = $1.strip if value =~ /^\[(.*)\]$/

  return @block_params = '' if value.empty?

  # global variable
  return @block_params = 'str' if value =~ /^\$[&0-9]$/

  # wipe out array/hash indices
  value.gsub!(/(\w)\[[^\[]+\]/, '\1')

  # remove @ from class/instance variables
  value.gsub!(/@@?([a-z0-9_]+)/, '\1')

  # method calls => method name
  value.gsub!(/([A-Z:a-z0-9_]+)\.([a-z0-9_]+)(\s*\(\s*[a-z0-9_.,\s]*\s*\)\s*)?/) do
    case $2
    when 'to_s'      then $1
    when 'const_get' then 'const'
    when 'new' then
      $1.split('::').last.  # ClassName => class_name
        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
        gsub(/([a-z\d])([A-Z])/,'\1_\2').
        downcase
    else
      $2
    end
  end

  # class prefixes
  value.gsub!(/[A-Za-z0-9_:]+::/, '')

  # simple expressions
  value = $1 if value =~ /^([a-z0-9_]+)\s*[-*+\/]/

  @block_params = value.strip
end

documented?() click to toggle source

A method/attribute is documented if any of the following is true:

it was marked with :nodoc:;
it has a comment;
it is an alias for a documented method;
it has a #see method that is documented.

 
               # File rdoc/method_attr.rb, line 116
def documented?
  super or
    (is_alias_for and is_alias_for.documented?) or
    (see and see.documented?)
end

full_name() click to toggle source

Full method/attribute name including namespace

 
               # File rdoc/method_attr.rb, line 284
def full_name
  @full_name ||= "#{parent_name}#{pretty_name}"
end

html_name() click to toggle source

HTML id-friendly method/attribute name

 
               # File rdoc/method_attr.rb, line 275
def html_name
  require 'cgi'

  CGI.escape(@name.gsub('-', '-2D')).gsub('%','-').sub(/^-/, '')
end

markup_code() click to toggle source

Turns the method’s token stream into HTML.

Prepends line numbers if add_line_numbers is true.

 
               # File rdoc/generator/markup.rb, line 110
def markup_code
  return '' unless @token_stream

  src = RDoc::TokenStream.to_html @token_stream

  # dedent the source
  indent = src.length
  lines = src.lines.to_a
  lines.shift if src =~ /\A.*#\ *File/ # remove '# File' comment
  lines.each do |line|
    if line =~ /^ *(?=\S)/
      n = $&.length
      indent = n if n < indent
      break if n == 0
    end
  end
  src.gsub!(/^#{' ' * indent}/, '') if indent > 0

  add_line_numbers(src) if RDoc::MethodAttr.add_line_numbers

  src
end

name_prefix() click to toggle source

‘::’ for a class method/attribute, ‘#’ for an instance method.

 
               # File rdoc/method_attr.rb, line 303
def name_prefix
  @singleton ? '::' : '#'
end

output_name(context) click to toggle source

Name for output to HTML. For class methods the full name with a “.” is used like SomeClass.method_name. For instance methods the class name is used if context does not match the parent.

This is to help prevent people from using: to call class methods.

 
               # File rdoc/method_attr.rb, line 314
def output_name context
  return "#{name_prefix}#{@name}" if context == parent

  "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
end

parent_name() click to toggle source

Name of our parent with special handling for un-marshaled methods

 
               # File rdoc/method_attr.rb, line 344
def parent_name
  @parent_name || super
end

path() click to toggle source

Path to this method for use with HTML generator output.

 
               # File rdoc/method_attr.rb, line 337
def path
  "#{@parent.path}##{aref}"
end

pretty_name() click to toggle source

Method/attribute name with class/instance indicator

 
               # File rdoc/method_attr.rb, line 323
def pretty_name
  "#{name_prefix}#{@name}"
end

search_record() click to toggle source

Used by RDoc::Generator::JsonIndex to create a record for the search engine.

 
               # File rdoc/method_attr.rb, line 377
def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    snippet(@comment),
  ]
end

see() click to toggle source

A method/attribute to look at, in particular if this method/attribute has no documentation.

It can be a method/attribute of the superclass or of an included module, including the Kernel module, which is always appended to the included modules.

Returns nil if there is no such method/attribute. The #is_alias_for method/attribute, if any, is not included.

Templates may generate a “see also …” if this method/attribute has documentation, and “see …” if it does not.

 
               # File rdoc/method_attr.rb, line 136
def see
  @see = find_see if @see == false
  @see
end

store=(store) click to toggle source

Sets the store for this class or module and its contained code objects.

 
               # File rdoc/method_attr.rb, line 144
def store= store
  super

  @file = @store.add_file @file.full_name if @file
end

type() click to toggle source

Type of method/attribute (class or instance)

 
               # File rdoc/method_attr.rb, line 330
def type
  singleton ? 'class' : 'instance'
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.