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 Attribute Summary

.add_line_numbers rw

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

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

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

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

Name of this method/attribute.
#params rw

Parameters for this method.
#singleton rw

Is this a singleton method/attribute?
#visibility rw

public, protected, private.
#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.
#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.
#param_seq readonly

Pretty parameter list for this method.
#text readonly

Source file token stream.
#store=(store) writeonly

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

CodeObject - Inherited

#comment	Our comment.
#comment=	Replaces our comment with `comment`, unless it is empty.
#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:.
#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`.
#force_documentation	Force documentation of this CodeObject.
#force_documentation=	Force the documentation of this object unless documentation has been turned off by :enddoc:
#line	Line in `#file` where this CodeObject was defined.
#offset	Offset in `#file` where this CodeObject was defined.
#parent	Our parent CodeObject.
#parent=	Sets the parent CodeObject.
#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.
#viewer	We are the model of the code, but we know that at some point we will be worked on by viewers.
#display?	Should this CodeObject be displayed in output?
#documented?	Does this object have a comment with content or is `#received_nodoc` true?
#file	Which file this code object was defined in.
#ignored?	Has this class been ignored?
#metadata	Hash of arbitrary metadata for this CodeObject.
#received_nodoc	Did we ever receive a `:nodoc:` directive?
#suppressed?	Has this class been suppressed?
#full_name=	Sets the full_name overriding any computed full name.

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).

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.

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

Class Attribute Details

.add_line_numbers (rw)

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

[ GitHub ]

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


attr_accessor :add_line_numbers

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

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


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

#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

#markup_code

Turns the method's token stream into HTML.

Prepends line numbers if .add_line_numbers is true.

[ GitHub ]

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


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 RDoc::MethodAttr.add_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

#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

#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 Attribute Summary

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

Class Attribute Details

.add_line_numbers (rw)

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)

#add_alias(an_alias, context)

#add_line_numbers(src)

#aref

#aref_prefix

#full_name

#html_name

#markup_code

#name_prefix

#output_name(context)

#parent_name

#path

#pretty_name

#search_record

#see

#type

.new(text, name) ⇒ `MethodAttr`

#documented? ⇒ `Boolean` (readonly)