yard 0.2.3.5 → 0.4.0

data/lib/yard/code_objects/method_object.rb

@@ -1,7 +1,36 @@
 module YARD::CodeObjects
+  # Represents a Ruby method in source
   class MethodObject < Base
-    attr_accessor :visibility, :scope, :explicit, :parameters
+    # The visibility of the method (+:public:+, +:protected+, +:private+)
+    # 
+    # @return [Symbol] the method visibility
+    attr_accessor :visibility
     
+    # The scope of the method (+:class+ or +:instance+)
+    # 
+    # @return [Symbol] the scope
+    attr_accessor :scope
+    
+    # Whether the object is explicitly defined in source or whether it was
+    # inferred by a handler. For instance, attribute methods are generally
+    # inferred and therefore not explicitly defined in source. 
+    # 
+    # @return [Boolean] whether the object is explicitly defined in source.
+    attr_accessor :explicit
+    
+    # Returns the list of parameters parsed out of the method signature
+    # with their default values.
+    # 
+    # @return [Array<Array(String, String)>] a list of parameter names followed
+    #   by their default values (or nil)
+    attr_accessor :parameters
+    
+    # Creates a new method object in +namespace+ with +name+ and an instance
+    # or class +scope+
+    # 
+    # @param [NamespaceObject] namespace the namespace
+    # @param [String, Symbol] name the method name
+    # @param [Symbol] scope +:instance+ or +:class+
     def initialize(namespace, name, scope = :instance) 
       self.visibility = :public
       self.scope = scope
@@ -10,6 +39,8 @@ module YARD::CodeObjects
       super
     end
     
+    # Changes the scope of an object from :instance or :class
+    # @param [Symbol] v the new scope
     def scope=(v) 
       reregister = @scope ? true : false
       YARD::Registry.delete(self) if reregister
@@ -17,20 +48,31 @@ module YARD::CodeObjects
       YARD::Registry.register(self) if reregister
     end
     
+    # Sets the visibility
+    # @param [Symbol] v the new visibility (:public, :private, or :protected)
     def visibility=(v) @visibility = v.to_sym end
       
+    # Tests if the object is defined as an attribute in the namespace
+    # @return [Boolean] whether the object is an attribute
     def is_attribute?
       namespace.attributes[scope].has_key? name.to_s.gsub(/=$/, '')
     end
       
+    # Tests if the object is defined as an alias of another method
+    # @return [Boolean] whether the object is an alias
     def is_alias?
       namespace.aliases.has_key? self
     end
     
+    # Tests boolean {#explicit} value.
+    # 
+    # @return [Boolean] whether the method is explicitly defined in source
     def is_explicit?
       explicit ? true : false
     end
     
+    # Returns all alias names of the object
+    # @return [Array<Symbol>] the alias names
     def aliases
       list = []
       namespace.aliases.each do |o, aname| 
@@ -39,6 +81,9 @@ module YARD::CodeObjects
       list
     end
     
+    # Override path handling for instance methods in the root namespace
+    # (they should still have a separator as a prefix).
+    # @return [String] the path of a method
     def path
       if !namespace || namespace.path == "" 
         sep + super
@@ -47,12 +92,25 @@ module YARD::CodeObjects
       end
     end
     
+    # Returns the name of the object.
+    # 
+    # @example The name of an instance method (with prefix)
+    #   an_instance_method.name(true) # => "#mymethod"
+    # @example The name of a class method (with prefix)
+    #   a_class_method.name(true) # => "mymethod"
+    # @param [Boolean] prefix whether or not to show the prefix
+    # @return [String] returns {#sep} + +name+ for an instance method if 
+    #   prefix is true
+    # @return [Symbol] the name without {#sep} if prefix is set to false
     def name(prefix = false)
-      ((prefix ? (sep == ISEP ? sep : "") : "") + super().to_s).to_sym
+      prefix ? (sep == ISEP ? "#{sep}#{super}" : super.to_s) : super
     end
     
     protected
     
+    # Override separator to differentiate between class and instance
+    # methods.
+    # @return [String] "#" for an instance method, "." for class
     def sep
       if scope == :class
         namespace && namespace != YARD::Registry.root ? CSEP : NSEP

data/lib/yard/code_objects/module_object.rb

@@ -1,5 +1,11 @@
 module YARD::CodeObjects
+  # Represents a Ruby module.
   class ModuleObject < NamespaceObject
+    # Returns the inheritance tree of mixins.
+    # 
+    # @param [Boolean] include_mods if true, will include mixed in
+    #   modules (which is likely what is wanted).
+    # @return [Array<NamespaceObject>] a list of namespace objects
     def inheritance_tree(include_mods = false)
       return [self] unless include_mods
       [self] + mixins(:instance).map do |m|

data/lib/yard/code_objects/namespace_object.rb

@@ -1,8 +1,54 @@
 module YARD::CodeObjects
+  # A "namespace" is any object that can store other objects within itself.
+  # The two main Ruby objects that can act as namespaces are modules 
+  # ({ModuleObject}) and classes ({ClassObject}).
   class NamespaceObject < Base
-    attr_reader :children, :cvars, :meths, :constants, :attributes, :aliases
-    attr_reader :class_mixins, :instance_mixins
+    attr_reader :constants, :meths, :cvars, :mixins, :child
+    attr_reader :class_attributes, :instance_attributes
+    attr_reader :included_constants, :included_meths
+
+    # The list of objects defined in this namespace
+    # @return [Array<Base>] a list of objects
+    attr_reader :children
+
+    # A hash containing two keys, class and instance, each containing
+    # the attribute name with a { :read, :write } hash for the read and
+    # write objects respectively.
+    # 
+    # @example The attributes of an object
+    #   >> Registry.at('YARD::Docstring').attributes
+    #   => {
+    #         :class => { }, 
+    #         :instance => {
+    #           :ref_tags => {
+    #             :read => #<yardoc method YARD::Docstring#ref_tags>, 
+    #             :write => nil 
+    #           }, 
+    #           :object => {
+    #             :read => #<yardoc method YARD::Docstring#object>,
+    #             :write => #<yardoc method YARD::Docstring#object=> 
+    #            },
+    #            ...
+    #         }
+    #       }
+    # @return [Hash] a list of methods
+    attr_reader :attributes
+
+    # A hash containing two keys, :class and :instance, each containing
+    # a hash of objects and their alias names.
+    # @return [Hash] a list of methods
+    attr_reader :aliases
+    
+    # Class mixins
+    # @return [Array<ModuleObject>] a list of mixins
+    attr_reader :class_mixins
+    
+    # Instance mixins
+    # @return [Array<ModuleObject>] a list of mixins
+    attr_reader :instance_mixins
     
+    # Creates a new namespace object inside +namespace+ with +name+.
+    # @see Base#initialize
     def initialize(namespace, name, *args, &block)
       @children = CodeObjectList.new(self)
       @class_mixins = CodeObjectList.new(self)
@@ -12,14 +58,26 @@ module YARD::CodeObjects
       super
     end
     
+    # Only the class attributes
+    # @return [Hash] a list of method names and their read/write objects
+    # @see #attributes
     def class_attributes
       attributes[:class]
     end
     
+    # Only the instance attributes
+    # @return [Hash] a list of method names and their read/write objects
+    # @see #attributes
     def instance_attributes 
       attributes[:instance]
     end
     
+    # Looks for a child that matches the attributes specified by +opts+.
+    # 
+    # @example Finds a child by name and scope
+    #   namespace.child(:name => :to_s, :scope => :instance)
+    #   # => #<yardoc method MyClass#to_s>
+    # @return [Base, nil] the first matched child object, or nil
     def child(opts = {})
       if !opts.is_a?(Hash)
         children.find {|o| o.name == opts.to_sym }
@@ -33,6 +91,20 @@ module YARD::CodeObjects
       end
     end
     
+    # Returns all methods that match the attributes specified by +opts+. If
+    # no options are provided, returns all methods.
+    # 
+    # @example Finds all private and protected class methods
+    #   namespace.meths(:visibility => [:private, :protected], :scope => :class)
+    #   # => [#<yardoc method MyClass.privmeth>, #<yardoc method MyClass.protmeth>]
+    # @option opts [Array<Symbol>, Symbol] :visibility ([:public, :private, 
+    #   :protected]) the visibility of the methods to list. Can be an array or 
+    #   single value.
+    # @option opts [Array<Symbol>, Symbol] :scope ([:class, :instance]) the 
+    #   scope of the methods to list. Can be an array or single value.
+    # @option opts [Boolean] :included (true) whether to include mixed in 
+    #   methods in the list.
+    # @return [Array<MethodObject>] a list of method objects
     def meths(opts = {})
       opts = SymbolHash[
         :visibility => [:public, :private, :protected],
@@ -52,6 +124,18 @@ module YARD::CodeObjects
       ourmeths + (opts[:included] ? included_meths(opts) : [])
     end
     
+    # Returns methods included from any mixins that match the attributes
+    # specified by +opts+. If no options are specified, returns all included
+    # methods.
+    # 
+    # @option opts [Array<Symbol>, Symbol] :visibility ([:public, :private, 
+    #   :protected]) the visibility of the methods to list. Can be an array or 
+    #   single value.
+    # @option opts [Array<Symbol>, Symbol] :scope ([:class, :instance]) the 
+    #   scope of the methods to list. Can be an array or single value.
+    # @option opts [Boolean] :included (true) whether to include mixed in 
+    #   methods in the list.
+    # @see #meths
     def included_meths(opts = {})
       opts = SymbolHash[:scope => [:instance, :class]].update(opts)
       [opts[:scope]].flatten.map do |scope|
@@ -66,12 +150,19 @@ module YARD::CodeObjects
       end.flatten
     end
     
+    # Returns all constants in the namespace
+    # 
+    # @option opts [Boolean] :included (true) whether or not to include
+    #   mixed in constants in list
+    # @return [Array<ConstantObject>] a list of constant objects
     def constants(opts = {})
       opts = SymbolHash[:included => true].update(opts)
       consts = children.select {|o| o.is_a? ConstantObject }
       consts + (opts[:included] ? included_constants : [])
     end
     
+    # Returns constants included from any mixins
+    # @return [Array<ConstantObject>] a list of constant objects
     def included_constants
       instance_mixins.reverse.inject([]) do |list, mixin|
         if mixin.respond_to? :constants
@@ -84,10 +175,16 @@ module YARD::CodeObjects
       end
     end
     
+    # Returns class variables defined in this namespace.
+    # @return [Array<ClassVariableObject>] a list of class variable objects
     def cvars 
       children.select {|o| o.is_a? ClassVariableObject }
     end
 
+    # Returns for specific scopes. If no scopes are provided, returns all mixins.
+    # @param [Array<Symbol>] scopes a list of scopes (:class, :instance) to
+    #   return mixins for. If this is empty, all scopes will be returned.
+    # @return [Array<ModuleObject>] a list of mixins
     def mixins(*scopes)
       return class_mixins if scopes == [:class]
       return instance_mixins if scopes == [:instance]

data/lib/yard/code_objects/proxy.rb

@@ -1,14 +1,30 @@
 module YARD
   module CodeObjects
+    # A special type of +NoMethodError+ when raised from a {Proxy}
     class ProxyMethodError < NoMethodError; end
 
-    class Proxy    
+    # The Proxy class is a way to lazily resolve code objects in
+    # cases where the object may not yet exist. A proxy simply stores
+    # an unresolved path until a method is called on the object, at which
+    # point it does a lookup using {Registry#resolve}. If the object is
+    # not found, a warning is raised and {ProxyMethodError} might be raised.
+    # 
+    # @example Creates a Proxy to the String class from a module
+    #   # When the String class is parsed this method will
+    #   # begin to act like the String ClassObject.
+    #   Proxy.new(mymoduleobj, "String")
+    # @see Registry#resolve
+    # @see ProxyMethodError
+    class Proxy
       def self.===(other) other.is_a?(self) end
 
       attr_reader :namespace, :name
       alias_method :parent, :namespace
 
-      # @raise ArgumentError if namespace is not a NamespaceObject
+      # Creates a new Proxy
+      # 
+      # @raise [ArgumentError] if namespace is not a NamespaceObject
+      # @return [Proxy] self
       def initialize(namespace, name)
         namespace = Registry.root if !namespace || namespace == :root
         
@@ -39,7 +55,9 @@ module YARD
           @namespace = Registry.root
         end
       end
-      
+
+      # Returns a text representation of the Proxy
+      # @return [String] the object's #inspect method or P(OBJECTPATH)
       def inspect
         if obj = to_obj
           obj.inspect
@@ -48,6 +66,11 @@ module YARD
         end
       end
       
+      # If the proxy resolves to an object, returns its path, otherwise
+      # guesses at the correct path using the original namespace and name.
+      # 
+      # @return [String] the assumed path of the proxy (or the real path
+      #   of the resolved object)
       def path
         if obj = to_obj
           obj.path
@@ -69,6 +92,7 @@ module YARD
       end
       alias to_s path
     
+      # @return [Boolean] 
       def is_a?(klass)
         if obj = to_obj
           obj.is_a?(klass)
@@ -77,6 +101,7 @@ module YARD
         end
       end
       
+      # @return [Boolean] 
       def ===(other)
         if obj = to_obj
           obj === other
@@ -85,6 +110,7 @@ module YARD
         end
       end
       
+      # @return [Boolean] 
       def <=>(other)
         if other.respond_to? :path
           path <=> other.path
@@ -93,6 +119,7 @@ module YARD
         end
       end
       
+      # @return [Boolean] 
       def ==(other)
         if other.respond_to? :path
           path == other.path
@@ -101,6 +128,9 @@ module YARD
         end
       end
       
+      # Returns the class name of the object the proxy is mimicking, if
+      # resolved. Otherwise returns +Proxy+. 
+      # @return [Class] the resolved object's class or +Proxy+
       def class
         if obj = to_obj
           obj.class
@@ -109,6 +139,11 @@ module YARD
         end
       end
       
+      # Returns the type of the proxy. If it cannot be resolved at the
+      # time of the call, it will either return the inferred proxy type
+      # (see {#type=}) or +:proxy+
+      # @return [Symbol] the Proxy's type
+      # @see #type=
       def type
         if obj = to_obj
           obj.type
@@ -116,16 +151,23 @@ module YARD
           Registry.proxy_types[path] || :proxy
         end
       end
+      
+      # Allows a parser to infer the type of the proxy by its path.
+      # @param [#to_sym] type the proxy's inferred type
+      # @return [nil] 
       def type=(type) Registry.proxy_types[path] = type.to_sym end
       
+      # @return [Boolean] 
       def instance_of?(klass)
         self.class == klass
       end
       
+      # @return [Boolean] 
       def kind_of?(klass)
         self.class <= klass
       end
       
+      # @return [Boolean] 
       def respond_to?(meth, include_private = false)
         if obj = to_obj
           obj.respond_to?(meth, include_private)
@@ -134,9 +176,9 @@ module YARD
         end
       end
 
-      # Dispatches the method to the resolved object
+      # Dispatches the method to the resolved object.
       # 
-      # @raise NoMethodError if the proxy cannot find the real object
+      # @raise [ProxyMethodError] if the proxy cannot find the real object
       def method_missing(meth, *args, &block)
         if obj = to_obj
           obj.__send__(meth, *args, &block)
@@ -166,7 +208,12 @@ module YARD
       # 
       # @return [Base, nil] the registered code object or nil
       def to_obj
-        @obj ||= Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s)
+        return @obj if @obj
+        if @obj = Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s)
+          @namespace = @obj.namespace
+          @name = @obj.name
+        end
+        @obj
       end
     end
   end

data/lib/yard/code_objects/root_object.rb

@@ -1,5 +1,7 @@
 module YARD
   module CodeObjects
+    # Represents the root namespace object (the invisible Ruby module that
+    # holds all top level modules, class and other objects).
     class RootObject < ModuleObject
       def path; "" end
       def inspect; "#<yardoc root>" end

data/lib/yard/core_ext/array.rb

@@ -0,0 +1,61 @@
+class Array
+  # Places a value before or after another object (by value) in
+  # an array. This is used in tandem with the before and after
+  # methods of the {Insertion} class.
+  # 
+  # @example Places an item before another
+  #   [1, 2, 3].place(4).before(3) # => [1, 2, 4, 3]
+  # @example Places an item after another
+  #   [:a, :b, :c].place(:x).after(:a) # => [:a, :x, :b, :c]
+  # @param [Object] value value to insert
+  # @return [Insertion] an insertion object to 
+  # @see Insertion#before
+  # @see Insertion#after
+  def place(value) Insertion.new(self, value) end
+end
+
+# The Insertion class inserts a value before or after another
+# value in a list.
+# 
+# @example
+#   Insertion.new([1, 2, 3], 4).before(3) # => [1, 2, 4, 3]
+class Insertion
+  # Creates an insertion object on a list with a value to be
+  # inserted. To finalize the insertion, call {#before} or
+  # {#after} on the object.
+  # 
+  # @param [Array] list the list to perform the insertion on
+  # @param [Object] value the value to insert
+  def initialize(list, value) @list, @value = list, value end
+    
+  # Inserts the value before +val+
+  # @param [Object] val the object the value will be inserted before
+  def before(val) insertion(val, 0) end
+    
+  # Inserts the value after +val+. 
+  # 
+  # @example If subsections are ignored
+  #   Insertion.new([1, [2], 3], :X).after(1) # => [1, [2], :X, 3]
+  # @param [Object] val the object the value will be inserted after
+  # @param [Boolean] ignore_subsections treat any Array objects that follow val as
+  #   associated and do not split them up.
+  def after(val, ignore_subsections = true) insertion(val, 1, ignore_subsections) end
+
+  private
+
+  # This method performs the actual insertion
+  # 
+  # @param [Object] val the value to insert
+  # @param [Fixnum] rel the relative index (0 or 1) of where the object
+  #   should be placed
+  # @param [Boolean] ignore_subsections see {#after} for an explanation.
+  def insertion(val, rel, ignore_subsections = true) 
+    if index = @list.index(val)
+      if ignore_subsections && rel == 1 && @list[index + 1].is_a?(Array)
+        rel += 1
+      end
+      @list[index+rel,0] = @value 
+    end
+    @list
+  end
+end