yard 0.5.8 → 0.6.0

data/lib/yard/tags/default_factory.rb

@@ -4,7 +4,6 @@ module YARD
       TYPELIST_OPENING_CHARS = '[({<'
       TYPELIST_CLOSING_CHARS = '>})]'
       
-      ##
       # Parses tag text and creates a new tag with descriptive text
       #
       # @param tag_name        the name of the tag to parse
@@ -14,7 +13,6 @@ module YARD
         Tag.new(tag_name, text)
       end
       
-      ##
       # Parses tag text and creates a new tag with a key name and descriptive text
       #
       # @param tag_name        the name of the tag to parse
@@ -25,7 +23,6 @@ module YARD
         Tag.new(tag_name, text, nil, name)
       end
       
-      ##
       # Parses tag text and creates a new tag with formally declared types and 
       # descriptive text
       #
@@ -38,7 +35,6 @@ module YARD
         Tag.new(tag_name, text, types)
       end
       
-      ##
       # Parses tag text and creates a new tag with formally declared types, a key 
       # name and descriptive text
       #
@@ -76,7 +72,6 @@ module YARD
       
       private
       
-      ##
       # Extracts the name from raw tag text returning the name and remaining value
       #
       # @param [String] text the raw tag text

data/lib/yard/tags/library.rb

@@ -1,6 +1,5 @@
 module YARD
   module Tags
-    ##
     # Holds all the registered meta tags. If you want to extend YARD and add
     # a new meta tag, you can do it in one of two ways.
     #
@@ -69,8 +68,40 @@ module YARD
         def default_factory=(factory)
           @default_factory = factory.is_a?(Class) ? factory.new : factory
         end
+        
+        # Returns the factory method used to parse the tag text for a specific tag
+        # 
+        # @param [Symbol] tag the tag name
+        # @return [Symbol] the factory method name for the tag
+        # @return [Class<Tag>] the Tag class to use to parse the tag
+        # @return [nil] if the tag is freeform text
+        # @since 0.6.0
+        def factory_method_for(tag)
+          @factory_methods[tag]
+        end
+        
+        # Sets the list of tags to display when rendering templates. The order of 
+        # tags in the list is also significant, as it represents the order that 
+        # tags are displayed in templates.
+        # 
+        # You can use the {Array#place} to insert new tags to be displayed in 
+        # the templates at specific positions:
+        # 
+        #   Library.visible_tags.place(:mytag).before(:return)
+        # 
+        # @return [Array<Symbol>] a list of ordered tags
+        # @since 0.6.0
+        attr_accessor :visible_tags
+        
+        # Sets the list of tags that should apply to any children inside the
+        # namespace they are defined in. For instance, a "@since" tag should
+        # apply to all methods inside a module is it defined in. Transitive
+        # tags can be overridden by directly defining a tag on the child object.
+        # 
+        # @return [Array<Symbol>] a list of transitive tags
+        # @since 0.6.0
+        attr_accessor :transitive_tags
       
-        ## 
         # Sorts the labels lexically by their label name, often used when displaying
         # the tags.
         # 
@@ -79,14 +110,13 @@ module YARD
           labels.sort_by {|a| a.last.downcase }
         end
       
-        ##
         # Convenience method to define a new tag using one of {Tag}'s factory methods, or the
         # regular {DefaultFactory#parse_tag} factory method if none is supplied.
         #
         # @param [#to_s] tag the tag name to create
         # @param [#to_s, Class<Tag>] meth the {Tag} factory method to call when 
         #   creating the tag or the name of the class to directly create a tag for
-        def define_tag(label, tag, meth = "")
+        def define_tag(label, tag, meth = nil)
           if meth.is_a?(Class) && Tag > meth
             class_eval <<-eof, __FILE__, __LINE__
               def #{tag}_tag(text) 
@@ -103,6 +133,8 @@ module YARD
 
           @labels ||= SymbolHash.new(false)
           @labels.update(tag => label)
+          @factory_methods ||= SymbolHash.new(false)
+          @factory_methods.update(tag => meth)
           tag
         end
       end
@@ -129,29 +161,36 @@ module YARD
         self.factory = factory
       end
       
-      define_tag "Parameters",        :param,       :with_types_and_name
-      define_tag "Yield Parameters",  :yieldparam,  :with_types_and_name
-      define_tag "Yield Returns",     :yieldreturn, :with_types
-      define_tag "Yields",            :yield,       :with_types
-      define_tag "Default Value",     :default,     :with_name
-      define_tag "Returns",           :return,      :with_types
-      define_tag "Deprecated",        :deprecated
-      define_tag "Author",            :author
-      define_tag "Raises",            :raise,       :with_types
-      define_tag "See Also",          :see,         :with_name
-      define_tag "Since",             :since
-      define_tag "Version",           :version
+      define_tag "Abstract",          :abstract
       define_tag "API Visibility",    :api
-      define_tag "Note",              :note
-      define_tag "Todo Item",         :todo
+      define_tag "Attribute",         :attr,         :with_types_and_name
+      define_tag "Attribute Getter",  :attr_reader,  :with_types_and_name
+      define_tag "Attribute Setter",  :attr_writer,  :with_types_and_name
+      define_tag "Author",            :author
+      define_tag "Deprecated",        :deprecated
       define_tag "Example",           :example,     :with_title_and_text
+      define_tag "End Grouping",      :endgroup
+      define_tag "Grouping",          :group
+      define_tag "Note",              :note
       define_tag "Options Hash",      :option,      :with_options
       define_tag "Overloads",         :overload,    OverloadTag
+      define_tag "Parameters",        :param,       :with_types_and_name
       define_tag "Private",           :private
-      define_tag "Abstract",          :abstract
-      define_tag "Attribute",         :attr,         :with_types_and_name
-      define_tag "Attribute Getter",  :attr_reader,  :with_types_and_name
-      define_tag "Attribute Setter",  :attr_writer,  :with_types_and_name
+      define_tag "Raises",            :raise,       :with_types
+      define_tag "Returns",           :return,      :with_types
+      define_tag "See Also",          :see,         :with_name
+      define_tag "Since",             :since
+      define_tag "Todo Item",         :todo
+      define_tag "Version",           :version
+      define_tag "Yields",            :yield,       :with_types
+      define_tag "Yield Parameters",  :yieldparam,  :with_types_and_name
+      define_tag "Yield Returns",     :yieldreturn, :with_types
+      
+      self.visible_tags = [:abstract, :deprecated, :note, :todo, :example, :overload, 
+        :param, :option, :yield, :yieldparam, :yieldreturn, :return, :raise, 
+        :see, :author, :since, :version]
+      
+      self.transitive_tags = [:since]
     end
   end
 end

data/lib/yard/tags/tag.rb

@@ -1,9 +1,32 @@
 module YARD
   module Tags
+    # Represents a metadata tag value (+@tag+). Tags can have any combination of
+    # {#types}, {#name} and {#text}, or none of the above.
+    # 
+    # @example Programmatic tag creation
+    #   # The following docstring syntax:
+    #   #   @param [String, nil] arg an argument
+    #   #
+    #   # is equivalent to:
+    #   Tag.new(:param, 'an argument', ['String', 'nil'], 'arg')
     class Tag
-      attr_accessor :tag_name, :text, :types, :name, :object
+      # @return [String] the name of the tag
+      attr_accessor :tag_name
+      
+      # @return [String] the tag text associated with the tag
+      # @return [nil] if no tag text is supplied
+      attr_accessor :text
+      
+      # @return [Array<String>] a list of types associated with the tag
+      # @return [nil] if no types are associated with the tag
+      attr_accessor :types
+      
+      # @return [String] a name associated with the tag
+      attr_accessor :name
+      
+      # @return [CodeObjects::Base] the associated object
+      attr_accessor :object
 
-      ##
       # Creates a new tag object with a tag name and text. Optionally, formally declared types
       # and a key name can be specified.
       #
@@ -12,7 +35,7 @@ module YARD
       # Key names are for tags that declare meta data for a specific key or name, such as +param+,
       # +raise+, etc.
       #
-      # @param tag_name                the tag name to create the tag for
+      # @param [#to_s] tag_name        the tag name to create the tag for
       # @param [String] text           the descriptive text for this tag
       # @param [Array<String>] types   optional type list of formally declared types
       #                                for the tag
@@ -21,7 +44,6 @@ module YARD
         @tag_name, @text, @name, @types = tag_name.to_s, text, name, (types ? [types].flatten.compact : nil)
       end
 
-      ##
       # Convenience method to access the first type specified. This should mainly
       # be used for tags that only specify one type.
       #

data/lib/yard/templates/engine.rb

@@ -1,5 +1,13 @@
+require 'ostruct'
+
 module YARD
   module Templates
+    # This module manages all creation, handling and rendering of {Engine::Template} 
+    # objects. 
+    # 
+    # * To create a template object at a path, use {template}. 
+    # * To render a template, call {render}.
+    # * To register a template path in the lookup paths, call {register_template_path}.
     module Engine
       class << self
         # @return [Array<String>] the list of registered template paths
@@ -20,6 +28,8 @@ module YARD
         # generated module as mixins (for overriding).
         # 
         # @param [Array<String, Symbol>] path a list of path components
+        # @raise [ArgumentError] if the path does not exist within one of the
+        #   {template_paths} on disk.
         # @return [Template] the module representing the template
         def template(*path)
           from_template = nil
@@ -43,7 +53,7 @@ module YARD
           full_paths ||= [path]
           full_paths = [full_paths] unless full_paths.is_a?(Array)
           name = template_module_name(full_paths.first)
-          return const_get(name) rescue NameError 
+          begin; return const_get(name); rescue NameError; end
 
           mod = const_set(name, Module.new)
           mod.send(:include, Template)
@@ -120,6 +130,7 @@ module YARD
         # @option options [Symbol] :template (:default) the default template
         # @return [void]
         def set_default_options(options = {})
+          options[:__globals] ||= OpenStruct.new
           options[:format] ||= :text
           options[:type] ||= options[:object].type if options[:object]
           options[:template] ||= :default

data/lib/yard/templates/erb_cache.rb

@@ -1,12 +1,13 @@
 module YARD
   module Templates
+    # @since 0.5.4
     module ErbCache
       def self.method_for(filename, &block)
         @methods ||= {}
         return @methods[filename] if @methods[filename]
         @methods[filename] = name = "_erb_cache_#{@methods.size}"
         erb = yield.src
-        encoding = erb[/\A(#coding:.*\r?\n)/, 1] || ''
+        encoding = erb[/\A(#coding[:=].*\r?\n)/, 1] || ''
         module_eval "#{encoding}def #{name}; #{erb}; end", filename
         
         name

data/lib/yard/templates/helpers/base_helper.rb

@@ -1,23 +1,62 @@
 module YARD::Templates::Helpers
+  # The base helper module included in all templates.
   module BaseHelper
     attr_accessor :object, :serializer
     
+    # @group Managing Global Template State
+    
+    # An object that keeps track of global state throughout the entire template 
+    # rendering process (including any sub-templates).
+    # 
+    # @return [OpenStruct] a struct object that stores state
+    # @since 0.6.0
+    def globals; options[:__globals] end
+    
+    # @group Running the Verifier
+    
+    # Runs a list of objects against the {Verifier} object passed into the 
+    # template and returns the subset of verified objects.
+    # 
+    # @param [Array<CodeObjects::Base>] list a list of code objects
+    # @return [Array<CodeObjects::Base>] a list of code objects that match
+    #   the verifier. If no verifier is supplied, all objects are returned.
     def run_verifier(list)
-      return list unless options[:verifier]
-      list.reject {|item| options[:verifier].call(item).is_a?(FalseClass) }
+      options[:verifier] ? options[:verifier].run(list) : list
     end
     
-    # This is used a lot by the HtmlHelper and there should
+    # @group Escaping Text
+    
+    # Escapes text. This is used a lot by the HtmlHelper and there should
     # be some helper to "clean up" text for whatever, this is it.
     def h(text)
       text
     end
     
+    # @group Linking Objects and URLs
+    
+    # Links objects or URLs. This method will delegate to the correct +link_+
+    # method depending on the arguments passed in.
+    # 
+    # @example Linking a URL
+    #   linkify('http://example.com')
+    # @example Including docstring contents of an object
+    #   linkify('include:YARD::Docstring')
+    # @example Linking to an extra file
+    #   linkify('file:README')
+    # @example Linking an object by path
+    #   linkify('YARD::Docstring')
     def linkify(*args) 
       if args.first.is_a?(String)
         case args.first
         when %r{://}, /^mailto:/
           link_url(args[0], args[1], {:target => '_parent'}.merge(args[2]||{}))
+        when /^include:(\S+)/
+          path = $1
+          if obj = YARD::Registry.resolve(object.namespace, path)
+            link_include_object(obj)
+          else
+            log.warn "Cannot find object at `#{path}' for inclusion"
+          end
         when /^file:(\S+?)(?:#(\S+))?$/
           link_file($1, args[1] ? args[1] : $1, $2)
         else
@@ -27,7 +66,18 @@ module YARD::Templates::Helpers
         link_object(*args)
       end
     end
+    
+    # Includes an object's docstring into output.
+    # @since 0.6.0
+    def link_include_object(object)
+      object.docstring
+    end
 
+    # Links to an object with an optional title
+    # 
+    # @param [CodeObjects::Base] object the object to link to
+    # @param [String] title the title to use for the link
+    # @return [String] the linked object
     def link_object(object, title = nil)
       return title if title
       
@@ -41,18 +91,52 @@ module YARD::Templates::Helpers
       end
     end
     
+    # Links to a URL
+    # 
+    # @param [String] url the URL to link to
+    # @param [String] title the optional title to display the link as
+    # @param [Hash] params optional parameters for the link
+    # @return [String] the linked URL
     def link_url(url, title = nil, params = nil)
       url
     end
     
+    # Links to an extra file 
+    # 
+    # @param [String] filename the filename to link to
+    # @param [String] title the title of the link
+    # @param [String] anchor optional anchor
+    # @return [String] the link to the file
+    # @since 0.5.5
     def link_file(filename, title = nil, anchor = nil)
       filename
     end
     
+    # @group Formatting Object Attributes
+    
+    # Formats a list of return types for output and links each type.
+    # 
+    # @example Formatting types
+    #   format_types(['String', 'Array']) #=> "(String, Array)"
+    # @example Formatting types without surrounding brackets
+    #   format_types(['String', 'Array'], false) #=> "String, Array"
+    # @param [Array<String>] list a list of types
+    # @param [Boolean] brackets whether to surround the types in brackets
+    # @return [String] the formatted list of Ruby types
     def format_types(list, brackets = true)
       list.nil? || list.empty? ? "" : (brackets ? "(#{list.join(", ")})" : list.join(", "))
     end
 
+    # @example Formatted type of an exception class
+    #   o = ClassObject.new(:root, :MyError)
+    #   o.superclass = P('RuntimeError')
+    #   format_object_type(o) # => "Exception"
+    # @example Formatted type of a method
+    #   o = MethodObject.new(:root, :to_s)
+    #   format_object_type(o) # => "Method"
+    # @param [CodeObjects::Base] object the object to retrieve the type for
+    # @return [String] the human-readable formatted {CodeObjects::Base#type #type} 
+    #   for the object
     def format_object_type(object)
       case object
       when YARD::CodeObjects::ClassObject
@@ -62,6 +146,11 @@ module YARD::Templates::Helpers
       end
     end
     
+    # @example
+    #   s = format_object_title ModuleObject.new(:root, :MyModuleName)
+    #   s # => "Module: MyModuleName"
+    # @param [CodeObjects::Base] object the object to retrieve a title for
+    # @return [String] the page title name for a given object
     def format_object_title(object)
       case object
       when YARD::CodeObjects::RootObject
@@ -71,6 +160,10 @@ module YARD::Templates::Helpers
       end
     end
     
+    # Indents and formats source code
+    # 
+    # @param [String] value the input source code
+    # @return [String] formatted source code
     def format_source(value)
       sp = value.split("\n").last[/^(\s+)/, 1]
       num = sp ? sp.size : 0

data/lib/yard/templates/helpers/filter_helper.rb

@@ -1,18 +1,23 @@
 module YARD
   module Templates::Helpers
+    # Helpers for various object types
     module FilterHelper
+      # @return [Boolean] whether an object is a method
       def is_method?(object)
         object.type == :method
       end
 
+      # @return [Boolean] whether an object is a namespace
       def is_namespace?(object)
         object.is_a?(CodeObjects::NamespaceObject)
       end
       
+      # @return [Boolean] whether an object is a class
       def is_class?(object)
         object.is_a?(CodeObjects::ClassObject)
       end
       
+      # @return [Boolean] whether an object is a module
       def is_module?(object)
         object.is_a?(CodeObjects::ModuleObject)
       end