yard 0.7.5 → 0.8.0

data/docs/TagsArch.md

@@ -0,0 +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.

data/docs/Templates.md

@@ -29,32 +29,32 @@ The design goals can be summarized as follows:
   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 
+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. 
+depending on the format.
 
 ## Engine
 
-The Engine class orchestrates the creation and rendering of Template modules and 
+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 
+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
@@ -67,11 +67,11 @@ 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 
+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
@@ -82,7 +82,7 @@ are used (like files or URLs), the serializer implements the {YARD::Serializers:
 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, 
+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.
@@ -120,13 +120,13 @@ on disk. A standard template directory looks like the following tree:
         |       |-- index.erb
         |       `-- text.erb
 
-The path `default` refers to the template style (:template key in options hash) 
+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. 
+`: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 
+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
@@ -134,8 +134,8 @@ 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 
+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 explcitly) that sets the sections
@@ -150,9 +150,9 @@ A standard setup.rb file looks like:
 ## 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 
+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
@@ -165,7 +165,7 @@ 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:
@@ -174,7 +174,7 @@ to them. A sample header.erb template might contain:
     <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.
@@ -197,7 +197,7 @@ 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 
+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.
@@ -225,29 +225,29 @@ instance, will modify the #init method to insert class specific sections:
       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 
+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 overriden by 
+depend on where the section is located (since it may have been overriden 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:
@@ -265,16 +265,16 @@ 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. 
+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 
+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:
@@ -292,7 +292,7 @@ The `setup.rb` file would look like:
       sections.push :customsection
     end
 
-Now, when a class object is formatted as HTML, our customsection.erb will be 
+Now, when a class object is formatted as HTML, our customsection.erb will be
 appended to the rendered data.
 
 
@@ -344,7 +344,7 @@ The `jquery.js` is copy of the jquery javascript library.
 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 
+  1. Define your own custom stylesheet and/or javascript file
      (default/ is the default template name inside of the /template root directory):
 
         /template/default/:
@@ -355,28 +355,28 @@ field menus) generated from the base `layout` template:
         |   |   |-- js
         |   |   |   |-- custom.js
 
-  2. Create a `setup.rb` in the `layout` template directory and override the methods 
+  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 
+
+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.
@@ -416,21 +416,21 @@ 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"
@@ -452,11 +452,11 @@ 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 
+  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
@@ -467,52 +467,30 @@ To load an additional menu item:
           # 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`. 
+     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 
+     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
-
-
-  3. Define custom javascript to load the search fields and the keyboard shortcuts.
-  
-        function featureSearchFrameLinks() {
-            $('#feature_list_link').click(function() {
-                toggleSearchFrame(this, relpath + 'feature_list.html');
-            });
-        }
-
-        function featureKeyboardShortcuts() {
-          if (window.top.frames.main) return;
-          $(document).keypress(function(evt) {
-            if (evt.altKey || evt.ctrlKey || evt.metaKey || evt.shiftKey) return;
-            if (typeof evt.orignalTarget !== "undefined" &&  
-                (evt.originalTarget.nodeName == "INPUT" || 
-                evt.originalTarget.nodeName == "TEXTAREA")) return;
-            switch (evt.charCode) {
-              case 82: case 114: $('#feature_list_link').click(); break; // 'r'
-            }
-          });
-        }