yard 0.2.2 → 0.2.3

data/docs/GENERATORS.markdown

@@ -0,0 +1,211 @@
+Generators Architecture
+=======================
+
+Note: This document describes the architecture of the current generators 
+implementation which is likely to undergo large changes in the 0.2.4
+release. Keep this in mind if you plan on extending or implementing
+custom generators.
+      
+Generators are the main component in the output generation process of YARD,
+which is invoked when conventional HTML/text output needs to be generated
+for a set of code objects.
+
+Design Goals
+------------
+
+The general design attempts to be as abstracted from actual content and templates
+as possible. Unlike RDoc which uses one file to describe the entire template,
+YARD splits up the generation of code objects into small components, allowing
+template modification for smaller subsets of a full template without having to
+duplicate the entire template itself. This is necessary because of YARD's support
+for plugins. YARD is designed for extensibility by external plugins, and because
+of this, no one plugin can be responsible for the entire template because no
+one plugin knows about the other plugins being used. For instance, if an RSpec
+plugin was added to support and document specifications in class templates,
+this information would need to be transparently added to the template to work
+in conjunction with any other plugin that performed similar template modifications.
+The design goals can be summarized as follows:
+
+  1. Output should be able to be generated for any arbitrary format with little
+     modification to YARD's source code. The addition of extra templates should
+     be sufficient.
+  2. The output generated for an object should independently generated data
+     from arbitrary sources. These independent components are called "sections".
+  3. Sections should be able to be inserted into any object without affecting
+     any existing sections in the document. This allows for easy modification
+     of templates by plugins.
+     
+Generators
+----------
+
+Generator classes are the objects used to orchestrate the design goals listed 
+above. Specifically, they organize the sections and render the template contents
+depending on the format. The main method used to initiate output is the 
+{YARD::Generators::Base#generate #generate} method which takes a list of
+objects to generate output for. A good example of this is the FullDocGenerator,
+which generates conventional HTML documentation:
+
+    # all_objects is an array of module and class objects
+    Generators::FullDocGenerator.new(options).generate(all_objects)
+
+Generator Options
+-----------------
+
+A generator keeps state when it is generating output. This state is kept in
+an options hash which is initially passed to it during instantiation. Some
+default options set the template style (`:template`), the output format (`:format`),
+and the serializer to use (`:serializer`). For example, initializing the 
+{YARD::Generators::QuickDocGenerator} to output as text instead of HTML can be
+done as follows:
+
+    YARD::Generators::QuickDocGenerator.new(:format => :text).generate(objects)
+    
+Serializer
+----------
+
+This class abstracts the logic involved in deciding how to serialize data to
+the expected endpoint. For instance, there is both a {YARD::Serializers::StdoutSerializer StdoutSerializer}
+and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class for
+outputting to console or to a file respectively. When endpoints with locations
+are used (like files or URLs), the serializer implements the {YARD::Serializers::Base#serialized_path #serialized_path}
+method. This allows the translation from a code object to its path at the endpoint,
+which enables inter-document linking.
+
+Generated objects are automatically serialized using the object if present, 
+otherwise the generated object is returned as a string to its parent. Nested
+generator objects automatically set the serializer to nil so that they return
+as a String to their parent.
+
+Templates
+---------
+
+Templates for a generator are by default found inside the one of the template 
+root paths (there can be multiple template paths). A standard template 
+directory looks like the following tree:
+
+    (Assuming templates/ is a template root path)
+    templates/
+    |-- default
+    |   |-- attributes
+    |   |   |-- html
+    |   |   |   `-- header.erb
+    |   |   `-- text
+    |   |       `-- header.erb
+    |   |-- class
+    |   |   `-- html
+    |   |       `-- header.erb
+    |   |-- constants
+    |   |   `-- html
+    |   |       |-- constants.erb
+    |   |       |-- header.erb
+    |   |       |-- included.erb
+    |   |       `-- inherited.erb
+    ...
+
+The path `default` refers to the template style and the directories at the next
+level (such as `attributes`) refer to templates for a generator. The next directory
+refers to the output format being used defined by the `:format` generator option. 
+As we saw in the above example, the format option can be set to `:text`, which
+would use the `text/` directory instead of `html/`. Finally, the individual .erb 
+files are the sections that make up the generator. 
+
+Sections
+--------
+
+As mentioned above, sections are smaller components that correlate to template
+fragments. Practically speaking, a section can either be a template fragment 
+(a conventional .erb file or other supported templating language), a method 
+(which returns a String) or another Generator object (which in turn has its own 
+list of sections).
+
+Creating a Generator
+--------------------
+
+To create a generator, subclass {YARD::Generators::Base} and implement the
+`#sections_for(object)` method. This method should return a list of sections where
+a Symbol refers to a method or template name and a class refers to a generator.
+
+    def sections_for(object)
+      case object
+      when MethodObject
+        [:main, [G(AnotherGenerator)], :footer]
+      else
+        []
+      end
+    end
+    
+A few points about the above example:
+
+  * The method can return different lists depending on the object.
+  * The list of objects is not flat, we will see how nested lists can be used
+    in a future example.
+  * The convenience method `G()` instantiates a generator out of the class using
+    the existing options.
+
+If a section is a Symbol, the generator first checks if a method is defined
+with that name, otherwise it checks in the template directories. If a method
+by the symbol name is defined, you need to manually call {YARD::Generators::Base#render #render}
+to return the contents of the template.
+
+Nested Sections
+---------------
+
+Sections often require the ability to encapsulate a set of sub-sections in markup
+(HTML, for instance). Rather than use heavier Generator subclass objects, a more
+lightweight solution is to nest a set of sub-sections as a list that follows
+a section, for example:
+
+    def sections_for(object) 
+      [:header, [:section_a, :section_b]]
+    end
+    
+The above example nests `section_a` and `section_b` within the `header` section.
+Practically speaking, these sections can be placed in the result by `yield`ing
+to them. A sample header.erb template might contain:
+
+    <h2>Header</h2>
+    <div id="contents">
+      <%= yield %>
+    </div>
+    
+This template code would place the output of `section_a` and `section_b` within
+the above div element. Using yield, we can also change the object that is being
+generated. For example, we may want to yield the first method of the class.
+We can do this like so:
+
+    <h2>First method</h2>
+    <%= yield(current_object.meths.first) %>
+
+This would run the nested sections for the method object instead of the class.
+
+Before Filters
+--------------
+
+Generators can run before filters using the {YARD::Generators::Base.before_section before_section} method
+for all or a specific section to test if the section should be generated or 
+skipped. For instance, we can do the following to generate the section :foo only 
+for MethodObjects:
+
+    class MyGenerator < YARD::Generators::Base
+      before_section :foo, :is_method?
+      
+      def sections_for(object)
+        [:foo, :bar, :baz]
+      end
+      
+      private
+      
+      def is_method?(object)
+        object.is_a?(MethodObject)
+      end
+    end
+
+Without the argument `:foo`, the before filter would be applied to all sections.
+Note that we must return `false` to skip a section. A return type of nil is not
+enough to skip the section.
+
+There is also a {YARD::Generators::Base.before_list before_list} method to run
+a filter before the entire generator is run. This is useful for doing necessary
+filesystem setup or for generating assets (stylesheets) before generating output 
+for the objects. Note that in this case you will need to serialize your data directly
+using the serializer object (described above).

data/docs/GETTING_STARTED.markdown

@@ -0,0 +1,263 @@
+Getting Started with YARD
+=========================
+
+There are a few ways which YARD can be of use to you or your project. This 
+document will cover the most common ways to use YARD:
+
+* [Documenting Code with YARD](#docing)
+* [Using YARD to Generate Documentation](#using)
+* [Extending YARD](#extending)
+* [Templating YARD](#templating)
+
+<a name="docing"></a>
+Documenting Code with YARD
+==========================
+
+By default, YARD is compatible with the same RDoc syntax most Ruby developers
+are already familiar with. However, one of the biggest advantages of YARD is
+the extended meta-data syntax, commonly known as "tags", that you can use
+to express small bits of information in a structured and formal manner. While
+RDoc syntax expects you to describe your method in a completely free-form
+manner, YARD recommends declaring your parameters, return types, etc. with
+the `@tag` syntax, which makes outputting the documentation more consistent
+and easier to read. Consider the RDoc documentation for a method reverse:
+
+    # Converts the object into textual markup given a specific `format` 
+    # (defaults to `:html`)
+    #
+    # == Parameters:
+    # format::
+    #   A Symbol declaring the format to convert the object to. This 
+    #   can be `:text` or `:html`.
+    #
+    # == Returns:
+    # A string representing the object in a specified
+    #
+    # format.
+    def to_format(format = :html)
+      # reverse the string
+    end
+    
+While this may seem easy enough to read and understand, it's hard for a machine
+to properly pull this data back out of our documentation. Also we've tied our
+markup to our content, and now our documentation becomes hard to maintain if
+we decide later to change our markup style (maybe we don't want the ":" suffix
+on our headers anymore).
+
+In YARD, we would simply define our method as:
+
+    # Converts the object into textual markup given a specific format.
+    #
+    # @param [Symbol] format the format type, `:text` or `:html`
+    # @return [String] the object converted into the expected format.
+    def to_format(format = :html)
+    end
+    
+Using tags we can add semantic metadata to our code without worrying about
+presentation. YARD will handle presentation for us when we decide to generate
+documentation later.
+
+Adding Tags to Documentation
+----------------------------
+
+The tag syntax that YARD uses is the same @tag-style syntax you may have seen 
+if you've ever coded in Java, Python, PHP, Objective-C or a myriad of other 
+languages. The following tag adds an author tag to your class:
+
+    # @author Loren Segal
+    class MyClass
+    end
+
+To allow for large amounts of text, the @tag syntax will recognize any indented
+lines following a tag as part of the tag data. For example:
+
+    # @deprecated Use {#my_new_method} instead of this method because
+    #   it uses a library that is no longer supported in Ruby 1.9.
+    #   The new method accepts the same parameters.
+    def mymethod
+    end
+
+Declaring Types
+---------------
+
+Some tags also have an optional "types" field which let us declare a list of
+types associated with the tag. For instance, a return tag can be declared
+with or without a types field.
+
+    # @return [String, nil] the contents of our object or nil
+    #   if the object has not been filled with data.
+    def validate; end
+    
+    # We don't care about the "type" here:
+    # @return the object
+    def to_obj; end
+    
+The list of types is in the form `[type1, type2, ...]` and is mostly free-form,
+so we can also specify duck-types or constant values. For example:
+
+    # @param [#to_s] argname any object that responds to `#to_s`
+    # @param [true, false] argname only true or false
+    
+Note the the latter example can be replaced by the meta-type "Boolean", and
+numeric types can be replaced by "Number". These meta-types are by convention
+only, but are recommended.
+    
+List types can be specified in the form `CollectionClass<ElementType, ...>`.
+For instance, consider the following Array that holds a set of Strings and
+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:
+
+  * `@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
+
+  * `@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
+        
+Other Extended Syntax
+---------------------
+
+**Reference Tags**
+
+To minimize rewriting of documentation and to ease maintenance, a special
+tag syntax is allowed to reference tags from other objects. Doing this allows
+a tag to be added as meta-data for multiple objects. A full example of this
+syntax is found in the {file:TAGS.markdown#reftags TAGS.markdown} file.
+
+**Inter-Document Links**
+
+YARD supports a special syntax to link to other code objects or files.
+The syntax is `{ObjectName#method OPTIONAL_TITLE}`. This syntax is acceptable
+anywhere in documentation with the exception of the @see tag, which 
+automatically links its data.
+
+<a name="using"></a>
+Using YARD to Generate Documentation
+====================================
+
+Obviously since YARD is a documentation tool, one of its primary goals is
+to generate documentation for a variety of formats, most commonly HTML. The
+`yardoc` tool that is installed with YARD allows you to quickly export code
+documentation to HTML document files. In addition to this, YARD ships with
+two more tools allowing you to quickly view `ri`-style documentation for
+a specific class or method as well as an extra tool to generate UML diagrams
+for your code using [Graphviz][graphviz]. An overview of these tools can
+be found in the {file:README.markdown README} under the Usage section.
+
+<a name="extending"></a>
+Extending YARD
+==============
+
+There are many ways to extend YARD to support non-standard Ruby syntax (DSLs), 
+add new meta-data tags or programmatically access the intermediate metadata
+and documentation from code. An overview of YARD's full architecture can be
+found in the {file:OVERVIEW.markdown} document.
+
+For information on adding support for Ruby DSLs, see the {file:HANDLERS.markdown}
+and {file:PARSER.markdown} architecture documents.
+
+For information on adding extra tags, see {file:TAGS.markdown}.
+
+For information on accessing the data YARD stores about your documentation,
+look at the {file:CODE_OBJECTS.markdown} architecture document.
+
+<a name="templating"></a>
+Templating YARD
+===============
+
+In many cases you may want to change the style of YARD's templates or add extra
+information after extending it. The {file:GENERATORS.markdown} architecture
+document covers the basics of how YARD's templating system works.
+
+[graphviz]:http://www.graphviz.org