yard 0.2.3.5 → 0.4.0

data/lib/yard/code_objects/base.rb

@@ -1,10 +1,20 @@
 module YARD
   module CodeObjects
+    # A list of code objects. This array acts like a set (no unique items)
+    # but also disallows any {Proxy} objects from being added.
     class CodeObjectList < Array
+      # Creates a new object list associated with a namespace
+      # 
+      # @param [NamespaceObject] owner the namespace the list should be associated with
+      # @return [CodeObjectList]
       def initialize(owner = Registry.root)
         @owner = owner
       end
       
+      # Adds a new value to the list
+      # 
+      # @param [Base] value a code object to add
+      # @return [CodeObjectList] self
       def push(value)
         value = Proxy.new(@owner, value) if value.is_a?(String) || value.is_a?(Symbol)
         if value.is_a?(CodeObjects::Base) || value.is_a?(Proxy)
@@ -17,8 +27,11 @@ module YARD
       alias_method :<<, :push
     end
     
-    NSEPQ = NSEP = '::'
-    ISEPQ = ISEP = '#'
+    
+    NSEP = '::'
+    NSEPQ = NSEP
+    ISEP = '#'
+    ISEPQ = ISEP
     CSEP = '.'
     CSEPQ = Regexp.quote CSEP
     CONSTANTMATCH = /[A-Z]\w*/
@@ -42,13 +55,73 @@ module YARD
     
     BUILTIN_EXCEPTIONS_HASH = BUILTIN_EXCEPTIONS.inject({}) {|h,n| h.update(n => true) }
     
+    # +Base+ is the superclass of all code objects recognized by YARD. A code
+    # object is any entity in the Ruby language (class, method, module). A 
+    # DSL might subclass +Base+ to create a new custom object representing
+    # a new entity type. 
+    # 
+    # == Registry Integration
+    # Any created object associated with a namespace is immediately registered 
+    # with the registry. This allows the Registry to act as an identity map
+    # to ensure that no object is represented by more than one Ruby object
+    # in memory. A unique {#path} is essential for this identity map to work
+    # correctly.
+    # 
+    # == Custom Attributes
+    # Code objects allow arbitrary custom attributes to be set using the
+    # {#[]=} assignment method.
+    # 
+    # == Namespaces
+    # There is a special type of object called a "namespace". These are subclasses
+    # of the {NamespaceObject} and represent Ruby entities that can have
+    # objects defined within them. Classically these are modules and classes,
+    # though a DSL might create a custom {NamespaceObject} to describe a 
+    # specific set of objects.
+    # 
+    # @abstract This class should not be used directly. Instead, create a
+    #   subclass that implements {#path}, {#sep} or {#type}.
+    # @see Registry
+    # @see #path
+    # @see #[]=
+    # @see NamespaceObject
     class Base  
-      attr_reader :name, :files
-      attr_accessor :namespace, :source, :signature, :docstring, :dynamic
+      # The files the object was defined in. To add a file, use {#add_file}.
+      # @return [Array<String>] a list of files
+      # @see #add_file
+      attr_reader :files
+      
+      # The namespace the object is defined in. If the object is in the
+      # top level namespace, this is {Registry#root}
+      # @return [NamespaceObject] the namespace object
+      attr_accessor :namespace
+      
+      # The source code associated with the object
+      # @return [String, nil] source, if present, or nil
+      attr_accessor :source
+      
+      # The one line signature representing an object. For a method, this will
+      # be of the form "def meth(arguments...)". This is usually the first
+      # source line.
+      # 
+      # @return [String] a line of source
+      attr_accessor :signature
+      
+      # The documentation string associated with the object
+      # @return [Docstring] the documentation string
+      attr_accessor :docstring
+      
+      # Marks whether or not the method is conditionally defined at runtime
+      # @return [Boolean] true if the method is conditionally defined at runtime
+      attr_accessor :dynamic
       
+      # Is the object defined conditionally at runtime?
+      # @see #dynamic
       def dynamic?; @dynamic end
       
       class << self
+        # Allocates a new code object
+        # @return [Base] 
+        # @see #initialize
         def new(namespace, name, *args, &block)
           if name.to_s[0,2] == NSEP
             name = name.to_s[2..-1]
@@ -79,11 +152,29 @@ module YARD
           end
         end
         
+        # Compares the class with subclasses
+        # 
+        # @param [Object] other the other object to compare classes with
+        # @return [Boolean] true if other is a subclass of self
         def ===(other)
           self >= other.class ? true : false
         end
       end
           
+      # Creates a new code object
+      # 
+      # @example Create a method in the root namespace
+      #   CodeObjects::Base.new(:root, '#method') # => #<yardoc method #method>
+      # @example Create class Z inside namespace X::Y
+      #   CodeObjects::Base.new(P("X::Y"), :Z) # or
+      #   CodeObjects::Base.new(Registry.root, "X::Y")
+      # @param [NamespaceObject] namespace the namespace the object belongs in,
+      #   {Registry#root} or :root should be provided if it is associated with
+      #   the top level namespace.
+      # @param [Symbol, String] name the name (or complex path) of the object. 
+      # @yield [self] a block to perform any extra initialization on the object
+      # @yieldparam [Base] self the newly initialized code object
+      # @return [Base] the newly created object
       def initialize(namespace, name, *args)
         if namespace && namespace != :root && 
             !namespace.is_a?(NamespaceObject) && !namespace.is_a?(Proxy)
@@ -99,12 +190,22 @@ module YARD
         yield(self) if block_given?
       end
       
+      # The name of the object
+      # @param [Boolean] prefix whether to show a prefix. Implement
+      #   this in a subclass to define how the prefix is showed.
+      # @return [Symbol] if prefix is false, the symbolized name
+      # @return [String] if prefix is true, prefix + the name as a String. 
+      #   This must be implemented by the subclass.
+      def name(prefix = false)
+        prefix ? @name.to_s : @name
+      end
+      
       # Associates a file with a code object, optionally adding the line where it was defined.
-      # By convention, '<STDIN>' should be used to associate code that comes form standard input.
+      # By convention, '<stdin>' should be used to associate code that comes form standard input.
       # 
-      # @param [String] file the filename ('<STDIN>' for standard input)
-      # @param [Fixnum, nil] the line number where the object lies in the file
-      # @param [Boolean] whether or not the definition has comments associated. This
+      # @param [String] file the filename ('<stdin>' for standard input)
+      # @param [Fixnum, nil] line the line number where the object lies in the file
+      # @param [Boolean] has_comments whether or not the definition has comments associated. This
       #   will allow {#file} to return the definition where the comments were made instead
       #   of any empty definitions that might have been parsed before (module namespaces for instance).
       def add_file(file, line = nil, has_comments = false)
@@ -134,6 +235,10 @@ module YARD
         @files.first ? @files.first[1] : nil
       end
       
+      # Tests if another object is equal to this, including a proxy
+      # @param [Base, Proxy] other if other is a {Proxy}, tests if
+      #   the paths are equal
+      # @return [Boolean] whether or not the objects are considered the same
       def ==(other)
         if other.is_a?(Proxy)
           path == other.path
@@ -142,6 +247,10 @@ module YARD
         end
       end
       
+      # Accesses a custom attribute on the object
+      # @param [#to_s] key the name of the custom attribute
+      # @return [Object, nil] the custom attribute or nil if not found.
+      # @see #[]=
       def [](key)
         if respond_to?(key)
           send(key)
@@ -150,6 +259,11 @@ module YARD
         end
       end
       
+      # Sets a custom attribute on the object
+      # @param [#to_s] key the name of the custom attribute
+      # @param [Object] value the value to associate
+      # @return [nil] 
+      # @see #[]
       def []=(key, value)
         if respond_to?("#{key}=")
           send("#{key}=", value)
@@ -158,6 +272,12 @@ module YARD
         end
       end
       
+      # Checks if the method matches the name of an existing custom
+      # attribute.
+      # 
+      # @param [Symbol] meth the name of the method/attribute
+      # @raise [NoMethodError] if no method or custom attribute exists by
+      #   the name +meth+
       def method_missing(meth, *args, &block)
         if meth.to_s =~ /=$/
           self[meth.to_s[0..-2]] = args.first
@@ -168,7 +288,6 @@ module YARD
         end
       end
 
-      ##
       # Attaches source code to a code object with an optional file location
       #
       # @param [#source, String] statement 
@@ -184,7 +303,6 @@ module YARD
         end
       end
 
-      ##
       # Attaches a docstring to a code oject by parsing the comments attached to the statement
       # and filling the {#tags} and {#docstring} methods with the parsed information.
       #
@@ -195,16 +313,23 @@ module YARD
         @docstring = Docstring === comments ? comments : Docstring.new(comments, self)
       end
       
-      ##
-      # Default type is the lowercase class name without the "Object" suffix
-      # 
-      # Override this method to provide a custom object type 
+      # Default type is the lowercase class name without the "Object" suffix.
+      # Override this method to provide a custom object type
       # 
       # @return [Symbol] the type of code object this represents
       def type
         self.class.name.split(/#{NSEPQ}/).last.gsub(/Object$/, '').downcase.to_sym
       end
     
+      # Represents the unique path of the object. The default implementation
+      # joins the path of {#namespace} with {#name} via the value of {#sep}.
+      # Custom code objects should ensure that the path is unique to the code 
+      # object by either overriding {#sep} or this method.
+      # 
+      # @example The path of an instance method
+      #   MethodObject.new(P("A::B"), :c).path # => "A::B#c"
+      # @return [String] the unique path of the object
+      # @see #sep
       def path
         if parent && parent != Registry.root
           [parent.path, name.to_s].join(sep)
@@ -214,10 +339,35 @@ module YARD
       end
       alias_method :to_s, :path
       
+      # Renders the object using the {Templates::Engine templating system}.
+      # 
+      # @example Formats a class in plaintext
+      #   puts P('MyClass').format
+      # @example Formats a method in html with rdoc markup
+      #   puts P('MyClass#meth').format(:format => :html, :markup => :rdoc)
+      # @param [Hash] options a set of options to pass to the template
+      # @option options [Symbol] :format (:text) :html, :text or another output format
+      # @option options [Symbol] :template (:default) a specific template to use
+      # @option options [Symbol] :markup (nil) the markup type (:rdoc, :markdown, :textile)
+      # @option options [Serializers::Base] :serializer (nil) see Serializers
+      # @return [String] the rendered template
+      # @see Templates::Engine#render
+      def format(options = {})
+        options.merge!(:object => self)
+        Templates::Engine.render(options)
+      end
+      
+      # Inspects the object, returning the type and path
+      # @return [String] a string describing the object
       def inspect
         "#<yardoc #{type} #{path}>"
       end
     
+      # Sets the namespace the object is defined in.
+      # 
+      # @param [NamespaceObject, :root, nil] obj the new namespace (:root 
+      #   for {Registry#root}). If obj is nil, the object is unregistered
+      #   from the Registry.
       def namespace=(obj)
         if @namespace
           @namespace.children.delete(self) 
@@ -235,15 +385,33 @@ module YARD
       alias_method :parent, :namespace
       alias_method :parent=, :namespace=
 
+      # Gets a tag from the {#docstring}
+      # @see Docstring#tag
       def tag(name); @docstring.tag(name) end
+      
+      # Gets a list of tags from the {#docstring}
+      # @see Docstring#tags
       def tags(name = nil); @docstring.tags(name) end
+      
+      # Tests if the {#docstring} has a tag
+      # @see Docstring#has_tag?
       def has_tag?(name); @docstring.has_tag?(name) end
 
       protected
     
+      # Override this method with a custom component separator. For instance,
+      # {MethodObject} implements sep as '#' or '.' (depending on if the
+      # method is instance or class respectively). {#path} depends on this
+      # value to generate the full path in the form: namespace.path + sep + name
+      # 
+      # @return [String] the component that separates the namespace path
+      #   and the name (default is {NSEP})
       def sep; NSEP end
 
       # Formats source code by removing leading indentation
+      # 
+      # @param [String] source the source code to format
+      # @return [String] formatted source
       def format_source(source)
         source.chomp!
         indent = source.split(/\r?\n/).last[/^([ \t]*)/, 1].length

data/lib/yard/code_objects/class_object.rb

@@ -1,7 +1,12 @@
 module YARD::CodeObjects
   class ClassObject < NamespaceObject
+    # The {ClassObject} that this class object inherits from in Ruby source.
+    # @return [ClassObject] a class object that is the superclass of this one
     attr_accessor :superclass
     
+    # Creates a new class object in +namespace+ with +name+
+    # 
+    # @see Base.new
     def initialize(namespace, name, *args, &block)
       super
 
@@ -12,14 +17,23 @@ module YARD::CodeObjects
       end
     end
     
+    # Whether or not the class is a Ruby Exception
+    # 
+    # @return [Boolean] whether the object represents a Ruby exception
     def is_exception?
       inheritance_tree.reverse.any? {|o| BUILTIN_EXCEPTIONS_HASH.has_key? o.path }
     end
     
+    # Returns the inheritance tree of the object including self.
+    # 
+    # @param [Boolean] include_mods whether or not to include mixins in the
+    #   inheritance tree.
+    # @return [Array<NamespaceObject>] the list of code objects that make up
+    #   the inheritance tree.
     def inheritance_tree(include_mods = false)
       list = (include_mods ? mixins(:instance) : [])
       if superclass.is_a?(Proxy) || superclass.respond_to?(:inheritance_tree)
-        list << superclass unless superclass == P(:Object)
+        list += [superclass] unless superclass == P(:Object)
       end
       [self] + list.map do |m|
         next m unless m.respond_to?(:inheritance_tree)
@@ -27,11 +41,23 @@ module YARD::CodeObjects
       end.flatten
     end
     
+    # Returns the list of methods matching the options hash. Returns
+    # all methods if hash is empty.
+    # 
+    # @param [Hash] opts the options hash to match
+    # @option opts [Boolean] :inherited (true) whether inherited methods should be
+    #   included in the list
+    # @option opts [Boolean] :included (true) whether mixed in methods should be
+    #   included in the list
+    # @return [Array<MethodObject>] the list of methods that matched
     def meths(opts = {})
       opts = SymbolHash[:inherited => true].update(opts)
       super(opts) + (opts[:inherited] ? inherited_meths(opts) : [])
     end
     
+    # Returns only the methods that were inherited.
+    # 
+    # @return [Array<MethodObject>] the list of inherited method objects
     def inherited_meths(opts = {})
       inheritance_tree[1..-1].inject([]) do |list, superclass|
         if superclass.is_a?(Proxy)
@@ -45,11 +71,22 @@ module YARD::CodeObjects
       end
     end
     
+    # Returns the list of constants matching the options hash.
+    # 
+    # @param [Hash] opts the options hash to match
+    # @option opts [Boolean] :inherited (true) whether inherited constant should be
+    #   included in the list
+    # @option opts [Boolean] :included (true) whether mixed in constant should be
+    #   included in the list
+    # @return [Array<ConstantObject>] the list of constant that matched
     def constants(opts = {})
       opts = SymbolHash[:inherited => true].update(opts)
       super(opts) + (opts[:inherited] ? inherited_constants : [])
     end
     
+    # Returns only the constants that were inherited.
+    # 
+    # @return [Array<ConstantObject>] the list of inherited constant objects
     def inherited_constants
       inheritance_tree[1..-1].inject([]) do |list, superclass|
         if superclass.is_a?(Proxy)
@@ -62,10 +99,10 @@ module YARD::CodeObjects
       end
     end
     
-    ##
     # Sets the superclass of the object
     # 
     # @param [Base, Proxy, String, Symbol, nil] object the superclass value
+    # @return [nil] 
     def superclass=(object)
       case object
       when Base, Proxy, NilClass

data/lib/yard/code_objects/class_variable_object.rb

@@ -1,4 +1,8 @@
 module YARD::CodeObjects
+  # Represents a class variable inside a namespace. The path is expressed
+  # in the form "A::B::@@classvariable"
   class ClassVariableObject < Base
+    # @return [String] the class variable's value
+    attr_accessor :value
   end
 end

data/lib/yard/code_objects/constant_object.rb

@@ -1,5 +1,13 @@
 module YARD::CodeObjects
+  # A +ConstantObject+ represents a Ruby constant (not a module or class).
+  # To access the constant's (source code) value, use {#value}.
   class ConstantObject < Base
+    # The source code representing the constant's value
+    # @return [String] the value the constant is set to
     attr_accessor :value
+    
+    def value=(value)
+      @value = format_source(value)
+    end
   end
 end

data/lib/yard/code_objects/extended_method_object.rb

@@ -1,9 +1,23 @@
 module YARD::CodeObjects
+  # Represents an instance method of a module that was mixed into the class
+  # scope of another namespace.
+  # 
+  # @see MethodObject
   class ExtendedMethodObject
     instance_methods.each {|m| undef_method(m) unless m =~ /^__/ || m.to_sym == :object_id }
     
+    # @return [Symbol] always +:class+
     def scope; :class end
+    
+    # Sets up a delegate for {MethodObject} obj.
+    # 
+    # @param [MethodObject] obj the instance method to treat as a mixed in
+    #   class method on another namespace.
     def initialize(obj) @del = obj end
+      
+    # Sends all methods to the {MethodObject} assigned in {#initialize}
+    # @see #initialize
+    # @see MethodObject
     def method_missing(sym, *args, &block) @del.__send__(sym, *args, &block) end
   end
 end