yard 0.6.8 → 0.7.0

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

@@ -2,7 +2,8 @@
 class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy::Base
   include YARD::Handlers::Ruby::StructHandlerMethods
   handles TkCLASS
-  
+  namespace_only
+
   process do
     if statement.tokens.to_s =~ /^class\s+(#{NAMESPACEMATCH})\s*(?:<\s*(.+)|\Z)/m
       classname = $1
@@ -25,14 +26,14 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
         create_attributes(klass, members_from_tags(klass))
       end
       parse_block(:namespace => klass)
-       
+
       if undocsuper
         raise YARD::Parser::UndocumentableError, 'superclass (class was added without superclass)'
       end
     elsif statement.tokens.to_s =~ /^class\s*<<\s*([\w\:]+)/
       classname = $1
       proxy = Proxy.new(namespace, classname)
-      
+
       # Allow constants to reference class names
       if ConstantObject === proxy
         if proxy.value =~ /\A#{NAMESPACEMATCH}\Z/
@@ -41,10 +42,10 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
           raise YARD::Parser::UndocumentableError, "constant class reference '#{classname}'"
         end
       end
-      
+
       if classname == "self"
         parse_block(:namespace => namespace, :scope => :class)
-      elsif classname[0,1] =~ /[A-Z]/ 
+      elsif classname[0,1] =~ /[A-Z]/
         register ClassObject.new(namespace, classname) if Proxy === proxy
         parse_block(:namespace => proxy, :scope => :class)
       else
@@ -54,9 +55,9 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
       raise YARD::Parser::UndocumentableError, "class: #{statement.tokens}"
     end
   end
-  
+
   private
-  
+
   # Extracts the parameter list from the Struct.new declaration and returns it
   # formatted as a list of member names. Expects the user will have used symbols
   # to define the struct member names
@@ -67,7 +68,7 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
     paramstring = superstring.match(/\A(O?Struct)\.new\((.*?)\)/)[2]
     paramstring.split(",").select {|x| x.strip[0,1] == ":"}.map {|x| x.strip[1..-1] } # the 1..-1 chops the leading :
   end
-  
+
   def create_struct_superclass(superclass, superclass_def)
     return if superclass == "Struct"
     the_super = register ClassObject.new(P("Struct"), superclass[8..-1]) do |o|
@@ -76,7 +77,7 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
     parse_struct_subclass(the_super, superclass_def)
     the_super
   end
-  
+
   def struct_superclass_name(superclass)
     if match = superclass.match(/\A(Struct)\.new\((.*?)\)/)
       paramstring = match[2].split(",")
@@ -87,17 +88,17 @@ class YARD::Handlers::Ruby::Legacy::ClassHandler < YARD::Handlers::Ruby::Legacy:
     end
     "Struct"
   end
-  
+
   def parse_struct_subclass(klass, superclass_def)
     # Bounce if there's no parens
     return unless superclass_def =~ /O?Struct\.new\((.*?)\)/
     members = extract_parameters(superclass_def)
     create_attributes(klass, members)
   end
-  
+
   def parse_superclass(superclass)
     case superclass
-    when /\A(#{NAMESPACEMATCH})(?:\s|\Z)/, 
+    when /\A(#{NAMESPACEMATCH})(?:\s|\Z)/,
          /\A(Struct|OStruct)\.new/,
          /\ADelegateClass\((.+?)\)\s*\Z/,
          /\A(#{NAMESPACEMATCH})\(/

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

@@ -2,14 +2,11 @@
 class YARD::Handlers::Ruby::Legacy::ClassVariableHandler < YARD::Handlers::Ruby::Legacy::Base
   HANDLER_MATCH = /\A@@\w+\s*=\s*/m
   handles HANDLER_MATCH
-  
+  namespace_only
+
   process do
-    # Don't document @@cvars if they're set in second class objects (methods) because
-    # they're not "static" when executed from a method
-    return unless owner.is_a? NamespaceObject
-    
     name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
-    register ClassVariableObject.new(namespace, name) do |o| 
+    register ClassVariableObject.new(namespace, name) do |o|
       o.source = statement
       o.value = value.strip
     end

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

@@ -3,12 +3,9 @@ class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Lega
   include YARD::Handlers::Ruby::StructHandlerMethods
   HANDLER_MATCH = /\A[A-Z]\w*\s*=[^=]\s*/m
   handles HANDLER_MATCH
-  
+  namespace_only
+
   process do
-    # Don't document CONSTANTS if they're set in second class objects (methods) because
-    # they're not "static" when executed from a method
-    return unless owner.is_a? NamespaceObject
-    
     name, value = *statement.tokens.to_s.split(/\s*=\s*/, 2)
     if value =~ /\A\s*Struct.new(?:\s*\(?|\b)/
       process_structclass(name, $')
@@ -16,14 +13,14 @@ class YARD::Handlers::Ruby::Legacy::ConstantHandler < YARD::Handlers::Ruby::Lega
       register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value.strip }
     end
   end
-  
+
   private
-  
+
   def process_structclass(classname, parameters)
     klass = create_class(classname, P(:Struct))
     create_attributes(klass, extract_parameters(parameters))
   end
-  
+
   def extract_parameters(parameters)
     members = tokval_list(YARD::Parser::Ruby::Legacy::TokenList.new(parameters), TkSYMBOL)
     members.map {|m| m.to_s }

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

@@ -1,7 +1,7 @@
 # (see Ruby::ExceptionHandler)
 class YARD::Handlers::Ruby::Legacy::ExceptionHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Araise(\s|\()/
-  
+
   process do
     return unless owner.is_a?(MethodObject) # Only methods yield
     return if owner.has_tag?(:raise)

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

@@ -1,6 +1,7 @@
 # (see Ruby::ExtendHandler)
 class YARD::Handlers::Ruby::Legacy::ExtendHandler < YARD::Handlers::Ruby::Legacy::MixinHandler
   handles /\Aextend(\s|\()/
+  namespace_only
 
   def scope; :class end
 

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

@@ -0,0 +1,40 @@
+module YARD
+  module Handlers
+    module Ruby
+      module Legacy
+        # (see Ruby::MacroHandler)
+        class MacroHandler < Base
+          include CodeObjects
+          include MacroHandlerMethods
+          handles TkIDENTIFIER
+          namespace_only
+
+          process do
+            return if namespace == Registry.root
+            globals.__attached_macros ||= {}
+            if !globals.__attached_macros[caller_method]
+              return if Ruby::MacroHandler::IGNORE_METHODS[caller_method]
+              return if !statement.comments || statement.comments.empty?
+            end
+
+            comments = statement.comments ? statement.comments.join("\n") : ""
+            @macro, @docstring = nil, Docstring.new(comments)
+            find_or_create_macro(@docstring)
+            return if !@macro && !statement.comments_hash_flag && @docstring.tags.size == 0
+            @docstring = expanded_macro_or_docstring
+            name = method_name
+            raise UndocumentableError, "method, missing name" if name.nil? || name.empty?
+            tmp_scope = sanitize_scope
+            tmp_vis = sanitize_visibility
+            object = MethodObject.new(namespace, name, tmp_scope)
+            register(object)
+            object.visibility = tmp_vis
+            object.dynamic = true
+            object.signature = method_signature
+            create_attribute_data(object)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,7 +1,7 @@
 # (see Ruby::MethodHandler)
 class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkDEF
-    
+
   process do
     nobj = namespace
     mscope = scope
@@ -23,27 +23,27 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
       end
       nobj = P(namespace, prefix) unless prefix == "self"
     end
-    
+
     nobj = P(namespace, nobj.value) while nobj.type == :constant
-    obj = register MethodObject.new(nobj, meth, mscope) do |o| 
-      o.visibility = visibility 
+    obj = register MethodObject.new(nobj, meth, mscope) do |o|
+      o.visibility = visibility
       o.source = statement
       o.explicit = true
       o.parameters = args
     end
-    
+
     # delete any aliases referencing old method
     nobj.aliases.each do |aobj, name|
       next unless name == obj.name
       nobj.aliases.delete(aobj)
     end if nobj.is_a?(NamespaceObject)
-    
+
     if mscope == :instance && meth == "initialize"
       unless obj.has_tag?(:return)
-        obj.docstring.add_tag(YARD::Tags::Tag.new(:return, 
+        obj.docstring.add_tag(YARD::Tags::Tag.new(:return,
           "a new instance of #{namespace.name}", namespace.name.to_s))
       end
-    elsif mscope == :class && obj.docstring.blank? && %w(inherited included 
+    elsif mscope == :class && obj.docstring.blank? && %w(inherited included
         extended method_added method_removed method_undefined).include?(meth)
       obj.docstring.add_tag(YARD::Tags::Tag.new(:private, nil))
     elsif meth.to_s =~ /\?$/
@@ -53,7 +53,7 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
         obj.docstring.add_tag(YARD::Tags::Tag.new(:return, "", "Boolean"))
       end
     end
-    
+
     if obj.has_tag?(:option)
       # create the options parameter if its missing
       obj.tags(:option).each do |option|
@@ -64,7 +64,7 @@ class YARD::Handlers::Ruby::Legacy::MethodHandler < YARD::Handlers::Ruby::Legacy
         end
       end
     end
-    
+
     if info = obj.attr_info
       if meth.to_s =~ /=$/ # writer
         info[:write] = obj if info[:read]

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

@@ -1,7 +1,8 @@
 # (see Ruby::MixinHandler)
 class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\Ainclude(\s|\()/
-  
+  namespace_only
+
   process do
     errors = []
     statement.tokens[1..-1].to_s.split(/\s*,\s*/).each do |mixin|
@@ -12,7 +13,7 @@ class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy:
         errors << err.message
       end
     end
-    
+
     if errors.size > 0
       msg = errors.size == 1 ? ": #{errors[0]}" : "s: #{errors.join(", ")}"
       raise YARD::Parser::UndocumentableError, "mixin#{msg} for class #{namespace.path}"
@@ -27,7 +28,7 @@ class YARD::Handlers::Ruby::Legacy::MixinHandler < YARD::Handlers::Ruby::Legacy:
     end
 
     obj = Proxy.new(namespace, mixmatch)
-    
+
     case obj
     when Proxy
       obj.type = :module

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

@@ -1,7 +1,8 @@
 # (see Ruby::ModuleHandler)
 class YARD::Handlers::Ruby::Legacy::ModuleHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkMODULE
-  
+  namespace_only
+
   process do
     modname = statement.tokens.to_s[/^module\s+(#{NAMESPACEMATCH})/, 1]
     mod = register ModuleObject.new(namespace, modname)

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

@@ -1,16 +1,16 @@
 # (see Ruby::PrivateConstantHandler)
 class YARD::Handlers::Ruby::Legacy::PrivateConstantHandler < YARD::Handlers::Ruby::Legacy::Base
-  namespace_only
   handles /\Aprivate_constant(\s|\(|$)/
-  
+  namespace_only
+
   process do
     tokval_list(statement.tokens[2..-1], :attr, TkCONSTANT).each do |name|
       privatize_constant name
     end
   end
-  
+
   private
-  
+
   def privatize_constant(name)
     const = Proxy.new(namespace, name)
     ensure_loaded!(const)

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

@@ -1,7 +1,8 @@
 # (see Ruby::VisibilityHandler)
 class YARD::Handlers::Ruby::Legacy::VisibilityHandler < YARD::Handlers::Ruby::Legacy::Base
   handles /\A(protected|private|public)(\s|\(|$)/
-  
+  namespace_only
+
   process do
     vis = statement.tokens.first.text
     if statement.tokens.size == 1

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

@@ -1,7 +1,7 @@
 # (see Ruby::YieldHandler)
 class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy::Base
   handles TkYIELD
-  
+
   process do
     return unless owner.is_a?(MethodObject) # Only methods yield
     return if owner.has_tag? :yield         # Don't override yield tags
@@ -12,11 +12,11 @@ class YARD::Handlers::Ruby::Legacy::YieldHandler < YARD::Handlers::Ruby::Legacy:
       item = item.inspect unless item.is_a?(String)
       if item == "self"
         yieldtag.types << '_self'
-        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
+        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
           "the object that the method was called on", owner.namespace.path, '_self')
       elsif item == "super"
         yieldtag.types << '_super'
-        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam, 
+        owner.docstring.add_tag YARD::Tags::Tag.new(:yieldparam,
           "the result of the method from the superclass", nil, '_super')
       else
         yieldtag.types << item

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

@@ -0,0 +1,41 @@
+module YARD
+  module Handlers
+    module Ruby
+      # Handles a macro (dsl-style method)
+      class MacroHandler < Base
+        include CodeObjects
+        include MacroHandlerMethods
+        handles method_call
+        namespace_only
+        
+        IGNORE_METHODS = Hash[*%w(alias alias_method autoload attr attr_accessor 
+          attr_reader attr_writer extend include public private protected 
+          private_constant).map {|n| [n, true] }.flatten]
+        
+        process do
+          return if namespace == Registry.root
+          globals.__attached_macros ||= {}
+          if !globals.__attached_macros[caller_method]
+            return if IGNORE_METHODS[caller_method]
+            return if !statement.comments || statement.comments.empty?
+          end
+          
+          @macro, @docstring = nil, Docstring.new(statement.comments)
+          find_or_create_macro(@docstring)
+          return if !@macro && !statement.comments_hash_flag && @docstring.tags.size == 0
+          @docstring = expanded_macro_or_docstring
+          name = method_name
+          raise UndocumentableError, "method, missing name" if name.nil? || name.empty?
+          tmp_scope = sanitize_scope
+          tmp_vis = sanitize_visibility
+          object = MethodObject.new(namespace, name, tmp_scope)
+          register(object)
+          object.visibility = tmp_vis
+          object.dynamic = true
+          object.signature = method_signature
+          create_attribute_data(object)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,130 @@
+module YARD
+  module Handlers
+    module Ruby
+      module MacroHandlerMethods
+        include CodeObjects
+        include Parser
+        
+        def find_or_create_macro(docstring)
+          return @macro if @macro
+          return if @macro = super(docstring)
+
+          # Look for implicit macros
+          (globals.__attached_macros[caller_method] || []).each do |macro|
+            namespace.inheritance_tree.each do |obj|
+              break(@macro = macro) if obj == macro.method_object.namespace
+            end
+          end
+        end
+        
+        def expanded_macro_or_docstring
+          return @docstring unless @macro
+          all_params = ([caller_method] + call_params).compact
+          data = MacroObject.apply_macro(@macro, @docstring, all_params, statement.source)
+          Docstring.new(data)
+        end
+        
+        def expand_macro(object, macro)
+          if @docstring
+            object.docstring = @docstring
+            object.docstring.tags.each do |tag|
+              tag.object = object if tag.respond_to?(:object=)
+            end
+          else
+            super(object, macro)
+          end
+        end
+        
+        def sanitize_scope
+          tmp_scope = @docstring.tag(:scope) ? @docstring.tag(:scope).text : ''
+          %w(class instance).include?(tmp_scope) ? tmp_scope.to_sym : scope
+        end
+
+        def sanitize_visibility
+          vis = @docstring.tag(:visibility) ? @docstring.tag(:visibility).text : ''
+          %w(public protected private).include?(vis) ? vis.to_sym : visibility
+        end
+
+        def create_attribute_data(object)
+          return unless object.docstring.tag(:attribute)
+          ensure_loaded!(namespace)
+          clean_name = object.name.to_s.sub(/=$/, '')
+          namespace.attributes[object.scope][clean_name] ||= SymbolHash[:read => nil, :write => nil]
+          if attribute_readable?
+            namespace.attributes[object.scope][clean_name][:read] = object
+          end
+          if attribute_writable?
+            if object.name.to_s[-1,1] == '='
+              writer = object
+            else
+              writer = MethodObject.new(namespace, object.name.to_s + '=', object.scope)
+              register(writer)
+              writer.signature = "def #{object.name}=(value)"
+              writer.visibility = object.visibility
+              writer.dynamic = true
+            end
+            namespace.attributes[object.scope][clean_name][:write] = writer
+          end
+        end
+        
+        def method_name
+          name = nil
+          [:method, :attribute, :overload].each do |tag_name|
+            if tag = @docstring.tag(tag_name)
+              name = tag.send(tag == :overload ? :text : :name).to_s
+              if tag_name == :method && name =~ /\(|\s/
+                overload = Tags::OverloadTag.new(:overload, name)
+                @docstring.add_tag(overload)
+              end
+              break
+            end
+          end
+          name = nil if name =~ /\A\s*\Z/
+          name ||= call_params.first
+          return unless name
+          if name =~ /\A\s*([^\(; \t]+)/
+            name = $1
+          end
+          if @docstring.tag(:attribute) && !attribute_readable?
+            name = name + '='
+          end
+          name
+        end
+
+        def method_signature
+          if @docstring.tag(:method)
+            name = @docstring.tag(:method).name
+          elsif @docstring.tag(:overload)
+            name = @docstring.tag(:overload).signature
+          elsif @docstring.tag(:attribute)
+            name = @docstring.tag(:attribute).text
+            name += '=(value)' if !attribute_readable?
+          else
+            name = method_name
+          end
+          name = nil if name =~ /\A\s*\Z/
+          name ||= call_params.first
+          name =~ /^def\b/ ? name : "def #{name}"
+        end
+
+        private
+
+        def attribute_writable?
+          if @docstring.tag(:attribute) 
+            types = @docstring.tag(:attribute).types
+            return types ? types.join.include?('w') : true
+          end
+          false
+        end
+
+        def attribute_readable?
+          if @docstring.tag(:attribute) 
+            types = @docstring.tag(:attribute).types
+            return types ? (types.join =~ /(?!w)r/ ? true : false) : true
+          end
+          false
+        end
+      end
+    end
+  end
+end