yard 0.9.18 → 0.9.19

data/docs/TagsArch.md

@@ -1,123 +1,123 @@
-# @title Tags Architecture
-
-# Tags Architecture
-
-## Programmatic API
-
-### 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
-conventional comments, tags are parsed and associated with the object. The easiest
-way to access tags on an object is to use the {YARD::CodeObjects::Base#tag} and `#tags`
-methods, for example:
-
-    # Using the Foo class object from above
-    obj.tags(:tagname).first.text #=> "some data"
-
-Because multiple tags can be stored with the same name, they are stored as a list
-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
-
-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
-a default install, YARD would raise a warning that the tag does not exist. It is,
-however, trivial to add this tag to be recognized by YARD.
-
-All tags in YARD are added to the {YARD::Tags::Library tag library} which makes
-use of a tag factory class to parse the data inside the tags. To simply add a
-tag that stores simple text like our `@tagname` tag above, use:
-
-    YARD::Tags::Library.define_tag("A Sample Tag", :tagname)
-
-This will now allow YARD to add the metadata from `@tagname` to the docstring.
-
-## 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
-change the way tags contents can be parsed.
-
-The separation of registration and tag creation can be seen in the following
-class diagram:
-
-![Tags Architecture Class Diagram](images/tags-class-diagram.png)
-
-### 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
-are:
-
-  * Standard text: no parsing is done, but text is stripped of newlines and
-    multiple spaces.
-
-  * Raw text: does no parsing at all, no stripping of newlines or spaces. This
-    is best used for code snippets.
-
-  * Raw text with title: does no parsing on the text but extracts the first line
-    of the metadata as the "title", useful for tags such as `@example`:
-
-        # @example Inspect an element
-        #   myobj.inspect #=> #<Object:0x123525>
-
-  * Text with types: parses a list of types at the beginning of the text. Types
-    are optional. The standard syntax is in the form `[type1, type2, ...]`,
-    for example:
-
-        # @return [String, Symbol] a description here
-        # @return description here with no types
-
-  * Text with types and a name: parses a list of types at the beginning of text
-    followed by a name and extra descriptive text. For example:
-
-        # @param [String] str the string to reverse
-        def reverse(str) '...' end
-
-As mentioned above, this syntax is implemented by the `DefaultFactory` which can
-be swapped out for any factory. In some cases, a developer may want to change
-the type declaration syntax to be in the form:
-
-    # @tagname name <Types, here> description
-
-This can be done by simply implementing a new factory that parses the data in
-this form.
-
-### 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,
-a tag can also be declared as follows:
-
-    YARD::Tags::Library.define_tag "Parameter", :param, :with_types
-
-In such a case, the factory will be called with method `parse_tag_with_types`. In
-all cases, the method should return a new {YARD::Tags::Tag} object. Generally,
-the `parse_tag` methods take 2 or 3 parameters. A simple tag can be implemented
-as:
-
-    def parse_tag(tag_name, text)
-      Tag.new(tag_name, text)
-    end
-
-The text parameter contains pre-parsed text with extra spaces and newlines removed.
-If required, the method could also be declared with a third parameter containing
-unmodified raw text:
-
-    def parse_tag_with_raw_text(tag_name, text, raw_text)
-      Tag.new(tag_name, raw_text)
-    end
-
-Note that this method would be invoked for a tag declared with the `:with_raw_text`
-suffix.
-
-### 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.
+# @title Tags Architecture
+
+# Tags Architecture
+
+## Programmatic API
+
+### 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
+conventional comments, tags are parsed and associated with the object. The easiest
+way to access tags on an object is to use the {YARD::CodeObjects::Base#tag} and `#tags`
+methods, for example:
+
+    # Using the Foo class object from above
+    obj.tags(:tagname).first.text #=> "some data"
+
+Because multiple tags can be stored with the same name, they are stored as a list
+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
+
+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
+a default install, YARD would raise a warning that the tag does not exist. It is,
+however, trivial to add this tag to be recognized by YARD.
+
+All tags in YARD are added to the {YARD::Tags::Library tag library} which makes
+use of a tag factory class to parse the data inside the tags. To simply add a
+tag that stores simple text like our `@tagname` tag above, use:
+
+    YARD::Tags::Library.define_tag("A Sample Tag", :tagname)
+
+This will now allow YARD to add the metadata from `@tagname` to the docstring.
+
+## 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
+change the way tags contents can be parsed.
+
+The separation of registration and tag creation can be seen in the following
+class diagram:
+
+![Tags Architecture Class Diagram](images/tags-class-diagram.png)
+
+### 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
+are:
+
+  * Standard text: no parsing is done, but text is stripped of newlines and
+    multiple spaces.
+
+  * Raw text: does no parsing at all, no stripping of newlines or spaces. This
+    is best used for code snippets.
+
+  * Raw text with title: does no parsing on the text but extracts the first line
+    of the metadata as the "title", useful for tags such as `@example`:
+
+        # @example Inspect an element
+        #   myobj.inspect #=> #<Object:0x123525>
+
+  * Text with types: parses a list of types at the beginning of the text. Types
+    are optional. The standard syntax is in the form `[type1, type2, ...]`,
+    for example:
+
+        # @return [String, Symbol] a description here
+        # @return description here with no types
+
+  * Text with types and a name: parses a list of types at the beginning of text
+    followed by a name and extra descriptive text. For example:
+
+        # @param [String] str the string to reverse
+        def reverse(str) '...' end
+
+As mentioned above, this syntax is implemented by the `DefaultFactory` which can
+be swapped out for any factory. In some cases, a developer may want to change
+the type declaration syntax to be in the form:
+
+    # @tagname name <Types, here> description
+
+This can be done by simply implementing a new factory that parses the data in
+this form.
+
+### 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,
+a tag can also be declared as follows:
+
+    YARD::Tags::Library.define_tag "Parameter", :param, :with_types
+
+In such a case, the factory will be called with method `parse_tag_with_types`. In
+all cases, the method should return a new {YARD::Tags::Tag} object. Generally,
+the `parse_tag` methods take 2 or 3 parameters. A simple tag can be implemented
+as:
+
+    def parse_tag(tag_name, text)
+      Tag.new(tag_name, text)
+    end
+
+The text parameter contains pre-parsed text with extra spaces and newlines removed.
+If required, the method could also be declared with a third parameter containing
+unmodified raw text:
+
+    def parse_tag_with_raw_text(tag_name, text, raw_text)
+      Tag.new(tag_name, raw_text)
+    end
+
+Note that this method would be invoked for a tag declared with the `:with_raw_text`
+suffix.
+
+### 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.

data/docs/Templates.md

@@ -1,496 +1,496 @@
-# @title Templates Architecture
-
-# Templates Architecture
-
-Templates are the main component in the output rendering process of YARD,
-which is invoked when conventional HTML/text output needs to be rendered
-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 rendering 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 rendered for any arbitrary format with little
-     modification to YARD's source code. The addition of extra templates should
-     be sufficient.
-  2. The output rendered for an object should independently rendered 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.
-
-## Templates
-
-Template modules 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.
-
-## Engine
-
-The Engine class orchestrates the creation and rendering of Template modules and
-handles serialization or specific rendering scenarios (like HTML). To create
-a template, use the {YARD::Templates::Engine.template template} method. The two most
-common methods used to initiate output are the {YARD::Templates::Engine.render render}
-and {YARD::Templates::Engine.generate generate} methods which generate and
-optionally serialize output to a file. The latter, `#generate`, is used
-specially to generate HTML documentation and copy over assets that may be
-needed. For instance, an object may be rendered with:
-
-    YARD::Templates::Engine.render(:object => myobject)
-
-A set of objects may be rendered into HTML documentation by using:
-
-    # all_objects is an array of module and class objects
-    # options includes a :serializer key to copy output to the file system
-    YARD::Templates::Engine.generate(all_objects, options)
-
-Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
-class has a {YARD::CodeObjects::Base#format #format} helper method to render an
-object. For instance, the above render example is equivalent to the simple
-call `myobject.format`. The `generate` method is a special kind of render
-and is called from the {YARD::CLI::Yardoc} command line utility.
-
-## Template Options
-
-A template keeps state when it is rendering 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`). This options hash is modifiable
-from all methods seen above. For example, initializing a template to output as
-HTML instead of text can be done as follows:
-
-    myobject.format(:format => :html)
-
-## 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.
-
-Rendered objects are automatically serialized using the object if present,
-otherwise the rendered object is returned as a string to its parent. Nested
-Templates automatically set the serializer to nil so that they return
-as a String to their parent.
-
-## Creating a Template
-
-Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
-on disk. A standard template directory looks like the following tree:
-
-    (Assuming templates/ is a template path)
-    templates
-    `-- default
-        |-- class
-        |   |-- dot
-        |   |   |-- setup.rb
-        |   |   `-- superklass.erb
-        |   |-- html
-        |   |   |-- constructor_details.erb
-        |   |   |-- setup.rb
-        |   |   `-- subclasses.erb
-        |   |-- setup.rb
-        |   `-- text
-        |       |-- setup.rb
-        |       `-- subclasses.erb
-        |-- docstring
-        |   |-- html
-        |   |   |-- abstract.erb
-        |   |   |-- deprecated.erb
-        |   |   |-- index.erb
-        |   |   `-- text.erb
-        |   |-- setup.rb
-        |   `-- text
-        |       |-- abstract.erb
-        |       |-- deprecated.erb
-        |       |-- index.erb
-        |       `-- text.erb
-
-The path `default` refers to the template style (:template key in options hash)
-and the directories at the next level (such as `class`) refer to template
-`:type` (options hash key) for a template. The next directory refers to the
-output format being used defined by the `:format` template option.
-
-As we saw in the above example, the format option can be set to `:html`, which
-would use the `html/` directory instead of `text/`. Finally, the individual .erb
-files are the sections that make up the template.
-
-Note that the subdirectory `html/` is also its own "template" that inherits
-from the parent directory. We will see more on this later.
-
-## setup.rb
-
-Every template should have at least one `setup.rb` file that defines the
-{YARD::Templates::Template#init #init} method to set the
-{YARD::Templates::Template#sections #sections} used by the template. If
-a setup.rb is not defined in the template itself, there should be a template
-that is inherited (via parent directory or explicitly) that sets the sections
-on a newly created template.
-
-A standard setup.rb file looks like:
-
-    def init
-      sections :section1, :section2, :section3
-    end
-
-## Sections
-
-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 {YARD::Templates::Template} (which in turn has its own
-list of sections).
-
-## Nested Sections
-
-Sections often require the ability to encapsulate a set of sub-sections in markup
-(HTML, for instance). Rather than use heavier Template subclass objects, a more
-lightweight solution is to nest a set of sub-sections as a list that follows
-a section, for example:
-
-    def init
-      sections :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">
-      <%= yieldall %>
-    </div>
-
-This template code would place the output of `section_a` and `section_b` within
-the above div element. Using `yieldall`, we can also change the object that is being
-rendered. For example, we may want to yield the first method of the class.
-We can do this like so:
-
-    <h2>First method</h2>
-    <%= yieldall :object => object.meths.first %>
-
-This would run the nested sections for the method object instead of the class.
-
-Note that `yieldall` yields to all subsections, whereas `yield` will yield
-to each individually (in order) until there are no more left to yield to.
-In the vast majority of cases, you'd want to use `yieldall`, since `yield`
-makes it hard for users to override your template.
-
-## Inheriting Templates
-
-Parent directory templates are automatically inherited (or mixed in, to be
-more accurate) by the current template. This means that the 'default/class/html'
-template automatically inherits from 'default/class'. This also means that anything
-defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.
-
-Since the Template module is a module, and not a class, they can be mixed in
-explicitly (via include/extend) from other templates, which allows templates
-to share erb files or helper logic. The 'default/class' template explicitly
-mixes in the 'default/module' template, since it uses much of the same sections.
-This is done with the helper {YARD::Templates::Template::ClassMethods#T T} method, which
-is simply a shorthand for {YARD::Templates::Engine.template Engine.template}.
-It can then override (using standard inheritance) the sections from the module
-template and insert sections pertaining to classes. This is one of the design
-goals described above.
-
-For instance, the first line in `default/class/html/setup.rb` is:
-
-    include T('default/module/html')
-
-This includes the 'default/module/html', which means it also includes 'default/module'
-by extension. This allows class to make use of any of module's erb files.
-
-## Inserting and Traversing Sections
-
-The ability to insert sections was mentioned above. The class template, for
-instance, will modify the #init method to insert class specific sections:
-
-    def init
-      super
-      sections.place(:subclasses).before(:children)
-      sections.delete(:children)
-      sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
-    end
-
-Observe how sections has been modified after the super method was called (the
-super method would have been defined in `default/module/setup.rb`). The
-`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
-before or after another section using {Array#place} by it's given name rather
-than index. This allows the overriding of templates in a way that does not
-depend on where the section is located (since it may have been overridden by
-another module).
-
-You can also use `sections[:name]` to find the first child section named `:name`.
-For instance, with the following sections declaration:
-
-    sections :a, [:b, :c, [:d]]
-
-You can get to the :d section with:
-
-    sections[:a][:c][:d]
-
-You can use this to insert a section inside a nested set without using indexed
-access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
-
-    sections[:a][:c].place(:e).after(:d)
-
-There are also two methods, {Insertion#before_any} and {Insertion#after_any},
-which allow you to insert sections before or after the first matching section name
-recursively. The above example could simply be rewritten as:
-
-    sections.place(:e).after_any(:d)
-
-## Overriding Templates by Registering a Template Path
-
-Inheriting templates explicitly is useful when creating a customized template
-that wants to take advantage of code re-use. However, most users who want
-to customize YARD templates will want to override existing behaviour without
-creating a template from scratch.
-
-YARD solves this problem by allowing other template paths to be registered.
-Because template modules are represented by a relative path such as 'default/class',
-they can be found within any of the registered template paths. A new template
-path is registered as:
-
-    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'
-
-At this point, any time the 'default/class' template is loaded, the template
-will first be looked for inside the newly registered template path. If found,
-it will be used as the template module, with the modules from the other
-template paths implicitly mixed in.
-
-Therefore, by using the same directory structure as a builtin YARD template,
-a user can customize or override individual templates as if the old ones were
-inherited. A real world example would further modify the 'default/class' template
-seen above by creating such a path in our '/path/to/mytemplates' custom template
-path:
-
-    /path/to/mytemplates/:
-    |-- class
-    |   |-- html
-    |   |   |-- customsection.erb
-    |   |-- setup.rb
-
-The `setup.rb` file would look like:
-
-    def init
-      super
-      sections.push :customsection
-    end
-
-Now, when a class object is formatted as HTML, our customsection.erb will be
-appended to the rendered data.
-
-
-### Overriding Stylesheets and Javascripts
-
-Template authors can override existing stylesheets and javascripts by creating
-a file with the same name as existing files within the `fulldoc` template. The
-documentation output will utilize the new replacement file.
-
-YARD's `fulldoc` template defines three stylesheets:
-
-    /yard/templates/default/:
-    |-- fulldoc
-    |   |-- html
-    |   |   |-- css
-    |   |   |   |-- common.css
-    |   |   |   |-- full_list.css
-    |   |   |   |-- style.css
-
-The `style.css` is the primary stylesheet for the HTML output.
-
-The `full_list.css` is an additional stylesheet loaded specifically for the
-search field menus (i.e. class list, method list, and file list).
-
-The `common.css` is an empty css file that an template author can easily override
-to provide custom styles for their plugin. However, if a user installs multiple
-plugins that utilize this same file to deliver styles, it is possible that they
-will be overridden.
-
-YARD's `fulldoc` template defines three javascript files:
-
-    /yard/templates/default/:
-    |-- fulldoc
-    |   |-- html
-    |   |   |-- js
-    |   |   |   |-- app.js
-    |   |   |   |-- full_list.js
-    |   |   |   |-- jquery.js
-
-The `app.js` is the primary javascript file for the HTML output.
-
-The `full_list.js` defines additional javascript loaded specifically for the
-search field menus (i.e. class list, method list, and file list).
-
-The `jquery.js` is copy of the jquery javascript library.
-
-### Adding a Custom Stylesheet or Javascript
-
-To load additional stylesheets and javascripts with every page (except the search
-field menus) generated from the base `layout` template:
-
-  1. Define your own custom stylesheet and/or javascript file
-     (default/ is the default template name inside of the /template root directory):
-
-         /template/default/:
-         |-- fulldoc
-         |   |-- html
-         |   |   |-- css
-         |   |   |   |-- custom.css
-         |   |   |-- js
-         |   |   |   |-- custom.js
-
-  2. Create a `setup.rb` in the `layout` template directory and override the methods
-     `stylesheets` and `javascripts`. The path to the template would be:
-
-         /template/default/:
-         |-- layout
-         |   |-- html
-         |   |   |-- setup.rb
-
-     And the code would look like:
-
-         def stylesheets
-           # Load the existing stylesheets while appending the custom one
-           super + %w(css/custom.css)
-         end
-
-         def javascripts
-           # Load the existing javascripts while appending the custom one
-           super + %w(js/custom.js)
-         end
-
-
-To load additional stylesheets and javascripts for the search menus loaded from
-the `fulldoc` template:
-
-  1. Define your own custom stylesheet and/or javascript file.
-
-        /path/to/mytemplates/:
-        |-- fulldoc
-        |   |-- html
-        |   |   |-- css
-        |   |   |   |-- custom_full_menu.css
-        |   |   |-- js
-        |   |   |   |-- custom_full_menu.js
-
-
-  3. Override the methods `stylesheets_full_list` and `javascripts_full_list`
-     in the `setup.rb` file inside fulldoc/html.
-
-        def stylesheets_full_list
-          # Load the existing stylesheets while appending the custom one
-          super + %w(css/custom.css)
-        end
-
-        def javascripts_full_list
-          # Load the existing javascripts while appending the custom one
-          super + %w(js/custom.js)
-        end
-
-### Overriding Search Menus
-
-By default YARD's `fulldoc` template generates three search fields:
-
-  * Class List
-  * Method List
-  * File List
-
-Their contents are rendered in methods within the `fulldoc` template:
-
-  * `generate_class_list`
-  * `generate_method_list`
-  * `generate_file_list`
-
-To override these lists you will need to:
-
-  1. Create a `setup.rb` in the `fulldoc` template directory and override the
-     particular method.
-
-         /path/to/mytemplates/:
-         |-- fulldoc
-         |   |-- html
-         |   |   |-- setup.rb
-
-         def generate_method_list
-           @items = prune_method_listing(Registry.all(:method), false)
-           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
-
-           # Here we changed the functionality to reverse the order of displayed methods
-           @items = @items.sort_by {|m| m.name.to_s }.reverse
-           @list_title = "Method List"
-           @list_type = "methods"
-           asset('method_list.html', erb(:full_list))
-         end
-
-### Adding Additional Search Menus
-
-By default YARD's `fulldoc` template generates three search fields:
-
-  * Class List
-  * Method List
-  * File List
-
-These are defined in the `layout` template method `menu_lists` and pulled into
-the `fulldoc` template through a similarly named method.
-
-To load an additional menu item:
-
-
-  1. Create a `setup.rb` in the `layout` template directory and override the methods
-   `menu_lists`. The `type` informs the search field the name of the file.
-    The `title` is the name that appears above the section when viewed in frames.
-    The `search_title` is the name that appears in the search field tab on the page.
-
-
-        /path/to/mytemplates/:
-        |-- layout
-        |   |-- html
-        |   |   |-- setup.rb
-
-        def menu_lists
-          # Load the existing menus
-          super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
-        end
-
-  2. Create a `setup.rb` in the `fulldoc` template directory and create a method
-     to generate a menu for the specified `type`.
-     The method `generate_assets` will look for a function with a signature prefixed
-     with `generate`, the type value specified, and the suffix `list`. Within that
-     method you can configure and load the specific objects you wish to display.
-
-         /path/to/mytemplates/:
-         |-- fulldoc
-         |   |-- html
-         |   |   |-- setup.rb
-
-         def generate_feature_list
-
-           # load all the features from the Registry
-           @items = Registry.all(:feature)
-           @list_title = "Feature List"
-           @list_type = "feature"
-
-           # optional: the specified stylesheet class
-           # when not specified it will default to the value of @list_type
-           @list_class = "class"
-
-           # Generate the full list html file with named feature_list.html
-           # @note this file must be match the name of the type
-           asset('feature_list.html', erb(:full_list))
-         end
+# @title Templates Architecture
+
+# Templates Architecture
+
+Templates are the main component in the output rendering process of YARD,
+which is invoked when conventional HTML/text output needs to be rendered
+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 rendering 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 rendered for any arbitrary format with little
+     modification to YARD's source code. The addition of extra templates should
+     be sufficient.
+  2. The output rendered for an object should independently rendered 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.
+
+## Templates
+
+Template modules 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.
+
+## Engine
+
+The Engine class orchestrates the creation and rendering of Template modules and
+handles serialization or specific rendering scenarios (like HTML). To create
+a template, use the {YARD::Templates::Engine.template template} method. The two most
+common methods used to initiate output are the {YARD::Templates::Engine.render render}
+and {YARD::Templates::Engine.generate generate} methods which generate and
+optionally serialize output to a file. The latter, `#generate`, is used
+specially to generate HTML documentation and copy over assets that may be
+needed. For instance, an object may be rendered with:
+
+    YARD::Templates::Engine.render(:object => myobject)
+
+A set of objects may be rendered into HTML documentation by using:
+
+    # all_objects is an array of module and class objects
+    # options includes a :serializer key to copy output to the file system
+    YARD::Templates::Engine.generate(all_objects, options)
+
+Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
+class has a {YARD::CodeObjects::Base#format #format} helper method to render an
+object. For instance, the above render example is equivalent to the simple
+call `myobject.format`. The `generate` method is a special kind of render
+and is called from the {YARD::CLI::Yardoc} command line utility.
+
+## Template Options
+
+A template keeps state when it is rendering 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`). This options hash is modifiable
+from all methods seen above. For example, initializing a template to output as
+HTML instead of text can be done as follows:
+
+    myobject.format(:format => :html)
+
+## 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.
+
+Rendered objects are automatically serialized using the object if present,
+otherwise the rendered object is returned as a string to its parent. Nested
+Templates automatically set the serializer to nil so that they return
+as a String to their parent.
+
+## Creating a Template
+
+Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
+on disk. A standard template directory looks like the following tree:
+
+    (Assuming templates/ is a template path)
+    templates
+    `-- default
+        |-- class
+        |   |-- dot
+        |   |   |-- setup.rb
+        |   |   `-- superklass.erb
+        |   |-- html
+        |   |   |-- constructor_details.erb
+        |   |   |-- setup.rb
+        |   |   `-- subclasses.erb
+        |   |-- setup.rb
+        |   `-- text
+        |       |-- setup.rb
+        |       `-- subclasses.erb
+        |-- docstring
+        |   |-- html
+        |   |   |-- abstract.erb
+        |   |   |-- deprecated.erb
+        |   |   |-- index.erb
+        |   |   `-- text.erb
+        |   |-- setup.rb
+        |   `-- text
+        |       |-- abstract.erb
+        |       |-- deprecated.erb
+        |       |-- index.erb
+        |       `-- text.erb
+
+The path `default` refers to the template style (:template key in options hash)
+and the directories at the next level (such as `class`) refer to template
+`:type` (options hash key) for a template. The next directory refers to the
+output format being used defined by the `:format` template option.
+
+As we saw in the above example, the format option can be set to `:html`, which
+would use the `html/` directory instead of `text/`. Finally, the individual .erb
+files are the sections that make up the template.
+
+Note that the subdirectory `html/` is also its own "template" that inherits
+from the parent directory. We will see more on this later.
+
+## setup.rb
+
+Every template should have at least one `setup.rb` file that defines the
+{YARD::Templates::Template#init #init} method to set the
+{YARD::Templates::Template#sections #sections} used by the template. If
+a setup.rb is not defined in the template itself, there should be a template
+that is inherited (via parent directory or explicitly) that sets the sections
+on a newly created template.
+
+A standard setup.rb file looks like:
+
+    def init
+      sections :section1, :section2, :section3
+    end
+
+## Sections
+
+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 {YARD::Templates::Template} (which in turn has its own
+list of sections).
+
+## Nested Sections
+
+Sections often require the ability to encapsulate a set of sub-sections in markup
+(HTML, for instance). Rather than use heavier Template subclass objects, a more
+lightweight solution is to nest a set of sub-sections as a list that follows
+a section, for example:
+
+    def init
+      sections :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">
+      <%= yieldall %>
+    </div>
+
+This template code would place the output of `section_a` and `section_b` within
+the above div element. Using `yieldall`, we can also change the object that is being
+rendered. For example, we may want to yield the first method of the class.
+We can do this like so:
+
+    <h2>First method</h2>
+    <%= yieldall :object => object.meths.first %>
+
+This would run the nested sections for the method object instead of the class.
+
+Note that `yieldall` yields to all subsections, whereas `yield` will yield
+to each individually (in order) until there are no more left to yield to.
+In the vast majority of cases, you'd want to use `yieldall`, since `yield`
+makes it hard for users to override your template.
+
+## Inheriting Templates
+
+Parent directory templates are automatically inherited (or mixed in, to be
+more accurate) by the current template. This means that the 'default/class/html'
+template automatically inherits from 'default/class'. This also means that anything
+defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.
+
+Since the Template module is a module, and not a class, they can be mixed in
+explicitly (via include/extend) from other templates, which allows templates
+to share erb files or helper logic. The 'default/class' template explicitly
+mixes in the 'default/module' template, since it uses much of the same sections.
+This is done with the helper {YARD::Templates::Template::ClassMethods#T T} method, which
+is simply a shorthand for {YARD::Templates::Engine.template Engine.template}.
+It can then override (using standard inheritance) the sections from the module
+template and insert sections pertaining to classes. This is one of the design
+goals described above.
+
+For instance, the first line in `default/class/html/setup.rb` is:
+
+    include T('default/module/html')
+
+This includes the 'default/module/html', which means it also includes 'default/module'
+by extension. This allows class to make use of any of module's erb files.
+
+## Inserting and Traversing Sections
+
+The ability to insert sections was mentioned above. The class template, for
+instance, will modify the #init method to insert class specific sections:
+
+    def init
+      super
+      sections.place(:subclasses).before(:children)
+      sections.delete(:children)
+      sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
+    end
+
+Observe how sections has been modified after the super method was called (the
+super method would have been defined in `default/module/setup.rb`). The
+`sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
+before or after another section using {Array#place} by it's given name rather
+than index. This allows the overriding of templates in a way that does not
+depend on where the section is located (since it may have been overridden by
+another module).
+
+You can also use `sections[:name]` to find the first child section named `:name`.
+For instance, with the following sections declaration:
+
+    sections :a, [:b, :c, [:d]]
+
+You can get to the :d section with:
+
+    sections[:a][:c][:d]
+
+You can use this to insert a section inside a nested set without using indexed
+access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
+
+    sections[:a][:c].place(:e).after(:d)
+
+There are also two methods, {Insertion#before_any} and {Insertion#after_any},
+which allow you to insert sections before or after the first matching section name
+recursively. The above example could simply be rewritten as:
+
+    sections.place(:e).after_any(:d)
+
+## Overriding Templates by Registering a Template Path
+
+Inheriting templates explicitly is useful when creating a customized template
+that wants to take advantage of code re-use. However, most users who want
+to customize YARD templates will want to override existing behaviour without
+creating a template from scratch.
+
+YARD solves this problem by allowing other template paths to be registered.
+Because template modules are represented by a relative path such as 'default/class',
+they can be found within any of the registered template paths. A new template
+path is registered as:
+
+    YARD::Templates::Engine.register_template_path '/path/to/mytemplates'
+
+At this point, any time the 'default/class' template is loaded, the template
+will first be looked for inside the newly registered template path. If found,
+it will be used as the template module, with the modules from the other
+template paths implicitly mixed in.
+
+Therefore, by using the same directory structure as a builtin YARD template,
+a user can customize or override individual templates as if the old ones were
+inherited. A real world example would further modify the 'default/class' template
+seen above by creating such a path in our '/path/to/mytemplates' custom template
+path:
+
+    /path/to/mytemplates/:
+    |-- class
+    |   |-- html
+    |   |   |-- customsection.erb
+    |   |-- setup.rb
+
+The `setup.rb` file would look like:
+
+    def init
+      super
+      sections.push :customsection
+    end
+
+Now, when a class object is formatted as HTML, our customsection.erb will be
+appended to the rendered data.
+
+
+### Overriding Stylesheets and Javascripts
+
+Template authors can override existing stylesheets and javascripts by creating
+a file with the same name as existing files within the `fulldoc` template. The
+documentation output will utilize the new replacement file.
+
+YARD's `fulldoc` template defines three stylesheets:
+
+    /yard/templates/default/:
+    |-- fulldoc
+    |   |-- html
+    |   |   |-- css
+    |   |   |   |-- common.css
+    |   |   |   |-- full_list.css
+    |   |   |   |-- style.css
+
+The `style.css` is the primary stylesheet for the HTML output.
+
+The `full_list.css` is an additional stylesheet loaded specifically for the
+search field menus (i.e. class list, method list, and file list).
+
+The `common.css` is an empty css file that an template author can easily override
+to provide custom styles for their plugin. However, if a user installs multiple
+plugins that utilize this same file to deliver styles, it is possible that they
+will be overridden.
+
+YARD's `fulldoc` template defines three javascript files:
+
+    /yard/templates/default/:
+    |-- fulldoc
+    |   |-- html
+    |   |   |-- js
+    |   |   |   |-- app.js
+    |   |   |   |-- full_list.js
+    |   |   |   |-- jquery.js
+
+The `app.js` is the primary javascript file for the HTML output.
+
+The `full_list.js` defines additional javascript loaded specifically for the
+search field menus (i.e. class list, method list, and file list).
+
+The `jquery.js` is copy of the jquery javascript library.
+
+### Adding a Custom Stylesheet or Javascript
+
+To load additional stylesheets and javascripts with every page (except the search
+field menus) generated from the base `layout` template:
+
+  1. Define your own custom stylesheet and/or javascript file
+     (default/ is the default template name inside of the /template root directory):
+
+         /template/default/:
+         |-- fulldoc
+         |   |-- html
+         |   |   |-- css
+         |   |   |   |-- custom.css
+         |   |   |-- js
+         |   |   |   |-- custom.js
+
+  2. Create a `setup.rb` in the `layout` template directory and override the methods
+     `stylesheets` and `javascripts`. The path to the template would be:
+
+         /template/default/:
+         |-- layout
+         |   |-- html
+         |   |   |-- setup.rb
+
+     And the code would look like:
+
+         def stylesheets
+           # Load the existing stylesheets while appending the custom one
+           super + %w(css/custom.css)
+         end
+
+         def javascripts
+           # Load the existing javascripts while appending the custom one
+           super + %w(js/custom.js)
+         end
+
+
+To load additional stylesheets and javascripts for the search menus loaded from
+the `fulldoc` template:
+
+  1. Define your own custom stylesheet and/or javascript file.
+
+        /path/to/mytemplates/:
+        |-- fulldoc
+        |   |-- html
+        |   |   |-- css
+        |   |   |   |-- custom_full_menu.css
+        |   |   |-- js
+        |   |   |   |-- custom_full_menu.js
+
+
+  3. Override the methods `stylesheets_full_list` and `javascripts_full_list`
+     in the `setup.rb` file inside fulldoc/html.
+
+        def stylesheets_full_list
+          # Load the existing stylesheets while appending the custom one
+          super + %w(css/custom.css)
+        end
+
+        def javascripts_full_list
+          # Load the existing javascripts while appending the custom one
+          super + %w(js/custom.js)
+        end
+
+### Overriding Search Menus
+
+By default YARD's `fulldoc` template generates three search fields:
+
+  * Class List
+  * Method List
+  * File List
+
+Their contents are rendered in methods within the `fulldoc` template:
+
+  * `generate_class_list`
+  * `generate_method_list`
+  * `generate_file_list`
+
+To override these lists you will need to:
+
+  1. Create a `setup.rb` in the `fulldoc` template directory and override the
+     particular method.
+
+         /path/to/mytemplates/:
+         |-- fulldoc
+         |   |-- html
+         |   |   |-- setup.rb
+
+         def generate_method_list
+           @items = prune_method_listing(Registry.all(:method), false)
+           @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
+
+           # Here we changed the functionality to reverse the order of displayed methods
+           @items = @items.sort_by {|m| m.name.to_s }.reverse
+           @list_title = "Method List"
+           @list_type = "methods"
+           asset('method_list.html', erb(:full_list))
+         end
+
+### Adding Additional Search Menus
+
+By default YARD's `fulldoc` template generates three search fields:
+
+  * Class List
+  * Method List
+  * File List
+
+These are defined in the `layout` template method `menu_lists` and pulled into
+the `fulldoc` template through a similarly named method.
+
+To load an additional menu item:
+
+
+  1. Create a `setup.rb` in the `layout` template directory and override the methods
+   `menu_lists`. The `type` informs the search field the name of the file.
+    The `title` is the name that appears above the section when viewed in frames.
+    The `search_title` is the name that appears in the search field tab on the page.
+
+
+        /path/to/mytemplates/:
+        |-- layout
+        |   |-- html
+        |   |   |-- setup.rb
+
+        def menu_lists
+          # Load the existing menus
+          super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
+        end
+
+  2. Create a `setup.rb` in the `fulldoc` template directory and create a method
+     to generate a menu for the specified `type`.
+     The method `generate_assets` will look for a function with a signature prefixed
+     with `generate`, the type value specified, and the suffix `list`. Within that
+     method you can configure and load the specific objects you wish to display.
+
+         /path/to/mytemplates/:
+         |-- fulldoc
+         |   |-- html
+         |   |   |-- setup.rb
+
+         def generate_feature_list
+
+           # load all the features from the Registry
+           @items = Registry.all(:feature)
+           @list_title = "Feature List"
+           @list_type = "feature"
+
+           # optional: the specified stylesheet class
+           # when not specified it will default to the value of @list_type
+           @list_class = "class"
+
+           # Generate the full list html file with named feature_list.html
+           # @note this file must be match the name of the type
+           asset('feature_list.html', erb(:full_list))
+         end