Class YARD::CodeObjects::Base
In: lib/yard/code_objects/base.rb
Parent: Object

Base is the superclass of all code objects recognized by YARD. A code object is any entity in the Ruby language (class, method, module). A DSL might subclass Base to create a new custom object representing a new entity type.

Registry Integration

Any created object associated with a namespace is immediately registered with the registry. This allows the Registry to act as an identity map to ensure that no object is represented by more than one Ruby object in memory. A unique {path} is essential for this identity map to work correctly.

Custom Attributes

Code objects allow arbitrary custom attributes to be set using the {#[]=} assignment method.

Namespaces

There is a special type of object called a "namespace". These are subclasses of the {NamespaceObject} and represent Ruby entities that can have objects defined within them. Classically these are modules and classes, though a DSL might create a custom {NamespaceObject} to describe a specific set of objects.

@abstract This class should not be used directly. Instead, create a

  subclass that implements {#path}, {#sep} or {#type}.

@see Registry @see path @see #[]= @see NamespaceObject

Methods

==   ===   []   []=   add_file   copy_to   copyable_attributes   docstring   docstring=   dynamic?   eql?   equal?   file   format   has_tag?   hash   inspect   line   method_missing   name   namespace=   new   new   parent=   path   relative_path   root?   sep   source=   tag   tags   to_ary   to_s   type   visibility=  

External Aliases

namespace -> parent

Attributes

docstring  [R]  The documentation string associated with the object @return [Docstring] the documentation string
dynamic  [RW]  Marks whether or not the method is conditionally defined at runtime @return [Boolean] true if the method is conditionally defined at runtime
files  [R]  The files the object was defined in. To add a file, use {add_file}. @return [Array<String>] a list of files @see add_file
group  [RW]  @return [String] the group this object is associated with @since 0.6.0
namespace  [R]  The namespace the object is defined in. If the object is in the top level namespace, this is {Registry.root} @return [NamespaceObject] the namespace object
signature  [RW]  The one line signature representing an object. For a method, this will be of the form "def meth(arguments…)". This is usually the first source line.

@return [String] a line of source

source  [R]  The source code associated with the object @return [String, nil] source, if present, or nil
source_type  [RW]  Language of the source code associated with the object. Defaults to +:ruby+.

@return [Symbol] the language type

visibility  [RW]  @return [Symbol] the visibility of an object (:public, :private, :protected)

Public Class methods

Compares the class with subclasses

@param [Object] other the other object to compare classes with @return [Boolean] true if other is a subclass of self

Allocates a new code object @return [Base] @see initialize

Creates a new code object

@example Create a method in the root namespace

  CodeObjects::Base.new(:root, '#method') # => #<yardoc method #method>

@example Create class Z inside namespace X::Y

  CodeObjects::Base.new(P("X::Y"), :Z) # or
  CodeObjects::Base.new(Registry.root, "X::Y")

@param [NamespaceObject] namespace the namespace the object belongs in,

  {Registry.root} or :root should be provided if it is associated with
  the top level namespace.

@param [Symbol, String] name the name (or complex path) of the object. @yield [self] a block to perform any extra initialization on the object @yieldparam [Base] self the newly initialized code object @return [Base] the newly created object

Public Instance methods

==(other)

Alias for equal?

Accesses a custom attribute on the object @param [to_s] key the name of the custom attribute @return [Object, nil] the custom attribute or nil if not found. @see #[]=

Sets a custom attribute on the object @param [to_s] key the name of the custom attribute @param [Object] value the value to associate @return [void] @see #[]

Associates a file with a code object, optionally adding the line where it was defined. By convention, ’<stdin>’ should be used to associate code that comes form standard input.

@param [String] file the filename (’<stdin>’ for standard input) @param [Fixnum, nil] line the line number where the object lies in the file @param [Boolean] has_comments whether or not the definition has comments associated. This

  will allow {#file} to return the definition where the comments were made instead
  of any empty definitions that might have been parsed before (module namespaces for instance).

Copies all data in this object to another code object, except for uniquely identifying information (path, namespace, name, scope).

@param [Base] other the object to copy data to @return [Base] the other object @since 0.8.0

Attaches a docstring to a code object by parsing the comments attached to the statement and filling the {tags} and {docstring} methods with the parsed information.

@param [String, Array<String>, Docstring] comments

  the comments attached to the code object to be parsed
  into a docstring and meta tags.

Is the object defined conditionally at runtime? @see dynamic

eql?(other)

Alias for equal?

Tests if another object is equal to this, including a proxy @param [Base, Proxy] other if other is a {Proxy}, tests if

  the paths are equal

@return [Boolean] whether or not the objects are considered the same

Returns the filename the object was first parsed at, taking definitions with docstrings first.

@return [String] a filename

Renders the object using the {Templates::Engine templating system}.

@example Formats a class in plaintext

  puts P('MyClass').format

@example Formats a method in html with rdoc markup

  puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)

@param [Hash] options a set of options to pass to the template @option options [Symbol] :format (:text) :html, :text or another output format @option options [Symbol] :template (:default) a specific template to use @option options [Symbol] :markup (nil) the markup type (:rdoc, :markdown, :textile) @option options [Serializers::Base] :serializer (nil) see Serializers @return [String] the rendered template @see Templates::Engine#render

Tests if the {docstring} has a tag @see Docstring#has_tag?

@return [Integer] the object‘s hash value (for equality checking)

Inspects the object, returning the type and path @return [String] a string describing the object

Returns the line the object was first parsed at (or nil)

@return [Fixnum] the line where the object was first defined. @return [nil] if there is no line associated with the object

@overload dynamic_attr_name

  @return the value of attribute named by the method attribute name
  @raise [NoMethodError] if no method or custom attribute exists by
    the attribute name
  @see #[]

@overload dynamic_attr_name=(value)

  @param value a value to set
  @return +value+
  @see #[]=

The name of the object @param [Boolean] prefix whether to show a prefix. Implement

  this in a subclass to define how the prefix is showed.

@return [Symbol] if prefix is false, the symbolized name @return [String] if prefix is true, prefix + the name as a String.

  This must be implemented by the subclass.

Sets the namespace the object is defined in.

@param [NamespaceObject, :root, nil] obj the new namespace (:root

  for {Registry.root}). If obj is nil, the object is unregistered
  from the Registry.
parent=(obj)

Alias for namespace=

Represents the unique path of the object. The default implementation joins the path of {namespace} with {name} via the value of {sep}. Custom code objects should ensure that the path is unique to the code object by either overriding {sep} or this method.

@example The path of an instance method

  MethodObject.new(P("A::B"), :c).path # => "A::B#c"

@return [String] the unique path of the object @see sep

@param [Base, String] other another code object (or object path) @return [String] the shortest relative path from this object to other @since 0.5.3

@return whether or not this object is a RootObject

Override this method with a custom component separator. For instance, {MethodObject} implements sep as ’#’ or ’.’ (depending on if the method is instance or class respectively). {path} depends on this value to generate the full path in the form: namespace.path + sep + name

@return [String] the component that separates the namespace path

  and the name (default is {NSEP})

Attaches source code to a code object with an optional file location

@param [source, String] statement

  the +Parser::Statement+ holding the source code or the raw source
  as a +String+ for the definition of the code object only (not the block)

Gets a tag from the {docstring} @see Docstring#tag

Gets a list of tags from the {docstring} @see Docstring#tags

@return [nil] this object does not turn into an array

to_s()

Alias for path

Default type is the lowercase class name without the "Object" suffix. Override this method to provide a custom object type

@return [Symbol] the type of code object this represents

Protected Instance methods

Override this method if your code object subclass does not allow copying of certain attributes.

@return [Array<String>] the list of instance variable names (without

  "@" prefix) that should be copied when {#copy_to} is called

@see copy_to @since 0.8.0

[Validate]