Class: RDoc::MethodAttr

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses: AnyMethod, Attr, GhostMethod, MetaMethod
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `CodeObject`
Instance Chain: self, Comparable, `CodeObject`, `Generator::Markup`, `Text`
Inherits:	RDoc::CodeObject Object RDoc::CodeObject RDoc::MethodAttr
Defined in:	lib/rdoc/method_attr.rb, lib/rdoc/generator/markup.rb

Overview

Abstract class representing either a method or an attribute.

Constant Summary

`Text` - Included

MARKUP_FORMAT, TO_HTML_CHARACTERS

Class Method Summary

.new(text, name) ⇒ MethodAttr constructor

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

`CodeObject` - Inherited

.new	Creates a new `CodeObject` that will document itself and its children.

Instance Attribute Summary

#aliases readonly

Array of other names for this method/attribute.
#arglists readonly

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

Parameters yielded by the called block.
#block_params=(value) rw

Attempts to sanitize the content passed by the Ruby parser: remove outer parentheses, etc.
#call_seq rw

Different ways to call this method.
#documented? ⇒ Boolean readonly

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.
#is_alias_for rw

The method/attribute we’re aliasing.
#name rw

Name of this method/attribute.
#param_seq readonly

Pretty parameter list for this method.
#params rw

Parameters for this method.
#singleton rw

Is this a singleton method/attribute?
#store=(store) writeonly

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

Source file token stream.
#visibility rw

public, protected, private.

`CodeObject` - Inherited

#comment	Our comment.
#comment=	Replaces our comment with `comment`, unless it is empty.
#display?	Should this `CodeObject` be displayed in output?
#document_children	Do we document our children?
#document_children=	Enables or disables documentation of this CodeObject’s children unless it has been turned off by :enddoc:
#document_self	Do we document ourselves?
#document_self=	Enables or disables documentation of this `CodeObject` unless it has been turned off by :enddoc:.
#documented?	Does this object have a comment with content or is `#received_nodoc` true?
#done_documenting	Are we done documenting (ie, did we come across a :enddoc:)?
#done_documenting=	Turns documentation on/off, and turns on/off `#document_self` and `#document_children`.
#file	Which file this code object was defined in.
#force_documentation	Force documentation of this `CodeObject`.
#force_documentation=	Force the documentation of this object unless documentation has been turned off by :enddoc:
#full_name=	Sets the full_name overriding any computed full name.
#ignored?	Has this class been ignored?
#line	Line in `#file` where this `CodeObject` was defined.
#metadata	Hash of arbitrary metadata for this `CodeObject`.
#parent	Our parent `CodeObject`.
#parent=	Sets the parent `CodeObject`.
#received_nodoc	Did we ever receive a `:nodoc:` directive?
#section	The section this `CodeObject` is in.
#section=	Set the section this `CodeObject` is in.
#store	The `Store` for this object.
#store=	Sets the `store` that contains this `CodeObject`.
#suppressed?	Has this class been suppressed?
#viewer	We are the model of the code, but we know that at some point we will be worked on by viewers.

Instance Method Summary

#<=>(other)

Order by #singleton then #name
#add_alias(an_alias, context)

Abstract method.
#add_line_numbers(src)

Prepend src with line numbers.
#aref

HTML fragment reference for this method.
#aref_prefix

Prefix for #aref, defined by subclasses.
#full_name

Full method/attribute name including namespace.
#html_name

HTML id-friendly method/attribute name.
#markup_code

Turns the method’s token stream into HTML.
#name_prefix

‘::’ for a class method/attribute, ‘#’ for an instance method.
#output_name(context)

Name for output to HTML.
#parent_name

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

Path to this method for use with HTML generator output.
#pretty_name

Method/attribute name with class/instance indicator.
#search_record

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

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

Type of method/attribute (class or instance).
#==(other) Internal use only
#find_method_or_attribute(name) Internal use only
#find_see Internal use only
#initialize_copy(other) Internal use only

Resets cached data for the object so it can be rebuilt by accessor methods.
#initialize_visibility Internal use only
#inspect Internal use only
#pretty_print(q) Internal use only
#to_s Internal use only

`CodeObject` - Inherited

#each_parent	Yields each parent of this `CodeObject`.
#file_name	File name where this `CodeObject` was found.
#ignore	Use this to ignore a `CodeObject` and all its children until found again (#record_location is called).
#options	The options instance from the store this `CodeObject` is attached to, or a default options instance if the `CodeObject` is not attached.
#parent_file_name	File name of our parent.
#parent_name	Name of our parent.
#record_location	Records the `TopLevel` (file) where this code object was defined.
#start_doc	Enable capture of documentation unless documentation has been turned off by :enddoc:
#stop_doc	Disable capture of documentation.
#suppress	Use this to suppress a `CodeObject` and all its children until the next file it is seen in or documentation is discovered.
#initialize_visibility	Initializes state for visibility of this `CodeObject` and its children.

`Generator::Markup` - Included

#aref_to	Generates a relative URL from this object’s path to `target_path`
#as_href	Generates a relative URL from `from_path` to this object’s path.
#cvs_url	Build a webcvs URL starting for the given `url` with `full_path` appended as the destination path.
#description	Handy wrapper for marking up this object’s comment.
#formatter	Creates an `Markup::ToHtmlCrossref` formatter.

`Text` - Included

#expand_tabs	Expands tab characters in #text to eight spaces.
#flush_left	Flush #text left based on the shortest line.
#markup	Convert a string in markup format into HTML.
#normalize_comment	Strips hashes, expands tabs then flushes #text to the left.
#parse	Normalizes #text then builds a `Markup::Document` from it.
#snippet	The first `limit` characters of #text as HTML.
#strip_hashes	Strips leading # characters from #text
#strip_newlines	Strips leading and trailing n characters from #text
#strip_stars	Strips /* */ style comments.
#to_html	Converts ampersand, dashes, ellipsis, quotes, copyright and registered trademark symbols in #text to properly encoded characters.
#wrap	Wraps `txt` to `line_len`

Constructor Details

.new(text, name) ⇒ `MethodAttr`

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

Usually this is called by super from a subclass.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 78


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

Instance Attribute Details

#aliases (readonly)

Array of other names for this method/attribute

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 32


attr_reader :aliases

#arglists (readonly)

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 64


attr_reader :arglists

#block_params (rw)

Parameters yielded by the called block

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 49


attr_reader :block_params

#block_params=(value) (rw)

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 233


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

#call_seq (rw)

Different ways to call this method

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 59


attr_accessor :call_seq

#documented? ⇒ `Boolean` (readonly)

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.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 132


def documented?
  super or
    (is_alias_for and is_alias_for.documented?) or
    (see and see.documented?)
end

#is_alias_for (rw)

The method/attribute we’re aliasing

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 37


attr_accessor :is_alias_for

#name (rw)

Name of this method/attribute.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 12


attr_accessor :name

#param_seq (readonly)

Pretty parameter list for this method

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 69


attr_reader :param_seq

#params (rw)

Parameters for this method

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 54


attr_accessor :params

#singleton (rw)

Is this a singleton method/attribute?

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 22


attr_accessor :singleton

#store=(store) (writeonly)

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 160


def store= store
  super

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

#text (readonly)

Source file token stream

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 27


attr_reader :text

#visibility (rw)

public, protected, private

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 17


attr_accessor :visibility

Instance Method Details

#<=>(other)

Order by #singleton then #name

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 113


def <=>(other)
  return unless other.respond_to?(:singleton) &&
                other.respond_to?(:name)

  [     @singleton ? 0 : 1,       name] <=>
  [other.singleton ? 0 : 1, other.name]
end

#==(other)

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 121


def == other # :nodoc:
  equal?(other) or self.class == other.class and full_name == other.full_name
end

#add_alias(an_alias, context)

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.

Raises:

(NotImplementedError)

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 209


def add_alias(an_alias, context)
  raise NotImplementedError
end

#add_line_numbers(src)

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.

[ GitHub ]

# File 'lib/rdoc/generator/markup.rb', line 77


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

HTML fragment reference for this method

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 216


def aref
  type = singleton ? 'c' : 'i'
  # % characters are not allowed in html names => dash instead
  "#{aref_prefix}-#{type}-#{html_name}"
end

#aref_prefix

Prefix for #aref, defined by subclasses.

Raises:

(NotImplementedError)

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 225


def aref_prefix
  raise NotImplementedError
end

#find_method_or_attribute(name)

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 178


def find_method_or_attribute name # :nodoc:
  return nil unless parent.respond_to? :ancestors

  searched = parent.ancestors
  kernel = @store.modules_hash['Kernel']

  searched << kernel if kernel &&
    parent != kernel && !searched.include?(kernel)

  searched.each do |ancestor|
    next if String === ancestor
    next if parent == ancestor

    other = ancestor.find_method_named('#' + name) ||
            ancestor.find_attribute_named(name)

    return other if other
  end

  nil
end

#find_see

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 166


def find_see # :nodoc:
  return nil if singleton || is_alias_for

  # look for the method
  other = find_method_or_attribute name
  return other if other

  # if it is a setter, look for a getter
  return nil unless name =~ /[a-z_]=$/i   # avoid == or ===
  return find_method_or_attribute name[0..-2]
end

#full_name

Full method/attribute name including namespace

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 300


def full_name
  @full_name ||= "#{parent_name}#{pretty_name}"
end

#html_name

HTML id-friendly method/attribute name

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 291


def html_name
  require 'cgi'

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

#initialize_copy(other)

This method is for internal use only.

Resets cached data for the object so it can be rebuilt by accessor methods

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 101


def initialize_copy other # :nodoc:
  @full_name = nil
end

#initialize_visibility

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 105


def initialize_visibility # :nodoc:
  super
  @see = nil
end

#inspect

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 304


def inspect # :nodoc:
  alias_for = @is_alias_for ? " (alias for #{@is_alias_for.name})" : nil
  visibility = self.visibility
  visibility = "forced #{visibility}" if force_documentation
  "#<%s:0x%x %s (%s)%s>" % [
    self.class, object_id,
    full_name,
    visibility,
    alias_for,
  ]
end

#markup_code

Turns the method’s token stream into HTML.

Prepends line numbers if options.line_numbers is true.

[ GitHub ]

# File 'lib/rdoc/generator/markup.rb', line 101


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/i # 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 options.line_numbers

  src
end

#name_prefix

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 319


def name_prefix
  @singleton ? '::' : '#'
end

#output_name(context)

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.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 330


def output_name context
  return "#{name_prefix}#{@name}" if context == parent

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

#parent_name

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 360


def parent_name
  @parent_name || super
end

#path

Path to this method for use with HTML generator output.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 353


def path
  "#{@parent.path}##{aref}"
end

#pretty_name

Method/attribute name with class/instance indicator

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 339


def pretty_name
  "#{name_prefix}#{@name}"
end

#pretty_print(q)

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 364


def pretty_print q # :nodoc:
  alias_for =
    if @is_alias_for.respond_to? :name then
      "alias for #{@is_alias_for.name}"
    elsif Array === @is_alias_for then
      "alias for #{@is_alias_for.last}"
    end

  q.group 2, "[#{self.class.name} #{full_name} #{visibility}", "]" do
    if alias_for then
      q.breakable
      q.text alias_for
    end

    if text then
      q.breakable
      q.text "text:"
      q.breakable
      q.pp @text
    end

    unless comment.empty? then
      q.breakable
      q.text "comment:"
      q.breakable
      q.pp @comment
    end
  end
end

#search_record

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

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 398


def search_record
  [
    @name,
    full_name,
    @name,
    @parent.full_name,
    path,
    params,
    snippet(@comment),
  ]
end

#see

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.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 152


def see
  @see = find_see if @see == false
  @see
end

#to_s

This method is for internal use only.

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 410


def to_s # :nodoc:
  if @is_alias_for
    "#{self.class.name}: #{full_name} -> #{is_alias_for}"
  else
    "#{self.class.name}: #{full_name}"
  end
end

#type

Type of method/attribute (class or instance)

[ GitHub ]

# File 'lib/rdoc/method_attr.rb', line 346


def type
  singleton ? 'class' : 'instance'
end

Class: RDoc::MethodAttr

Overview

Constant Summary

Text - Included

Class Method Summary

CodeObject - Inherited

Instance Attribute Summary

CodeObject - Inherited

Instance Method Summary

CodeObject - Inherited

Generator::Markup - Included

Text - Included

Constructor Details

.new(text, name) ⇒ MethodAttr

Instance Attribute Details

#aliases (readonly)

#arglists (readonly)

#block_params (rw)

#block_params=(value) (rw)

#call_seq (rw)

#documented? ⇒ Boolean (readonly)

#is_alias_for (rw)

#name (rw)

#param_seq (readonly)

#params (rw)

#singleton (rw)

#store=(store) (writeonly)

#text (readonly)

#visibility (rw)

Instance Method Details

#<=>(other)

#==(other)

#add_alias(an_alias, context)

#add_line_numbers(src)

#aref

#aref_prefix

#find_method_or_attribute(name)

#find_see

#full_name

#html_name

#initialize_copy(other)

#initialize_visibility

#inspect

#markup_code

#name_prefix

#output_name(context)

#parent_name

#path

#pretty_name

#pretty_print(q)

#search_record

#see

#to_s

#type

`Text` - Included

`CodeObject` - Inherited

`CodeObject` - Inherited

`CodeObject` - Inherited

`Generator::Markup` - Included

`Text` - Included

.new(text, name) ⇒ `MethodAttr`

#documented? ⇒ `Boolean` (readonly)