yard 0.6.8 → 0.7.0

data/docs/Glossary.md

@@ -1,5 +1,4 @@
-Glossary
-========
+# Glossary
 
 * **Code Object**: Any explicitly defined Ruby source that describes a feature
   of the code. By default, this refers to classes, modules, methods, constants

data/docs/Handlers.md

@@ -1,5 +1,6 @@
-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
@@ -8,8 +9,7 @@ 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}
@@ -19,8 +19,7 @@ the parser and delegating them to matching handlers. Handlers match when the
 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
@@ -32,8 +31,7 @@ is most often the same as the namespace, except when parsing the body of a metho
 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.
@@ -60,8 +58,7 @@ node types respectively (the latter refers to classes defined as `class << Somet
 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
@@ -85,8 +82,7 @@ the following syntaxes:
       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}).
@@ -96,8 +92,7 @@ will be enough to add them to the registry. There is also a convenience
 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
@@ -125,8 +120,7 @@ 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

data/docs/Overview.md

@@ -1,5 +1,6 @@
-Architecture Overview
-=====================
+# @title Architecture Overview
+
+# Architecture Overview
 
 YARD is separated in three major components, each of which allows YARD to be
 extended for a separate purpose. The split also emphasizes YARD's design choice
@@ -23,17 +24,17 @@ following class diagram:
 ![Overview Class Diagram](images/overview-class-diagram.png)
 
 <a name="parsing"></a>
-Code Parsing & Processing Component
------------------------------------
+
+## Code Parsing & Processing Component
 
 This component is made up of four sub-components, each of which have separate
 tasks during the data gathering process (*note: the tag architecture is not*
 *shown in the class diagram*). These sub-components are:
 
-  * {file:docs/Parser.md Parser Architecture}
-  * {file:docs/Handlers.md Handler Architecture}
-  * {file:docs/CodeObjects.md Code Object Architecture}
-  * {file:docs/Tags.md Tag Architecture}
+  * {file:docs/Parser.md}
+  * {file:docs/Handlers.md}
+  * {file:docs/CodeObjects.md}
+  * {file:docs/Tags.md}
 
 The parser component reads source files and converts it into a set of statements
 which the handlers then process, creating code objects which in turn create tags 
@@ -41,8 +42,8 @@ which the handlers then process, creating code objects which in turn create tags
 the data store component.
 
 <a name="storage"></a>
-Data Storage Component
-----------------------
+
+## Data Storage Component
 
 This component is currently implemented as a simple Ruby marshalled flat namespace
 of object. The implementation is found in the single class {YARD::Registry}, which
@@ -51,10 +52,10 @@ are future plans to improve this storage mechanism to be backend agnostic and al
 for more robust storage.
 
 <a name="templates"></a>
-Post Processing & Templating System
------------------------------------
+
+## Post Processing & Templating System
 
 This component handles processing of objects from the registry through a templating
 engine that allows output to a variety of formats. Practically speaking, this is
 where templates can be implemented to change the design, output or structure of
-the data. See {file:docs/Templates.md Templates Architecture} for a complete overview.
+the data. See {file:docs/Templates.md Templates Architecture} for a complete overview.

data/docs/Parser.md

@@ -1,5 +1,6 @@
-Parser Architecture
-===================
+# @title Parser Architecture
+
+# Parser Architecture
 
 The parser component of YARD is the first component in the data processing pipeline
 that runs before any handling is done on the source. The parser is meant to translate
@@ -13,8 +14,7 @@ system below:
 
 (Note: the RubyToken classes are omitted from the diagram)
 
-SourceParser
-------------
+## SourceParser
 
 The main class {YARD::Parser::SourceParser} acts as a factory class, instantiating
 the correct parser class, an implementation of {YARD::Parser::Base}. The selected parser
@@ -28,8 +28,7 @@ the individual parser classes since it initiates the pipeline that runs the
 handlers on the parsed source. The parser used must also match the handlers,
 and this is coordinated by the `SourceParser` class as well.
 
-Using the SourceParser Class
-----------------------------
+## Using the SourceParser Class
 
 The `SourceParser` class API is optimized for parsing globs of files. As such,
 the main method to use the class is the `parse` class method, which takes an
@@ -56,8 +55,7 @@ You can also provide the parser type explicitly as the second argument:
 Note that these two methods are aliased as {YARD.parse} and {YARD.parse_string} for 
 convenience.
     
-Implementing and Registering a Custom Parser
---------------------------------------------
+## Implementing and Registering a Custom Parser
 
 To implement a custom parser, subclass {YARD::Parser::Base}. Documentation on which
 abstract methods should be implemented are documented in that class. After the class
@@ -72,8 +70,7 @@ The last argument can be a single extension, a list of extensions (Array), a sin
 list of Regexps. Do not include the '.' in the extension.
 
 
-The Two Ruby Parser Types
--------------------------
+## The Two Ruby Parser Types
 
 When parsing Ruby, the SourceParser can either instantiate the new {YARD::Parser::Ruby::RubyParser}
 class or the {YARD::Parser::Ruby::Legacy::StatementList} class. The first of the 
@@ -83,8 +80,7 @@ compatibility is required. The choice of parser will affect which handlers
 ultimately get used, since new handlers can only use the new parser and the 
 same requirement applies to the legacy parser & handlers.
 
-Switching to Legacy Parser
---------------------------
+## Switching to Legacy Parser
 
 By default, running YARD under Ruby 1.9 will automatically select the new parser
 and new handlers by extension. Although YARD supports both handler styles, plugins
@@ -98,8 +94,7 @@ The default value is `:ruby`. Note that this cannot be forced the other way arou
 a parser type of `:ruby` cannot be set under Ruby 1.8.x as the new parser is not
 supported under 1.8.
 
-RubyParser (the New Parser)
-===========================
+## RubyParser (the New Parser)
 
 The new Ruby parser uses the Ripper library that is packaged as part of stdlib
 in Ruby 1.9. Because of this, it can generate an AST from a string of Ruby input
@@ -107,8 +102,7 @@ that is similar to the style of other sexp libraries (such as ParseTree). Each
 node generated in the tree is of the base type {YARD::Parser::Ruby::AstNode},
 which has some subclasses for common node types.
 
-AstNode Basics
---------------
+### AstNode Basics
 
 The `AstNode` class behaves like a standard Array class in which all of its data
 make up the list of elements in the array. Unlike other sexp style libraries, however,
@@ -131,8 +125,7 @@ the sexp declared above, we can do:
 
     node.children #=> [s(:int, "1"), s(:var_ref, s(:ident, "hello"))]
 
-AstNode#source and #line
-------------------------
+### AstNode#source and #line
 
 Every node defines the `#source` method which returns the source code that the 
 node represents. One of the most common things to do with a node is to grab its 
@@ -157,8 +150,7 @@ We can also get the line and line ranges in a similar fashion:
     ast[0].line       #=> 1
     ast[0].line_range #=> 1..3 (note the newlines in the source)
 
-AstNode#jump
-------------
+### AstNode#jump
 
 Often the AST will be such that the node we care about might be buried arbitrarily
 deep in a node's hierarchy. The {YARD::Parser::Ruby::AstNode#jump} method exists
@@ -171,8 +163,7 @@ to quickly get at a node of a specific type in such a situation:
 Multiple types can be searched for at once. If none are found, the original root
 node is returned so that it may be chained.
 
-The Legacy Parser
-=================
+## The Legacy Parser
 
 The goal of the legacy parser is much the same as the new parser, but it is far
 more simplistic. Instead of a full-blown AST, the legacy parser simply groups

data/docs/Tags.md

@@ -1,5 +1,6 @@
-Tags Overview
-=============
+# @title Tags Overview
+
+# Tags Overview
 
 Tags represent the metadata that can be added to documentation through the `@tag`
 style syntax:
@@ -15,8 +16,7 @@ way to access it later without having to parse the entire comment string. The
 rest of the document will describe the tag syntax, how to access the tag 
 metadata and how to extend YARD to support custom tags or override existing tags.
 
-Tag Syntax
-----------
+## Tag Syntax
 
 Tags begin with "@tagname" at the start of a comment line. Tags can span multiple
 lines if the subsequent lines are indented by more than one space. The following
@@ -87,8 +87,8 @@ As mentioned, types are optional, so the following is also valid:
 
 
 <a name="taglist"></a>
-List of Available Tags
-----------------------
+
+## List of Available Tags
 
 YARD supplies the following built-in tags:
 
@@ -122,6 +122,12 @@ YARD supplies the following built-in tags:
   
         @attr_writer [Types] name description of writeonly attribute
 
+  * `@attribute`: Recognizes a DSL class method as an attribute with the given
+    name. Also accepts the r, w, or rw flag to signify that the attribute is 
+    readonly, writeonly, or readwrite (default). Only used with DSL methods.
+
+        @attribute [rw|r|w] NAME
+
   * `@author`: List the author(s) of a class/method
 
         @author Full Name
@@ -137,6 +143,17 @@ YARD supplies the following built-in tags:
         @example Reverse a string
           "mystring".reverse #=> "gnirtsym"
           
+  * `@macro`: Registers or expands a new macro. See the [Macros](#macros)
+    section for more details. Note that the name parameter is never optional.
+    
+        @macro [new|attached] macro_name
+          The macro contents to expand
+          
+  * `@method`: Recognizes a DSL class method as a method with the given name
+    and optional signature. Only used with DSL methods.
+      
+        @method method_signature(opts = {}, &block)
+  
   * `@note`: Creates an emphasized note for the users to read about the
     object.
     
@@ -191,6 +208,11 @@ YARD supplies the following built-in tags:
   * `@return`: Describes return value of method
 
         @return [optional, types, ...] description
+  
+  * `@scope`: Sets the scope of a DSL method. Only applicable to DSL method
+    calls. Acceptable values are 'class' or 'instance'
+    
+        @scope class|instance
       
   * `@see`: "See Also" references for an object. Accepts URLs or
     other code objects with an optional description at the end.
@@ -213,6 +235,11 @@ YARD supplies the following built-in tags:
 
         @version 1.0
 
+  * `@visibility`: Sets the visibility of a DSL method. Only applicable to
+    DSL method calls. Acceptable values are public, protected, or private.
+    
+        @visibility public|protected|private
+
   * `@yield`: Describes the block. Use types to list the parameter
     names the block yields.
 
@@ -229,8 +256,8 @@ YARD supplies the following built-in tags:
 
 
 <a name="reftags"></a>
-Reference Tags
---------------
+
+## Reference Tags
 
 Although attempt is made in YARD to leave as many of the syntax details as
 possible to the factory provider, there is a special tag syntax for referencing
@@ -268,11 +295,179 @@ method only references one of the tags by adding `username` before the reference
 Reference tags are represented by the {YARD::Tags::RefTag} class and are created
 directly during parsing by {YARD::Docstring}.
 
-Programmatic API
-================
+<a name="macros"></a>
+
+## Macros
+
+Macros enable the documenter to write repetitive documentation once and then
+re-apply it to other objects. Macros are defined on docstrings using the
+`@macro` tag. The same `@macro` tag is used to expand them. The following
+is an example of a simple macro declaration and expansion:
+
+    # @macro [new] string_attr
+    # @return [String] the attribute +$1+ as a String
+    attr_accessor :foo
+    
+    # @macro string_attr
+    attr_accessor :bar
+    
+In the above example, both attributes `foo` and `bar` will get the docstring
+that includes a return tag "the attribute as a String". It would be equivalent
+to writing the following:
+
+    # @return [String] the attribute +foo+ as a String
+    attr_accessor :foo
+
+    # @return [String] the attribute +bar+ as a String
+    attr_accessor :bar
+
+### Creating a Macro
+
+If the macro does not already exist, it will be created if:
+
+  1. there are interpolation variables (`$1`, `$2`, `${3-5}`, etc.) in the
+     docstring, or,
+  2. the macro is specified with the `[new]` or `[attached]` flag.
+
+For instance, creating a new macro might look like (see the section on
+interpolation below for a description of the `$2` syntax):
+
+    # @macro the_macro_name
+    # @return [$2] the thing to return
+    typed_attribute :foo, String
+
+Or:
+
+    # @macro [new] the_macro_name
+    # Returns a string!
+    def foo; end
+    
+You can also "attach" a macro to a method if it is in the class scope. In
+this case, you do not need to also provide the 'new' flag, using 'attach'
+is sufficient:
+
+    # @macro [attach] the_macro_name
+    #   @return [String] the string value
+    def self.foo; end
+
+Any time 'foo' is called in the class scope of an inheriting class, the macro
+will automatically expand on that method call (potentially creating a new
+method object). Attaching macros is discussed below.
+
+Note that the name is never optional. Even if the macro is never re-used,
+it must be named.
+    
+### Indenting the Macro Data
+
+If a macro tag has an indented body of macro data (shown below), it will be
+the only portion of the docstring saved for re-use.
+
+    # @macro [new] macro_name
+    #   The macro data is here.
+    # This data is only used for the current object
+    def method; end
+    
+In the above case, "The macro data is here." is the only portion that will be
+re-used if the macro is called again on another object. However, for the case
+of the above method, both the macro data and the local docstring will be
+applied to the method, creating the docstring:
+
+    # The macro data is here.
+    # This data is only used for the current object.
+    def method; end
+    
+You can therefore keep portions of docstrings local to objects even when
+creating a macro, by indenting the portion of the data that should be re-
+expanded, and listing the local docstring data above or below.
+
+If there is no indented macro data, the entire docstring is saved as the
+macro data. For instance,
+
+    # @macro [new] macro_name
+    # The macro data is here.
+    # This data is also used for all macros.
+    def method; end
+    
+In the above case, the macro 'macro_name' will always show both lines of text
+when expanded on other objects.
+
+### Attaching a Macro to a DSL (Class) Method
+
+Macros can be created on class level methods (or class level method calls) in 
+order to implicitly expand a macro whenever that method is subsequently called 
+in a class, or any class that mixes in or inherits the method. These macros
+are called "attached" and are declared with the `[attach]` flag. For instance, 
+a library that uses a class level method call `property` in its codebase can 
+document these declarations in any future call like so:
+
+    class Resource
+      # Defines a new property
+      # @param [String] name the property name
+      # @param [Class] type the property's type
+      # @macro [attach] property
+      #   @return [$2] the $1 property
+      def self.property(name, type) end
+    end
+    
+    class Post < Resource
+      property :title, String
+      property :view_count, Integer
+    end
+
+If you cannot declare the macro on the actual method declaration, you can
+arbitrarily attach the macro to any method call. Suppose we only had the
+Post class in our codebase, we could add the macro to the first usage of
+the `property` call:
+
+    class Post < Resource
+      # @macro [attach] property
+      # @return [$2] the $1 property
+      property :title, String
+      property :view_count, Integer
+    end
+
+### Macro Variable Interpolation Syntax
+
+The interpolation syntax is similar to Ruby's regular expression variable syntax.
+It uses $1, $2, $3, ..., referring to the Nth argument in the method call. Using
+the above property example, $1 would be 'title', and $2 would be 'String'.
+$0 is a special variable that refers to the method call itself, in this case
+'property'. Finally, there is a $& variable which refers to the full line,
+or 'property :title, String'.
+
+#### Ranges
+
+Ranges are also acceptable with the syntax `${N-M}`. Negative values on either
+N or M are valid, and refer to indexes from the end of the list. Consider
+a DSL method that creates a method using the first argument with argument
+names following, ending with the return type of the method. This could be
+documented as:
+
+    # @macro dsl_method
+    # @method $1(${2--2})
+    # @return [${-1}] the return value of $0
+    create_method_with_args :foo, :a, :b, :c, String
+
+As described, the method is using the signature `foo(a, b, c)` and the return
+type from the last argument, `String`. When using ranges, tokens are joined
+with commas. Note that this includes using $0:
+
+    $0-1 # => Interpolates to "create_method_with_args, foo"
+
+If you want to separate them with spaces, use `$1 $2 $3 $4 ...`. Note that
+if the token cannot be expanded, it will return the empty string (not an error),
+so it would be safe to list `$1 $2 ... $10`, for example.
+
+#### Escaping Interpolation
+
+Interpolation can be escaped by prefixing the `$` with `\`, like so: 
+
+    # @macro foo
+    #   I have \$2.00 USD.
+
+## Programmatic API
 
-Accessing Tag Information
--------------------------
+### Accessing Tag Information
 
 Tag metadata is added when a {YARD::Docstring} is added to a {file:docs/CodeObjects.md code object}
 using the {YARD::CodeObjects::Base#docstring=} attribute. In addition to adding
@@ -288,8 +483,7 @@ of tags. The `#tag` method is an alias for the first item in the list of tags.
 Also note that the `#tag`, `#tags` and `#has_tag?` methods are all convenience
 methods that delegate to the {YARD::Docstring} object described above.
 
-Adding Custom Tags
-------------------
+### Adding Custom Tags
 
 The `@tagname` tag used in the above examples is clearly not part of the tags
 that come with YARD. If such a tag would actually be part of documentation under
@@ -304,8 +498,7 @@ tag that stores simple text like our `@tagname` tag above, use:
 
 This will now allow YARD to add the metadata from `@tagname` to the docstring.
 
-Tag Factory Architecture
-------------------------
+## Tag Factory Architecture
 
 Recognizing a tag is one part of the process. Parsing the tag contents is the
 second step. YARD has a tag architecture that allows developers to add or completely