yard 0.8.7.6 → 0.9.0

data/lib/yard/handlers/c/init_handler.rb

@@ -1,6 +1,6 @@
 # Handles the Init_Libname() method
 class YARD::Handlers::C::InitHandler < YARD::Handlers::C::Base
-  MATCH = %r{\A\s*(?:static\s+)?void\s+(?:[Ii]nit_)?(\w+)\s*}
+  MATCH = %r{\A\s*(?:\S+\s+)*void\s+(?:[Ii]nit_)?(\w+)\s*}
   handles MATCH
   statement_class ToplevelStatement
 

data/lib/yard/handlers/c/method_handler.rb

@@ -6,9 +6,9 @@ class YARD::Handlers::C::MethodHandler < YARD::Handlers::C::Base
                     module_function  |
                     private_method
                  )
-                 \s*\(\s*([\w\.]+),
-                   \s*"([^"]+)",
-                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?,
+                 \s*\(\s*([\w\.]+)\s*,
+                   \s*"([^"]+)"\s*,
+                   \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\(|\(\w+\))?(\w+)\)?\s*,
                    \s*(-?\w+)\s*\)}xm
   MATCH2 = %r{rb_define_global_function\s*\(
                 \s*"([^"]+)",

data/lib/yard/handlers/ruby/decorator_handler_methods.rb

@@ -0,0 +1,132 @@
+# Helper methods to assist with processing decorators.
+module YARD::Handlers::Ruby::DecoratorHandlerMethods
+
+  # @overload process_decorator(*nodes, opts = {}, &block)
+  #   Takes care of parsing method definitions passed to decorators
+  #   as parameters, as well as parsing chained decorators.
+  #
+  #   Use this in a handler's process block.
+  #
+  #   @yieldparam method [YARD::CodeObjects::MethodObject] Method being decorated.
+  #   @yieldparam node [YARD::Parser::Ruby::AstNode] AST node of the decorated method.
+  #   @yieldparam name [Symbol] Name of the decorated method.
+  #   @return [Array<Hash>] Array of hashes containing :method, :node, :name.
+  #     See yield params.
+  #
+  #   @param nodes [YARD::Parser::Ruby::AstNode] AST nodes that refer to decorated
+  #     methods, like indexes of statement.parameter. Defaults to all parameters.
+  #     Pass nil to specify zero parameters.
+  #
+  #   @option opts [:instance, :class] :scope (:instance) Scope to use for each
+  #     MethodObject.
+  #
+  #   @option opts [true, false] :transfer_docstring Set false to disable
+  #     transferring the decorator docstring to method definitions passed to the
+  #     decorator as parameters.
+  #
+  #   @option opts [true, false] :transfer_source Set false to disable
+  #     transferring the decorator source code string to method definitions
+  #     passed to the decorator as parameters.
+  #
+  #   @example Basic Usage
+  #     # Simply pass the method docs through to the method definition.
+  #     process do
+  #       process_decorator
+  #     end
+  #
+  #   @example Setting a method's visibility to private.
+  #     process do
+  #       process_decorator :scope => :class do |method|
+  #         method.visibility = :private if method.respond_to? :visibility
+  #       end
+  #     end
+  def process_decorator(*nodes, &block)
+    opts = nodes.last.is_a?(Hash) ? nodes.pop : {}
+
+    all_nodes = statement.parameters.select do |p|
+      p.is_a? YARD::Parser::Ruby::AstNode
+    end
+
+    # Parse decorator parameters (decorator chain).
+    all_nodes.each do |param|
+      parse_block param if param.call? or param.def?
+    end
+
+    selected_nodes =
+      if nodes.empty?
+        all_nodes
+      elsif (nodes.count == 1 and nodes.first == nil)
+        []
+      else
+        nodes
+      end
+
+    decorated_methods = selected_nodes.map { |param|
+      process_decorator_parameter param, opts, &block
+    }.flatten
+
+    # Store method nodes in decorator node.
+    statement.define_singleton_method :decorators do
+      decorated_methods.map { |h| h[:node] }
+    end
+
+    decorated_methods
+  end
+
+  private
+
+  def process_decorator_parameter(node, opts={}, &block)
+    scope              = opts.fetch :scope, :instance
+    transfer_docstring = opts.fetch :transfer_docstring, true
+    transfer_source    = opts.fetch :transfer_source, true
+
+    name = nil
+
+    if node.call?
+      if node.respond_to? :decorators
+        return node.decorators.map do |n|
+          process_decorator_parameter n, opts, &block
+        end
+      end
+    elsif node.def?
+      name = node.jump(:def).method_name.source
+    else
+      name = node.jump(:ident, :string_content, :const).source
+    end
+
+    method = YARD::CodeObjects::Proxy.new(
+      namespace,
+      (scope == :instance ? '#' : '.') + name.to_s,
+      :method
+    )
+
+    # Transfer source to methods passed to the helper as parameters.
+    method.source = statement.source if transfer_source and node.def?
+
+    # Tag decorator on decorated method.
+    if method.respond_to? :add_tag
+      method.add_tag YARD::Tags::Tag.new(
+        :decorator,
+        statement.jump(:command).jump(:ident).source
+      )
+    end
+
+    # Transfer decorator docstring to methods passed to the helper as parameters.
+    if transfer_docstring \
+      and node.def? \
+      and statement.docstring \
+      and method.docstring.empty?
+        tags = method.tags if method.respond_to? :tags
+        tags ||= []
+
+        method.docstring = statement.docstring
+
+        tags.each { |t| method.add_tag t }
+    end
+
+    block.call method, node, name.to_sym if block_given?
+
+    [{:method => method, :node => node, :name => name.to_sym}]
+  end
+
+end

data/lib/yard/handlers/ruby/legacy/private_class_method_handler.rb

@@ -15,7 +15,7 @@ class YARD::Handlers::Ruby::Legacy::PrivateClassMethodHandler < YARD::Handlers::
     method = Proxy.new(namespace, name)
     ensure_loaded!(method)
     method.visibility = :private
-  rescue NamespaceMissingError
+  rescue YARD::Handlers::NamespaceMissingError
     raise UndocumentableError, "private visibility set on unrecognized method: #{name}"
   end
 end

data/lib/yard/handlers/ruby/private_class_method_handler.rb

@@ -1,46 +1,13 @@
-# Sets visibility of a class method
+# Sets visibility of a class method to private.
 class YARD::Handlers::Ruby::PrivateClassMethodHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::DecoratorHandlerMethods
+
   handles method_call(:private_class_method)
   namespace_only
 
   process do
-    errors = []
-    statement.parameters.each do |param|
-      next unless AstNode === param
-      begin
-        privatize_class_method(param)
-      rescue UndocumentableError => err
-        errors << err.message
-      end
-    end
-    if errors.size > 0
-      msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
-      raise UndocumentableError, "private class_method#{msg} for #{namespace.path}"
-    end
-  end
-
-  private
-
-  def privatize_class_method(node)
-    if node.literal?
-      method = Proxy.new(namespace, node[0][0][0], :method)
-      
-      # Proxy will not have a #visibility method when handling inherited class methods
-      # like :new, yet "private_class_method :new" is valid Ruby syntax. Therefore
-      # if Proxy doesn't respond to #visibility, the object should be skipped.
-      # 
-      # However, it is important to note that classes can be reopened, and
-      # private_class_method can be called inside these reopened classes.
-      # Therefore when encountering private_class_method, all of the files need
-      # to be parsed before checking if Proxy responds to #visibility. If this
-      # is not done, it is possible that class methods may be incorrectly marked
-      # public/private.
-      parser.parse_remaining_files
-      method.visibility = :private if method.respond_to? :visibility
-    else
-      raise UndocumentableError, "invalid argument to private_class_method: #{node.source}"
+    process_decorator :scope => :class do |method|
+      method.visibility = :private if method.respond_to? :visibility=
     end
-  rescue NamespaceMissingError
-    raise UndocumentableError, "private visibility set on unrecognized method: #{node[0]}"
   end
-end
+end

data/lib/yard/handlers/ruby/private_constant_handler.rb

@@ -1,36 +1,42 @@
 # Sets visibility of a constant (class, module, const)
-class YARD::Handlers::Ruby::PrivateConstantHandler < YARD::Handlers::Ruby::Base
-  handles method_call(:private_constant)
-  namespace_only
+module YARD
+  module Handlers
+    module Ruby
+      class PrivateConstantHandler < YARD::Handlers::Ruby::Base
+        handles method_call(:private_constant)
+        namespace_only
 
-  process do
-    errors = []
-    statement.parameters.each do |param|
-      next unless AstNode === param
-      begin
-        privatize_constant(param)
-      rescue UndocumentableError => err
-        errors << err.message
-      end
-    end
-    if errors.size > 0
-      msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
-      raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
-    end
-  end
+        process do
+          errors = []
+          statement.parameters.each do |param|
+            next unless AstNode === param
+            begin
+              privatize_constant(param)
+            rescue UndocumentableError => err
+              errors << err.message
+            end
+          end
+          if errors.size > 0
+            msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
+            raise UndocumentableError, "private constant#{msg} for #{namespace.path}"
+          end
+        end
 
-  private
+        private
 
-  def privatize_constant(node)
-    if node.literal? || (node.type == :var_ref && node[0].type == :const)
-      node = node.jump(:tstring_content, :const)
-      const = Proxy.new(namespace, node[0])
-      ensure_loaded!(const)
-      const.visibility = :private
-    else
-      raise UndocumentableError, "invalid argument to private_constant: #{node.source}"
+        def privatize_constant(node)
+          if node.literal? || (node.type == :var_ref && node[0].type == :const)
+            node = node.jump(:tstring_content, :const)
+            const = Proxy.new(namespace, node[0])
+            ensure_loaded!(const)
+            const.visibility = :private
+          else
+            raise UndocumentableError, "invalid argument to private_constant: #{node.source}"
+          end
+        rescue NamespaceMissingError
+          raise UndocumentableError, "private visibility set on unrecognized constant: #{node[0]}"
+        end
+      end
     end
-  rescue NamespaceMissingError
-    raise UndocumentableError, "private visibility set on unrecognized constant: #{node[0]}"
   end
-end
+end

data/lib/yard/handlers/ruby/public_class_method_handler.rb

@@ -0,0 +1,13 @@
+# Sets visibility of a class method to public.
+class YARD::Handlers::Ruby::PublicClassMethodHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::DecoratorHandlerMethods
+
+  handles method_call(:public_class_method)
+  namespace_only
+
+  process do
+    process_decorator :scope => :class do |method|
+      method.visibility = :public if method.respond_to? :visibility
+    end
+  end
+end

data/lib/yard/handlers/ruby/struct_handler_methods.rb

@@ -133,6 +133,7 @@ module YARD::Handlers::Ruby::StructHandlerMethods
   def create_attributes(klass, members)
     # For each parameter, add reader and writers
     members.each do |member|
+      next if klass.attributes[:instance][member]
       klass.attributes[:instance][member] = SymbolHash[:read => nil, :write => nil]
       create_writer klass, member if create_member_method?(klass, member, :write)
       create_reader klass, member if create_member_method?(klass, member, :read)

data/lib/yard/handlers/ruby/visibility_handler.rb

@@ -1,5 +1,7 @@
 # Handles 'private', 'protected', and 'public' calls.
 class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
+  include YARD::Handlers::Ruby::DecoratorHandlerMethods
+
   handles method_call(:private)
   handles method_call(:protected)
   handles method_call(:public)
@@ -11,14 +13,9 @@ class YARD::Handlers::Ruby::VisibilityHandler < YARD::Handlers::Ruby::Base
     when :var_ref, :vcall
       self.visibility = ident.first.to_sym
     when :fcall, :command
-      statement[1].traverse do |node|
-        case node.type
-        when :symbol; source = node.first.source
-        when :string_content; source = node.source
-        else next
-        end
-        MethodObject.new(namespace, source, scope) {|o| o.visibility = ident.first }
+      process_decorator do |method|
+        method.visibility = ident.first if method.respond_to? :visibility=
       end
     end
   end
-end
+end

data/lib/yard/logging.rb

@@ -164,6 +164,7 @@ module YARD
     def enter_level(new_level = level, &block)
       old_level, self.level = level, new_level
       yield
+    ensure
       self.level = old_level
     end
 

data/lib/yard/parser/ruby/ruby_parser.rb

@@ -219,7 +219,7 @@ module YARD
           node.line_range = Range.new(lstart, lineno)
           if node.respond_to?(:block)
             sr, lr = node.block.source_range, node.block.line_range
-            node.block.source_range = Range.new(sr.first, @tokens.last[2][1])
+            node.block.source_range = Range.new(sr.first, @tokens.last[2][1]-1)
             node.block.line_range = Range.new(lr.first, @tokens.last[2][0])
           end
           node
@@ -634,4 +634,4 @@ module YARD
       end if defined?(::Ripper)
     end
   end
-end
+end

data/lib/yard/parser/source_parser.rb

@@ -63,6 +63,10 @@ module YARD
       SHEBANG_LINE  = /\A\s*#!\S+/
       ENCODING_LINE = /\A(?:\s*#*!.*\r?\n)?\s*(?:#+|\/\*+|\/\/+).*coding\s*[:=]{1,2}\s*([a-z\d_\-]+)/i
 
+      # The default glob of files to be parsed.
+      # @since 0.9.0
+      DEFAULT_PATH_GLOB = ["{lib,app}/**/*.rb", "ext/**/*.{c,cc,cxx,cpp}"]
+
       # Byte order marks for various encodings
       # @since 0.7.0
       ENCODING_BYTE_ORDER_MARKS = {
@@ -90,7 +94,7 @@ module YARD
         # @param [Fixnum] level the logger level to use during parsing. See
         #   {YARD::Logger}
         # @return [void]
-        def parse(paths = ["{lib,app}/**/*.rb", "ext/**/*.c"], excluded = [], level = log.level)
+        def parse(paths = DEFAULT_PATH_GLOB, excluded = [], level = log.level)
           log.debug("Parsing #{paths.inspect} with `#{parser_type}` parser")
           excluded = excluded.map do |path|
             case path
@@ -99,7 +103,7 @@ module YARD
             end
           end
           files = [paths].flatten.
-            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c}" : p }.
+            map {|p| File.directory?(p) ? "#{p}/**/*.{rb,c,cc,cxx,cpp}" : p }.
             map {|p| p.include?("*") ? Dir[p].sort_by {|f| f.length } : p }.flatten.
             reject {|p| !File.file?(p) || excluded.any? {|re| p =~ re } }
 
@@ -147,16 +151,12 @@ module YARD
         # @return [Hash{Symbol=>Object}] a list of registered parser types
         # @private
         # @since 0.5.6
-        attr_reader :parser_types
-        undef parser_types
         def parser_types; @@parser_types ||= {} end
         def parser_types=(value) @@parser_types = value end
 
         # @return [Hash] a list of registered parser type extensions
         # @private
         # @since 0.5.6
-        attr_reader :parser_type_extensions
-        undef parser_type_extensions
         def parser_type_extensions; @@parser_type_extensions ||= {} end
         def parser_type_extensions=(value) @@parser_type_extensions = value end
 

data/lib/yard/rake/yardoc_task.rb

@@ -66,12 +66,12 @@ module YARD
       # Defines the rake task
       # @return [void]
       def define
-        desc "Generate YARD Documentation" unless ::Rake.application.last_comment
+        desc "Generate YARD Documentation" unless ::Rake.application.last_description
         task(name) do
           before.call if before.is_a?(Proc)
           yardoc = YARD::CLI::Yardoc.new
           yardoc.options[:verifier] = verifier if verifier
-          yardoc.run *(options + files)
+          yardoc.run(*(options + files))
           YARD::CLI::Stats.run(*(stats_options + ['--use-cache'])) unless stats_options.empty?
           after.call if after.is_a?(Proc)
         end

data/lib/yard/serializers/file_system_serializer.rb

@@ -26,6 +26,7 @@ module YARD
       #   path filename. If this is set to the empty string, no extension is used.
       def initialize(opts = {})
         super
+        @name_map = nil
         @basepath = (options[:basepath] || 'doc').to_s
         @extension = (options.has_key?(:extension) ? options[:extension] : 'html').to_s
       end
@@ -51,7 +52,7 @@ module YARD
         if object.is_a?(CodeObjects::ExtraFileObject)
           fspath = ['file.' + object.name + (extension.empty? ? '' : ".#{extension}")]
         else
-          objname = object != YARD::Registry.root ? object.name.to_s : "top-level-namespace"
+          objname = object != YARD::Registry.root ? mapped_name(object) : "top-level-namespace"
           objname += '_' + object.scope.to_s[0,1] if object.is_a?(CodeObjects::MethodObject)
           fspath = [objname + (extension.empty? ? '' : ".#{extension}")]
           if object.namespace && object.namespace.path != ""
@@ -72,6 +73,37 @@ module YARD
 
       private
 
+      # Builds a filename mapping from object paths to filesystem path names.
+      # Needed to handle case sensitive YARD objects mapped into a case
+      # insensitive filesystem. Uses with {#mapped_name} to determine the
+      # mapping name for a given object.
+      #
+      # @note In order to use filesystem name mapping, you must initialize
+      #   the serializer object after preparing the {YARD::Registry}.
+      def build_filename_map
+        @name_map = {}
+        YARD::Registry.all.each do |object|
+          lpath = nil
+          if object.parent && object.parent.type != :root
+            lpath = object.parent.path + "::" + object.name.to_s.downcase
+          else
+            lpath = object.path.downcase
+          end
+
+          @name_map[lpath] ||= {}
+          size = @name_map[lpath].size
+          name = "#{object.name}#{size > 0 ? "_" * size : ""}"
+          @name_map[lpath][object.name] = name
+        end
+      end
+
+      # @return [String] the filesystem mapped name of a given object.
+      def mapped_name(object)
+        build_filename_map if !@name_map
+        map = @name_map[object.path.downcase]
+        return map && map[object.name] ? map[object.name] : object.name.to_s
+      end
+
       # Remove special chars from filenames.
       # Windows disallows \ / : * ? " < > | but we will just remove any
       # non alphanumeric (plus period, underscore and dash).