Handlers.md in yard-0.7.0

- old
+ new

@@ -1,28 +1,27 @@
-Handlers Architecture
-=====================
+# @title Handlers Architecture
 
+# Handlers Architecture
+
 Handlers allow the processing of parsed source code. Handling is done after
 parsing to abstract away the implementation details of lexical and semantic
 analysis on source and to only deal with the logic regarding recognizing
 source statements as {file:docs/CodeObjects.md code objects}.
 
 ![Handlers Architecture Class Diagram](images/handlers-class-diagram.png)
 
-The Pipeline
-------------
+## The Pipeline
 
 After the {file:docs/Parser.md parser component} finishes analyzing the
 source, it is handed off for post-processing to the {YARD::Handlers::Processor}
 class, which is responsible for traversing the set of statements given by
 the parser and delegating them to matching handlers. Handlers match when the
 {YARD::Handlers::Base.handles?} method returns true for a given statement.
 The handler can then perform any action after being invoked by the `process`
 method.
 
-The Processor Class
--------------------
+## The Processor Class
 
 The main purpose of the processor, as mentioned above, is to traverse through
 the list of statements given to it by the parser. The processor also keeps
 state about what is being processed. For instance, the processor is what keeps
 track of the current namespace (the module or class an object is being defined
@@ -30,12 +29,11 @@
 that is most directly responsible for the source statement being processed. This
 is most often the same as the namespace, except when parsing the body of a method, 
 where the namespace would be the class/module the method is defined in and the 
 owner would be the method object itself.
 
-Implementing a Handler
-======================
+## Implementing a Handler
 
 This section covers the basics of implementing a *new-style* Ruby handler. For
 details on implementing a legacy handler, see the "API Differences" section below.
 
 a Ruby handler can be implemented simply by subclassing the {YARD::Handlers::Ruby::Base}
@@ -58,12 +56,11 @@
 a handler that handles class definitions should handle the `:class` and `:sclass`
 node types respectively (the latter refers to classes defined as `class << Something`).
 The {YARD::Handlers::Base#statement statement} attribute refers to the current
 node (or statement) that is being handled by the handler.
 
-Handling a Method Call
-----------------------
+### Handling a Method Call
 
 In some cases, a developer might need to handle a method call. The parser can
 express a method call in many AST forms, so to simplify this process, a method
 call can be handled by declaring the following in a `handles` statement:
 
@@ -83,23 +80,21 @@
     describe(something) { perform_a_block }
     describe "Something" do
       a_block
     end
     
-Creating a new Code Object
---------------------------
+### Creating a new Code Object
 
 Usually (but not always) handling is performed to create new code objects to add
 to the registry (for information about code objects, see {file:docs/CodeObjects.md this document}).
 Code objects should simply be created and added to the existing `namespace`. This
 will be enough to add them to the registry. There is also a convenience 
 {YARD::Handlers::Base#register register} method which quickly sets standard attributed
 on the newly created object, such as the file, line, source and docstring of the
 object. This method will be seen in the next example.
     
-Handling an Inner Block
------------------------
+### Handling an Inner Block
 
 By default, the parser gives the processor class a list of all the top level
 statements and the processor parses only those top level statements. If an inner
 block of a module, class, method declaration or even a block passed to a method call
 needs to be handled, the {YARD::Handlers::Base#parse_block parse_block} method must be called on the list of statements
@@ -123,11 +118,10 @@
 In this case `statement[1]` refers to a list of extra statements, the block we
 wish to parse. Note here that when parsing objects like modules and classes,
 we set the namespace for the duration of the block parsing by setting options
 on the `parse_block` method.
 
-API Differences for Legacy Handler
-----------------------------------
+### API Differences for Legacy Handler
 
 Because the legacy handler uses the legacy parser and therefore a different kind
 of AST, there are subtle differences in the handler API. Most importantly, the
 `handles` method usually deals with either lexical tokens or source code as a string
 or RegExp object. The statement object, similarly, is made up of lexical tokens instead