class YARD::Handlers::Base

@see #parse_block
@see #register
@see #owner
@see #namespace
@see handles
@see CodeObjects::NamespaceObject
@see CodeObjects::Base
during the processing phase.
@abstract Subclass this class to provide a handler for YARD to use
invoked explicitly out of efficiency sake.
even if statements. For this reason, the block parsing method must be
YARD has the ability to continue into any block: class, module, method,
the namespace now pointing to the class object the handler created.
{#parse_block} method to continue parsing code inside the block, with
the class. For a class handler, the programmer would execute the
would be a list of statements including the method definitions inside
For example, a class statement would be “class MyClass” and the block
statement or classic ‘Ruby block’.
of any statement, be it class definition, module definition, if
block (if there is one). In this context, a block means the inside
handlers may wish to continue parsing the code inside the statement’s
In addition to parsing a statement and creating new objects, some
== Parsing Blocks in Statements
of the current parsing position.
refer to the public/protected/private and class/instance values (respectively)
Mainly needed for parsing methods, the visibility and scope attributes
=== visibility and scope Attributes
second-class Ruby objects (methods).
of as the difference between first-class Ruby objects (namespaces) and
In summary, the distinction between namespace and owner can be thought
to the correct namespace (the class, not the method).
definitions set inside a method (def x; def y; 2 end end) by adding them
set to the class. This would allow the developer to process any method
the owner would be set to the method object but the namespace would remain
handler was added to the mix and decided to parse inside the method body,
To put this into context, the example from above will be used. If a method
so the owner attribute would not be limited to modules and classes.
to parse beyond module and class blocks (inside methods, for instance),
object is loosely defined as a module or class and YARD has the ability
it also follows the scope of the code during parsing. However, a namespace
The owner attribute is similar to the namespace attribute in that
=== owner Attribute
code object.
called on the method, the namespace would be set to the ‘MyClass’
a statement. If the class was then entered and another handler was
This is the value that namespace would return when processing such
be necessary to know that it belonged inside the SomeModule module.
If a handler was to parse the ‘class MyClass’ statement, it would
end
end
def mymethod; end
class MyClass
module SomeModule
which represents the current namespace that the parser is in. For instance:
The namespace attribute is a {CodeObjects::NamespaceObject namespace object}
=== namespace Attribute
regular expressions (or other text processing mechanisms), if needed.
can be converted to a String using #to_s to parse the data with
the data to be processed will live in the tokens attribute. This list
can be accessed by the {Parser::Ruby::Legacy::Statement#comments} method, but generally
of data to be analyzed and processed. The comments attached to the statement
containing a set of tokens parsed in by the parser. This is the main set
The statement attribute pertains to the {Parser::Ruby::Legacy::Statement} object
=== statement Attribute
it.
it is important to know where the data is coming from to be able to use
such there is no real guideline on how to process the data. However,
The goal of a specific handler is really up to the developer, and as
== Processing Handler Data
end
end
# do something
def process
handles TkMODULE
class MyModuleHandler < YARD::Handlers::Base
Here is a simple example which processes module statements.
declaration, taking either a {Parser::Ruby::Legacy::RubyToken}, {String} or ‘Regexp`.
which statement the handler will process. This is done with the handles
base class. The only other thing that needs to be done is to specify
A Handler is automatically registered when it is subclassed from the
== Setting up a Handler for Use
and register a new object or add new attributes to the current namespace.
Handlers are usually simple and take up to a page of code to process
sets some basic attributes for the new objects.
which case they should be registered by {#register}, a method that
{CodeObjects::Base code objects} or the creation of new ones, in
usually involve the manipulation of the {#namespace}, {#owner}
implement the {#process} method to do the work. The processing would
it will handle using the {handles} class declaration. It will then
Generally, a handler class will declare a set of statements which
== Overview of a Typical Handler Scenario
class objects in any outputted documentation.
documentation in a very explicit format by treating them as first-
takes advantage of class level declarations could add these to the
adding a handler for such a keyword. Similarly, any Ruby API that
the ’describe’ declaration of the RSpec testing framework by simply
of this would be the ability to document and generate meta data for
any Ruby DSLs that a customized framework may use. A good example
generated by YARD, giving them the ability to, for instance, document
phase. They allow developers to control what information gets
Handlers are pluggable semantic parsers for YARD’s code generation