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.
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.
Code objects allow arbitrary custom attributes to be set using the {#[]=} assignment method.
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
namespace | -> | parent |
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. |
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) |
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
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
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).
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.
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
@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.
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"
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})