yard 0.5.8 → 0.6.0

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

@@ -1,6 +1,8 @@
 module YARD
   module Templates::Helpers
+    # Helper methods for method objects.
     module MethodHelper
+      # @return [String] formatted arguments for a method
       def format_args(object)
         return if object.parameters.nil?
         params = object.parameters
@@ -19,12 +21,14 @@ module YARD
         end
       end
       
+      # @return [String] formatted and linked return types for a method
       def format_return_types(object)
         return unless object.has_tag?(:return) && object.tag(:return).types
         return if object.tag(:return).types.empty?
         format_types [object.tag(:return).types.first], false
       end
       
+      # @return [String] formatted block if one exists
       def format_block(object)
         if object.has_tag?(:yield) && object.tag(:yield).types
           params = object.tag(:yield).types
@@ -39,12 +43,14 @@ module YARD
         params ? h("{|" + params.join(", ") + "| ... }") : ""
       end
       
+      # @return [String] formats line numbers for source code of an object
       def format_lines(object)
         return "" if object.source.nil? || object.line.nil?
         i = -1
         object.source.split(/\n/).map { object.line + (i += 1) }.join("\n")
       end
       
+      # @return [String] formats source of an object
       def format_code(object, show_lines = false)
         i = -1
         lines = object.source.split(/\n/)
@@ -55,6 +61,7 @@ module YARD
         end.join("\n")
       end
       
+      # @return [String] formats source code of a constant value
       def format_constant(value)
         sp = value.split("\n").last[/^(\s+)/, 1]
         num = sp ? sp.size : 0

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

@@ -1,7 +1,12 @@
 module YARD
   module Templates
     module Helpers
+      # Helper methods for managing module objects.
       module ModuleHelper
+        # Prunes the method listing by running the verifier and removing attributes/aliases
+        # @param [Array<CodeObjects::Base>] list a list of methods
+        # @param [Boolean] hide_attributes whether to prune attribute methods from the list
+        # @return [Array<CodeObjects::Base>] a pruned list of methods
         def prune_method_listing(list, hide_attributes = true)
           list = run_verifier(list)
           list = list.reject {|o| o.is_alias? unless CodeObjects::Proxy === o.namespace }

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

@@ -1,7 +1,9 @@
 module YARD
   module Templates
     module Helpers
+      # Helper methods for text template formats.
       module TextHelper
+        # @return [String] escapes text
         def h(text)
           out = ""
           text = text.split(/\n/)
@@ -16,26 +18,33 @@ module YARD
           out
         end
 
+        # @return [String] wraps text at +col+ columns.
         def wrap(text, col = 72)
           text.gsub(/(.{1,#{col}})( +|$\n?)|(.{1,#{col}})/, "\\1\\3\n") 
         end
                 
+        # @return [String] indents +text+ by +len+ characters.
         def indent(text, len = 4)
           text.gsub(/^/, ' ' * len)
         end
         
+        # @return [String] aligns a title to the right
         def title_align_right(text, col = 72)
           align_right(text, '-', col)
         end
         
+        # @return [String] aligns text to the right
         def align_right(text, spacer = ' ', col = 72)
+          text = text[0, col - 4] + '...' if (col - 1 - text.length) < 0
           spacer * (col - 1 - text.length) + " " + text
         end
         
+        # @return [String] returns a horizontal rule for output
         def hr(col = 72, sep = "-")
           sep * col
         end
         
+        # @return [String] the formatted signature for a method
         def signature(meth)
           # use first overload tag if it has a return type and method itself does not
           if !meth.tag(:return) && meth.tag(:overload) && meth.tag(:overload).tag(:return)
@@ -44,7 +53,7 @@ module YARD
 
           type = options[:default_return] || ""
           if meth.tag(:return) && meth.tag(:return).types
-            types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten
+            types = meth.tags(:return).map {|t| t.types ? t.types : [] }.flatten.uniq
             first = types.first
             if types.size == 2 && types.last == 'nil'
               type = first + '?'

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

@@ -1,6 +1,10 @@
 module YARD
   module Templates::Helpers
+    # Helpers for UML template format
     module UMLHelper
+      # Official UML visibility prefix syntax for an object given its visibility
+      # @param [CodeObjects::Base] object the object to retrieve visibility for
+      # @return [String] the UML visibility prefix
       def uml_visibility(object)
         case object.visibility
         when :public;    '+'
@@ -9,14 +13,23 @@ module YARD
         end
       end
       
+      # Formats the path of an object for Graphviz syntax
+      # @param [CodeObjects::Base] object an object to format the path of
+      # @return [String] the encoded path
       def format_path(object)
         object.path.gsub('::', '_')
       end
       
+      # Encodes text in escaped Graphviz syntax
+      # @param [String] text text to encode
+      # @return [String] the encoded text
       def h(text)
         text.to_s.gsub(/(\W)/, '\\\\\1')
       end
       
+      # Tidies data by formatting and indenting text
+      # @param [String] data pre-formatted text
+      # @return [String] tidied text.
       def tidy(data)
         indent = 0
         data.split(/\n/).map do |line|

data/lib/yard/templates/section.rb

@@ -0,0 +1,106 @@
+module YARD
+  module Templates
+    # Abstracts the structure for a section and its subsections into an ordered
+    # list of sections and subsections.
+    # @since 0.6.0
+    class Section < Array
+      attr_accessor :name
+      
+      def initialize(name, *args)
+        self.name = name
+        replace(parse_sections(args))
+      end
+      
+      def dup
+        obj = super
+        obj.name = name
+        obj
+      end
+      
+      def [](*args)
+        if args.first.is_a?(Range) || args.size > 1
+          obj = super(*args)
+          obj.name = name
+          return obj
+        elsif args.first.is_a?(Integer)
+          return super(*args)
+        end
+        find {|o| o.name == args.first }
+      end
+      
+      def eql?(other)
+        super(other) && name == other.name
+      end
+      
+      def ==(other)
+        case other
+        when Section
+          eql?(other)
+        when Array
+          to_a == other
+        else
+          name == other
+        end
+      end
+      
+      def push(*args)
+        super(*parse_sections(args))
+      end
+      alias << push
+      
+      def unshift(*args)
+        super(*parse_sections(args))
+      end
+      
+      def inspect
+        n = name.respond_to?(:path) ? "T('#{name.path}')" : name.inspect
+        subsects = empty? ? "" : ", subsections=#{super}"
+        "Section(#{n}#{subsects})"
+      end
+      
+      def place(*args)
+        super(*parse_sections(args))
+      end
+      
+      def to_a
+        list = [name]
+        unless empty?
+          subsects = []
+          each {|s| subsects += s.to_a }
+          list << subsects
+        end
+        list
+      end
+      
+      def any(item)
+        find do |section|
+          return section if section == item
+          return section.any(item) unless section.empty?
+        end
+        nil
+      end
+      
+      private
+      
+      def parse_sections(args)
+        if args.size == 1 && args.first.is_a?(Array) && !args.first.is_a?(Section)
+          args = args.first
+        end
+        sections = []
+        args.each_with_index do |name, index|
+          case name
+          when Section; sections << name
+          when Array;   next
+          else
+            subsections = args[index + 1].is_a?(Array) ? args[index + 1] : []
+            if subsections.is_a?(Section)
+              subsections = [] 
+            end
+            sections << Section.new(name, subsections)
+          end
+        end
+        sections
+      end
+    end
+  end
+end

data/lib/yard/templates/template.rb

@@ -4,7 +4,7 @@ module YARD
   module Templates
     module Template
       attr_accessor :class, :section
-      attr_reader :options, :subsections
+      attr_reader :options
       
       class << self
         # @return [Array<Module>] a list of modules to be automatically included
@@ -94,6 +94,13 @@ module YARD
         def T(*path)
           Engine.template(*path)
         end
+        
+        # Alias for creating a {Section} with arguments
+        # @see Section#initialize
+        # @since 0.6.0
+        def S(*args)
+          Section.new(*args)
+        end
       
         private
 
@@ -166,7 +173,7 @@ module YARD
       #   templates, they will have {Template::ClassMethods#run} called on them. 
       #   Any subsections can be yielded to using yield or {#yieldall}
       def sections(*args)
-        @sections.replace(args) if args.size > 0
+        @sections = Section.new(nil, *args) if args.size > 0
         @sections
       end
       
@@ -177,6 +184,7 @@ module YARD
       #   def init
       #     sections :section1, :section2, [:subsection1, :etc]
       #   end
+      # @see #sections
       def init
       end
     
@@ -184,7 +192,7 @@ module YARD
       # not be called directly. Instead, call the class method {ClassMethods#run}
       # 
       # @param [Hash, nil] opts any extra options to apply to sections
-      # @param [Array] sects a list of sections to render
+      # @param [Section, Array] sects a section list of sections to render
       # @param [Fixnum] start_at the index in the section list to start from
       # @param [Boolean] break_first if true, renders only the first section
       # @yield [opts] calls for the subsections to be rendered
@@ -194,20 +202,16 @@ module YARD
         out = ""
         return out if sects.nil?
         sects = sects[start_at..-1] if start_at > 0
+        sects = Section.new(nil, sects) unless sects.is_a?(Section)
         add_options(opts) do
-          sects.each_with_index do |s, index|
-            next if Array === s
+          sects.each do |s|
             self.section = s
-            self.subsections = sects[index + 1]
             subsection_index = 0
             value = render_section(section) do |*args|
               value = with_section do
-                run(args.first, subsections, subsection_index, true, &block)
+                run(args.first, section, subsection_index, true, &block)
               end
               subsection_index += 1 
-              subsection_index += 1 until subsections.nil? ||
-                subsections[subsection_index].nil? || 
-                !subsections[subsection_index].is_a?(Array)
               value
             end
             out << (value || "")
@@ -221,7 +225,7 @@ module YARD
       # 
       # @param [Hash] opts extra options to be applied to subsections
       def yieldall(opts = nil, &block)
-        with_section { run(opts, subsections, &block) }
+        with_section { run(opts, section, &block) }
       end
     
       # @param [String, Symbol] section the section name
@@ -285,7 +289,7 @@ module YARD
       end
       
       def inspect
-        "Template(#{self.class.path}) [section=#{section}]"
+        "Template(#{self.class.path}) [section=#{section.name}]"
       end
     
       protected
@@ -302,13 +306,10 @@ module YARD
     
       private
     
-      def subsections=(value)
-        @subsections = Array === value ? value : nil
-      end
-    
       def render_section(section, &block)
+        section = section.name if section.is_a?(Section)
         case section
-        when String, Symbol
+        when Section, String, Symbol
           if respond_to?(section)
             send(section, &block) 
           else
@@ -354,9 +355,9 @@ module YARD
       end
       
       def with_section(&block)
-        s1, s2 = section, subsections
+        sect = section
         value = yield
-        self.section, self.subsections = s1, s2
+        self.section = sect
         value
       end
     end

data/lib/yard/verifier.rb

@@ -32,6 +32,7 @@ module YARD
   #   Verifier.new('@return && @param && @yield')
   class Verifier
     # @return [Array<String>] a list of all expressions the verifier checks for
+    # @since 0.5.6
     attr_reader :expressions
     
     def expressions=(value)
@@ -52,6 +53,7 @@ module YARD
     # 
     # @param [Array<String>] expressions a list of expressions
     # @return [void]
+    # @since 0.5.6
     def add_expressions(*expressions)
       self.expressions += expressions.flatten
     end
@@ -77,6 +79,16 @@ module YARD
       retval
     end
     
+    # Runs a list of objects against the verifier 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.
+    def run(list)
+      list.reject {|item| call(item).is_a?(FalseClass) }
+    end
+    
     protected
     
     # @return [CodeObjects::Base] the current object being tested
@@ -85,6 +97,9 @@ module YARD
     
     private
     
+    # @private
+    NILCLASS_METHODS = [:type, :method_missing]
+    
     # Modifies nil to not throw NoMethodErrors. This allows
     # syntax like object.tag(:return).text to work if the #tag
     # call returns nil, which means users don't need to perform
@@ -92,13 +107,17 @@ module YARD
     # 
     # @return [void] 
     def modify_nilclass
-      NilClass.send(:define_method, :method_missing) {|*args| }
+      NILCLASS_METHODS.each do |meth|
+        NilClass.send(:define_method, meth) {|*args| }
+      end
     end
     
     # Returns the state of NilClass back to normal
     # @return [void] 
     def unmodify_nilclass
-      NilClass.send(:undef_method, :method_missing)
+      NILCLASS_METHODS.each do |meth|
+        NilClass.send(:undef_method, meth)
+      end
     end
     
     # Creates the +__execute+ method by evaluating the expressions

data/spec/cli/command_parser_spec.rb

@@ -0,0 +1,43 @@
+require File.dirname(__FILE__) + '/../spec_helper'
+
+describe YARD::CLI::CommandParser do
+  describe '#run' do
+    before do
+      @cmd = CLI::CommandParser.new
+    end
+    
+    it "should show help if --help is provided" do
+      command = mock(:command)
+      command.should_receive(:run).with('--help')
+      CLI::CommandParser.commands[:foo] = command
+      @cmd.class.default_command = :foo
+      @cmd.run *%w( foo --help )
+    end
+    
+    it "should use default command if first argument is a switch" do
+      command = mock(:command)
+      command.should_receive(:run).with('--a', 'b', 'c')
+      CLI::CommandParser.commands[:foo] = command
+      @cmd.class.default_command = :foo
+      @cmd.run *%w( --a b c )
+    end
+    
+    it "should use default command if no arguments are provided" do
+      command = mock(:command)
+      command.should_receive(:run)
+      CLI::CommandParser.commands[:foo] = command
+      @cmd.class.default_command = :foo
+      @cmd.run
+    end
+    
+    it "should list commands if command is not found" do
+      @cmd.should_receive(:list_commands)
+      @cmd.run *%w( unknown_command --args )
+    end
+
+    it "should list commands if --help is provided as sole argument" do
+      @cmd.should_receive(:list_commands)
+      @cmd.run *%w( --help )
+    end
+  end
+end