yard 0.5.5 → 0.5.6

data/ChangeLog

@@ -1,5 +1,85 @@
+2010-06-12  Loren Segal <lsegal@soen.ca>
+
+  * ChangeLog, README.md, docs/WhatsNew.md, lib/yard.rb, yard.gemspec: Release
+  0.5.6
+
+  * lib/rubygems_plugin.rb: Don't generate yri index if has_rdoc == false
+
+  * lib/yard/handlers/ruby/class_condition_handler.rb,
+  spec/handlers/class_condition_handler_spec.rb: Fix failing class condition
+  handling case in 1.9
+
+  * lib/rubygems_plugin.rb, lib/yard/cli/yardoc.rb,
+  lib/yard/code_objects/base.rb, lib/yard/code_objects/class_object.rb,
+  lib/yard/code_objects/constant_object.rb,
+  lib/yard/code_objects/method_object.rb,
+  lib/yard/code_objects/namespace_object.rb, lib/yard/code_objects/proxy.rb,
+  lib/yard/docstring.rb, lib/yard/handlers/base.rb,
+  lib/yard/parser/ruby/ast_node.rb, lib/yard/parser/ruby/ruby_parser.rb,
+  lib/yard/serializers/file_system_serializer.rb,
+  lib/yard/tags/default_factory.rb, lib/yard/tags/library.rb,
+  lib/yard/templates/template.rb, templates/default/tags/html/option.erb: Fix a
+  boatload of Ruby warnings
+
+  * lib/rubygems_plugin.rb: Fix warnings in RubyGems plugin  Closes gh-108
+
+  * spec/cli/yardoc_spec.rb: Fix Yardoc CLI specs for new read_binary encoding
+  fixes
+
+  * lib/yard/autoload.rb, lib/yard/parser/base.rb, lib/yard/parser/c_parser.rb,
+  lib/yard/parser/ruby/legacy/ruby_parser.rb,
+  lib/yard/parser/ruby/legacy/statement_list.rb,
+  lib/yard/parser/ruby/ruby_parser.rb, lib/yard/parser/source_parser.rb,
+  spec/parser/base_spec.rb, spec/parser/source_parser_spec.rb: Refactor
+  SourceParser and create API to extend YARD with custom source parsers using
+  YARD::Parser::SourceParser.register_parser_type  Closes gh-101
+
+2010-06-11  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/parser/source_parser.rb: Add .cc as C source filename extension
+
+  * .../ruby/legacy/class_condition_handler.rb,
+  spec/handlers/class_condition_handler_spec.rb: Fixes handling of class
+  conditionals in the form "defined?(A) && defined?(B)"
+
+2010-06-05  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/cli/yardoc.rb, lib/yard/templates/erb_cache.rb,
+  lib/yard/templates/helpers/html_helper.rb,
+  templates/default/layout/html/setup.rb: Various encoding related template
+  fixes.  Closes gh-131
+
+2010-05-26  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/cli/yri.rb: Don't use less on Windows (non-cygwin)
+
+  * lib/yard/cli/yri.rb: yri should fail gracefully when no arguments are
+  supplied
+
+  * Rakefile: Better rake support for windows
+
+  * lib/yard/parser/ruby/ruby_parser.rb, spec/parser/source_parser_spec.rb: Fix
+  handling of docstrings in 1.9 parser when there are comments before and on
+  the same line of a code object
+
+  * README.md, docs/GettingStarted.md, docs/Tags.md: Move tag list from
+  GettingStarted to Tags and document syntax
+
+  * README.md: Update README formatting
+
+2010-05-25  Loren Segal <lsegal@soen.ca>
+
+  * lib/yard/autoload.rb, lib/yard/handlers/ruby/class_handler.rb,
+  lib/yard/handlers/ruby/legacy/class_handler.rb,
+  lib/yard/handlers/ruby/struct_handler_methods.rb: Various documentation and
+  style refactorings
+
 2010-05-22  Loren Segal <lsegal@soen.ca>
 
+  * README.md: Fix release date/version in readme
+
+  * README.md: Fix contributors formatting in readme for github
+
   * ChangeLog, README.md, lib/yard.rb, yard.gemspec: Bump version to 0.5.5
 
 2010-05-21  Loren Segal <lsegal@soen.ca>
@@ -53,6 +133,11 @@
   lib/yard/code_objects/proxy.rb, spec/code_objects/class_object_spec.rb: Fixes
   an issue where mixins could appear twice in the class hierarchy
 
+2010-05-18  Michael Edgar <michael.j.edgar@dartmouth.edu>
+
+  * lib/yard/handlers/ruby/struct_handler_methods.rb: Made struct handler
+  directly add tags. Technical faux pas.
+
 2010-05-15  postmodern <postmodern.mod3@gmail.com>
 
   * lib/yard.rb: Only glob .rb files from yard/core_ext and do not strip the
@@ -71,6 +156,52 @@
   spec/parser/ruby/legacy/statement_list_spec.rb: Fill .block for 'else' and
   'elsif' statements in legacy parser.
 
+2010-05-09  Michael Edgar <michael.j.edgar@dartmouth.edu>
+
+  * lib/yard/handlers/ruby/legacy/class_handler.rb,
+  spec/handlers/class_handler_spec.rb,
+  spec/handlers/examples/class_handler_001.rb.txt: Added more specs for
+  attr_reader and attr_writer combinations.
+
+  * lib/yard/handlers/ruby/struct_handler_methods.rb,
+  spec/handlers/class_handler_spec.rb,
+  spec/handlers/examples/class_handler_001.rb.txt: Added some specs for the use
+  of attr_reader and attr_writer. Made them pass.
+
+  * lib/yard/handlers/ruby/struct_handler_methods.rb, lib/yard/tags/library.rb:
+  Added basic logic for the separation of reader/writer attributes. Specs pass,
+  but no new specs have been added.
+
+  * lib/yard/handlers/ruby/class_handler.rb,
+  lib/yard/handlers/ruby/legacy/class_handler.rb: Added support on the handler
+  side for defining constants for non-anonymous structs
+
+  * spec/handlers/class_handler_spec.rb: Added a spec to ensure that when a
+  non-anonymous struct is used, the appropriate constant is defined in
+  Struct::.
+
+  * lib/yard/handlers/ruby/class_handler.rb,
+  lib/yard/handlers/ruby/legacy/class_handler.rb: Added Ruby 1.8.x
+  compatibility, and fixed an error caused by OStruct.new (without parens).
+
+  * lib/yard/handlers/ruby/struct_handler_methods.rb, lib/yard/tags/library.rb,
+  spec/handlers/class_handler_spec.rb,
+  spec/handlers/examples/class_handler_001.rb.txt: Specifications added for the
+  @attr tag.
+
+  * lib/yard/handlers/ruby/class_handler.rb: Added basic support for
+  subclass-syntax with Structs. The newly-added specs pass.
+
+  * lib/yard/autoload.rb, lib/yard/handlers/ruby/struct_handler_methods.rb:
+  Added my struct_handler_methods.rb file from yard-struct, which will provide
+  shortcuts for adding attributes. This is a module (and not dropped into the
+  ClassHandler) because I want to reuse this code for the Constant-assignment
+  syntax as well.
+
+  * spec/handlers/class_handler_spec.rb,
+  spec/handlers/examples/class_handler_001.rb.txt: Added specs for the
+  superclass syntax for Struct usage.
+
 2010-05-04  Denis Defreyne <denis.defreyne@stoneship.org>
 
   * templates/default/docstring/html/private.erb,

data/README.md

@@ -1,17 +1,18 @@
-YARD Release 0.5.4 "The Longest" (Mar 22nd 2010)
-================================================
+YARD: Yay! A Ruby Documentation Tool
+====================================
 
 **Homepage**:     [http://yardoc.org](http://yardoc.org)   
-**IRC**:          **Join us on IRC in #yard on irc.freenode.net!**   
+**IRC**:          [irc://irc.freenode.net/yard](irc.freenode.net / #yard)    
 **Git**:          [http://github.com/lsegal/yard](http://github.com/lsegal/yard)   
 **Author**:       Loren Segal  
 **Contributors**: Nathan Weizenbaum, Yehuda Katz, Denis Defreyne, Postmodern, 
-                  Michael Edgar    
+Michael Edgar    
 **Copyright**:    2007-2010    
 **License**:      MIT License    
+**Latest Version**: 0.5.6 (codename "The Longest")    
+**Release Date**: May 22nd 2010    
 
-
-SYNOPSIS
+Synopsis
 --------
 
 YARD is a documentation generation tool for the Ruby programming language.

@@ -21,7 +22,7 @@ custom Ruby constructs such as custom class level definitions. Below is a
 summary of some of YARD's notable features.
 
 
-FEATURE LIST
+Feature List
 ------------
                                                                               
 **1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible

@@ -37,7 +38,7 @@ important information about objects, such as what parameters they take and what
 they are expected to be, what type a
method should return, what exceptions it can 
 raise, if it is deprecated, etc.. It also allows information to be better (and more 
 consistently) organized
during the output generation phase. You can find a list
-of tags in the {file:GettingStarted.md#taglist GettingStarted.md} file.
+of tags in the {file:Tags.md#taglist Tags.md} file.
 
 YARD also supports an optional "types" declarations for certain tags.

 This allows the developer to document type signatures for ruby methods and

@@ -46,7 +47,6 @@ describing this data in the body of the description, a developer may formally
 declare the parameter or return type(s) in a single line. Consider the

 following Yardoc'd method:

 
-     ## 
      # Reverses the contents of a String or IO object. 
      # 
      # @param [String, #read] contents the contents to reverse 
@@ -97,7 +97,7 @@ exploiting this raw data format would be to write tools that can auto generate
 test cases, for example, or show possible unhandled exceptions in code.

                                                                               
 
-USAGE
+Usage
 -----
 
 There are a couple of ways to use YARD. The first is via command-line, and the
@@ -221,9 +221,13 @@ More options can be seen by typing `yard-graph --help`, but here is an example:
     $ yard-graph --protected --full --dependencies
 
 
-CHANGELOG
+Changelog
 ---------
 
+- **June.12.10**: 0.5.6 release
+    - Bug fixes for RubyGems plugin, `has_rdoc=false` should now work
+    - New API for registering custom parsers. See {file:WhatsNew.md}
+
 - **May.22.10**: 0.5.5 release
     - Various bug fixes
 
@@ -293,7 +297,7 @@ CHANGELOG
   power of YARD and what to expect from the syntax (Yardoc style meta tags).    
                                                           
 
-COPYRIGHT
+Copyright
 ---------
 
 YARD © 2007-2010 by [Loren Segal](mailto:lsegal@soen.ca). YARD is 

data/Rakefile

@@ -1,6 +1,7 @@
 require File.dirname(__FILE__) + '/lib/yard'
+require 'rbconfig'
 
-WINDOWS = (RUBY_PLATFORM =~ /win32|cygwin/ ? true : false) rescue false
+WINDOWS = (Config::CONFIG['host_os'] =~ /mingw|win32|cygwin/ ? true : false) rescue false
 SUDO = WINDOWS ? '' : 'sudo'
 
 task :default => :specs

data/docs/GettingStarted.md

@@ -110,116 +110,10 @@ Symbols:
   
     # @param [Array<String, Symbol>] list the list of strings and symbols.
 
-<a name="taglist"></a>
 List of Tags
 ------------
     
-A list of common tags and example usage is below:
-
-  * `@abstract`: Marks a class/module/method as abstract with optional
-    implementor information.
-    
-        @abstract Subclass and override {#run} to implement a custom Threadable class.
-
-  * `@author`: List the author(s) of a class/method
-
-        @author Full Name
-
-  * `@deprecated`: Marks a method/class as deprecated with an optional
-    reason.
-
-        @deprecated Describe the reason or provide alt. references here
-
-  * `@example`: Show an example snippet of code for an object. The
-    first line is an optional title.
-
-        @example Reverse a string
-          "mystring.reverse" #=> "gnirtsym"
-
-  * `@option`: Describe an options hash in a method. The tag takes the
-    name of the options parameter first, followed by optional types,
-    the option key name, an optional default value for the key and a 
-    description of the option.
-
-        # @param [Hash] opts the options to create a message with.
-        # @option opts [String] :subject The subject
-        # @option opts [String] :from ('nobody') From address
-        # @option opts [String] :to Recipient email
-        # @option opts [String] :body ('') The email's body 
-        def send_email(opts = {})
-        end 
-
-  * `@overload`: Describe that your method can be used in various
-    contexts with various parameters or return types. The first
-    line should declare the new method signature, and the following
-    indented tag data will be a new documentation string with its
-    own tags adding metadata for such an overload.
-
-        # @overload set(key, value)
-        #   Sets a value on key
-        #   @param [Symbol] key describe key param
-        #   @param [Object] value describe value param
-        # @overload set(value)
-        #   Sets a value on the default key `:foo`
-        #   @param [Object] value describe value param
-        def set(*args)
-        end
-        
-  * `@param`: Defines method parameters
-
-        @param [optional, types, ...] argname description
-        
-  * `@private`: Defines an object as private. This exists for classes,
-    modules and constants that do not obey Ruby's visibility rules. For
-    instance, an inner class might be considered "private", though Ruby
-    would make no such distinction. By declaring the @private tag, the
-    class can be hidden from documentation by using the `--no-private`
-    command-line switch to yardoc (see {file:README.md}).
-    
-        @private
-
-  * `@raise`: Describes an Exception that a method may throw
-
-        @raise [ExceptionClass] description
-
-  * `@return`: Describes return value of method
-  
-        @return [optional, types, ...] description
-        
-  * `@see`: "See Also" references for an object. Accepts URLs or
-    other code objects with an optional description at the end.
-  
-        @see http://example.com Description of URL
-        @see SomeOtherClass#method
-        
-  * `@since`: Lists the version the feature/object was first added
-  
-        @since 1.2.4
-        
-  * `@todo`: Marks a TODO note in the object being documented
-
-        @todo Add support for Jabberwocky service
-          There is an open source Jabberwocky library available 
-          at http://somesite.com that can be integrated easily
-          into the project.
-
-  * `@version`: Lists the version of a class, module or method
-  
-        @version 1.0
-
-  * `@yield`: Describes the block. Use types to list the parameter
-    names the block yields.
-
-        # for block {|a, b, c| ... }
-        @yield [a, b, c] Description of block
-
-  * `@yieldparam`: Defines parameters yielded by a block
-
-        @yieldparam [optional, types, ...] argname description
-
-  * `@yieldreturn`: Defines return type of a block
-
-        @yieldreturn [optional, types, ...] description
+A list of tags can be found in {file:Tags.md#taglist}
         
 Other Extended Syntax
 ---------------------

data/docs/Tags.md

@@ -1,5 +1,5 @@
-Tags Architecture
-=================
+Tags Overview
+=============
 
 Tags represent the metadata that can be added to documentation through the `@tag`
 style syntax:
@@ -12,9 +12,249 @@ The above example adds metadata under the name `tagname` to the Foo class object
 
 Tags are the best way to add arbitrary metadata when documenting an object in a
 way to access it later without having to parse the entire comment string. The
-rest of the document will describe how to access the tag metadata and how to extend
-YARD to support custom tags or override existing tags to the {YARD::Tags::Library}
-class.
+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
+----------
+
+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
+syntax is valid:
+
+    # @tagname This is 
+    #   tag data
+    # but this is not
+    
+In the above example, "@tagname" will have the text *"This is tag data"*.
+
+If a tag's data begins with `(see NAME)` it is considered a "reference tag".
+The syntax and semantics of a reference tag are discussed in the section below
+titled "[Reference Tags](#reftags)"
+
+Although custom tags can be parsed in any way, the built-in tags follow a few 
+common syntax structures by convention in order to simplify the syntax. The 
+following syntaxes are available:
+
+### Freeform Data
+
+This syntax has no special syntax, it is simply a tagname followed by any
+data.
+
+    @tagname data here
+    
+### Freeform Data With Title
+
+Occasionally a freeform tag may reserve the first line for a title (or some
+other associative identifier) and treat only the subsequent indented lines as
+the tag data. Two examples are the `@example` and `@overload` tags. In the case
+of `@example` the first line is a title, and in the case of `@overload` the
+first line is the method signature for the overload. Here is an example of both:
+
+    @example Reverse a string
+      "hello world".reverse
+      
+    @overload request(method = :get, url = 'http://example.com')
+      Performs a request on +url+
+      @param [Symbol] method the request method
+      @param [String] url the URL to perform the request on
+      @return [String] the result body (no headers)
+
+### Data With Optional Type Information
+
+This syntax optionally contains type information to be associated with the
+tag. Type information is specified as a freeform list of Ruby types, duck
+types or literal values. The following is a valid tag with type information:
+
+    @return [String, #read] a string or object that responds to #read
+    
+### Data With Name and Optional Type Information
+
+A special case of the above data with optional type information is the case
+of tags like `@param`, where the data is further associated with a key. In
+the case of `@param` the key is an argument name in the method. The following
+shows how this can be used:
+
+    @param [String] url the URL to perform the request on
+
+Note that "url" in the above example is the key name. The syntax is of the form:
+
+    @tagname [types] <name> <description>
+    
+As mentioned, types are optional, so the following is also valid:
+
+    @param url the URL to perform the request on
+
+
+<a name="taglist"></a>
+List of Available Tags
+----------------------
+
+YARD supplies the following built-in tags:
+
+  * `@abstract`: Marks a class/module/method as abstract with optional
+    implementor information.
+  
+        @abstract Subclass and override {#run} to implement a custom Threadable class.
+      
+  * `@attr`: Declares an attribute from the docstring of a class. Meant to be
+    used on Struct classes (classes that inherit Struct).
+  
+        @attr [Types] attribute_name a full description of the attribute
+      
+  * `@attr_reader`: Declares a readonly attribute from the docstring of a class.
+    Meant to be used on Struct classes (classes that inherit Struct). See `@attr`.
+  
+        @attr_reader [Types] name description of a readonly attribute
+      
+  * `@attr_writer`: Declares a writeonly attribute from the docstring of class.
+    Meant to be used on Struct classes (classes that inherit Struct). See `@attr`.
+  
+        @attr_writer [Types] name description of writeonly attribute
+
+  * `@author`: List the author(s) of a class/method
+
+        @author Full Name
+
+  * `@deprecated`: Marks a method/class as deprecated with an optional
+    reason.
+
+        @deprecated Describe the reason or provide alt. references here
+
+  * `@example`: Show an example snippet of code for an object. The
+    first line is an optional title.
+
+        @example Reverse a string
+          "mystring.reverse" #=> "gnirtsym"
+
+  * `@option`: Describe an options hash in a method. The tag takes the
+    name of the options parameter first, followed by optional types,
+    the option key name, an optional default value for the key and a 
+    description of the option.
+
+        # @param [Hash] opts the options to create a message with.
+        # @option opts [String] :subject The subject
+        # @option opts [String] :from ('nobody') From address
+        # @option opts [String] :to Recipient email
+        # @option opts [String] :body ('') The email's body 
+        def send_email(opts = {})
+        end 
+
+  * `@overload`: Describe that your method can be used in various
+    contexts with various parameters or return types. The first
+    line should declare the new method signature, and the following
+    indented tag data will be a new documentation string with its
+    own tags adding metadata for such an overload.
+
+        # @overload set(key, value)
+        #   Sets a value on key
+        #   @param [Symbol] key describe key param
+        #   @param [Object] value describe value param
+        # @overload set(value)
+        #   Sets a value on the default key `:foo`
+        #   @param [Object] value describe value param
+        def set(*args)
+        end
+      
+  * `@param`: Defines method parameters
+
+        @param [optional, types, ...] argname description
+      
+  * `@private`: Defines an object as private. This exists for classes,
+    modules and constants that do not obey Ruby's visibility rules. For
+    instance, an inner class might be considered "private", though Ruby
+    would make no such distinction. By declaring the @private tag, the
+    class can be hidden from documentation by using the `--no-private`
+    command-line switch to yardoc (see {file:README.md}).
+  
+        @private
+
+  * `@raise`: Describes an Exception that a method may throw
+
+        @raise [ExceptionClass] description
+
+  * `@return`: Describes return value of method
+
+        @return [optional, types, ...] description
+      
+  * `@see`: "See Also" references for an object. Accepts URLs or
+    other code objects with an optional description at the end.
+
+        @see http://example.com Description of URL
+        @see SomeOtherClass#method
+      
+  * `@since`: Lists the version the feature/object was first added
+
+        @since 1.2.4
+      
+  * `@todo`: Marks a TODO note in the object being documented
+
+        @todo Add support for Jabberwocky service
+          There is an open source Jabberwocky library available 
+          at http://somesite.com that can be integrated easily
+          into the project.
+
+  * `@version`: Lists the version of a class, module or method
+
+        @version 1.0
+
+  * `@yield`: Describes the block. Use types to list the parameter
+    names the block yields.
+
+        # for block {|a, b, c| ... }
+        @yield [a, b, c] Description of block
+
+  * `@yieldparam`: Defines parameters yielded by a block
+
+        @yieldparam [optional, types, ...] argname description
+
+  * `@yieldreturn`: Defines return type of a block
+
+        @yieldreturn [optional, types, ...] description
+
+
+<a name="reftags"></a>
+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
+tags created in other objects so that they can be reused again. This is common
+when an object describes a return type or parameters that are passed through to
+other methods. In such a case, it is more manageable to use the reference tag
+syntax. Consider the following example:
+
+    class User
+      # @param [String] username the nam of the user to add
+      # @param [Number] uid the user ID
+      # @param [Number] gid the group ID
+      def initialize(username, uid, gid)
+      end
+    end
+
+    module UserHelper
+      # @param (see User#initialize)
+      def add_user(username, uid, gid)
+        User.new(username, uid, gid)
+      end
+
+      # @param username (see User#initialize)
+      def add_root_user(username)
+        User.new(username, 0, 0)
+      end
+    end
+
+Because the UserHelper module methods delegate directly to `User.new`, copying
+the documentation details would be unmaintainable. In this case, the (see METHODNAME)
+syntax is used to reference the tags from the User constructor to the helper methods.
+For the first method, all `@param` tags are referenced in one shot, but the second
+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
+================
 
 Accessing Tag Information
 -------------------------
@@ -49,8 +289,8 @@ 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.
 
-The 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
@@ -61,8 +301,7 @@ class diagram:
 
 ![Tags Architecture Class Diagram](images/tags-class-diagram.png)
 
-DefaultFactory
---------------
+### DefaultFactory
 
 By default, YARD has a few standard syntaxes that can be parsed for tags. These
 are all implemented by the {YARD::Tags::DefaultFactory} class. These syntaxes
@@ -102,8 +341,7 @@ the type declaration syntax to be in the form:
 This can be done by simply implementing a new factory that parses the data in
 this form.
 
-Implementing a Factory
-----------------------
+### Implementing a Factory
 
 Factories should implement the method `parse_tag` as well as any `parse_tag_SUFFIX`
 method where SUFFIX refers to the suffix added when declaring the tag. For example,
@@ -131,51 +369,10 @@ unmodified raw text:
 Note that this method would be invoked for a tag declared with the `:with_raw_text`
 suffix.
 
-Changing the Factory
---------------------
+### Changing the Factory
 
 To change the factory, set the {YARD::Tags::Library.default_factory} attribute:
 
     YARD::Tags::Library.default_factory = MyFactory
 
 This must be done before any parsing is done, or the factory will not be used.
-
-<a name="reftags"></a>
-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
-tags created in other objects so that they can be reused again. This is common
-when an object describes a return type or parameters that are passed through to
-other methods. In such a case, it is more manageable to use the reference tag
-syntax. Consider the following example:
-
-    class User
-      # @param [String] username the nam of the user to add
-      # @param [Number] uid the user ID
-      # @param [Number] gid the group ID
-      def initialize(username, uid, gid)
-      end
-    end
-
-    module UserHelper
-      # @param (see User#initialize)
-      def add_user(username, uid, gid)
-        User.new(username, uid, gid)
-      end
-      
-      # @param username (see User#initialize)
-      def add_root_user(username)
-        User.new(username, 0, 0)
-      end
-    end
-    
-Because the UserHelper module methods delegate directly to `User.new`, copying
-the documentation details would be unmaintainable. In this case, the (see METHODNAME)
-syntax is used to reference the tags from the User constructor to the helper methods.
-For the first method, all `@param` tags are referenced in one shot, but the second
-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}.