yard 0.2.2 → 0.2.3

data/lib/yard/code_objects/proxy.rb

@@ -12,18 +12,18 @@ module YARD
       def initialize(namespace, name)
         namespace = Registry.root if !namespace || namespace == :root
         
-        if name =~ /^#{NSEP}/
+        if name =~ /^#{NSEPQ}/
           namespace = Registry.root
           name = name[2..-1]
         end
         
-        if name =~ /(?:#{NSEP}|#{ISEP})([^#{NSEP}#{ISEP}]+)$/
+        if name =~ /(?:#{NSEPQ}|#{ISEPQ}|#{CSEPQ})([^#{NSEPQ}#{ISEPQ}#{CSEPQ}]+)$/
           @orignamespace, @origname = namespace, name
           @imethod = true if name.include? ISEP
-          namespace = $`.empty? ? Registry.root : Proxy.new(namespace, $`)
+          namespace = Proxy.new(namespace, $`) unless $`.empty?
           name = $1
         end 
-
+        
         @name = name.to_sym
         @namespace = namespace
         
@@ -34,8 +34,8 @@ module YARD
         # If the name begins with "::" (like "::String")
         # this is definitely a root level object, so
         # remove the namespace and attach it to the root
-        if @name =~ /^#{NSEP}/
-          @name.gsub!(/^#{NSEP}/, '')
+        if @name =~ /^#{NSEPQ}/
+          @name.gsub!(/^#{NSEPQ}/, '')
           @namespace = Registry.root
         end
       end
@@ -54,8 +54,16 @@ module YARD
         else
           if @namespace == Registry.root
             (@imethod ? ISEP : "") + name.to_s
-          else
-            @origname || name.to_s
+          elsif @origname
+            if @origname =~ /^[A-Z]/
+              @origname
+            else
+              [namespace.path, @origname].join
+            end
+          elsif name.to_s =~ /^[A-Z]/ # const
+            name.to_s
+          else # class meth?
+            [namespace.path, name.to_s].join(CSEP)
           end
         end
       end
@@ -117,18 +125,10 @@ module YARD
       def kind_of?(klass)
         self.class <= klass
       end
-
-      def object_id
-        if obj = to_obj
-          obj.object_id
-        else
-          nil
-        end
-      end
       
-      def respond_to?(meth)
+      def respond_to?(meth, include_private = false)
         if obj = to_obj
-          obj.respond_to?(meth)
+          obj.respond_to?(meth, include_private)
         else
           super
         end
@@ -166,7 +166,7 @@ module YARD
       # 
       # @return [Base, nil] the registered code object or nil
       def to_obj
-        @obj ||= Registry.resolve(@namespace, @name)
+        @obj ||= Registry.resolve(@namespace, (@imethod ? ISEP : '') + @name.to_s)
       end
     end
   end
@@ -176,8 +176,8 @@ end
 # via a path
 # 
 # @see YARD::CodeObjects::Proxy
-# @see YARD::Registry::resolve
+# @see YARD::Registry#resolve
 def P(namespace, name = nil)
   namespace, name = nil, namespace if name.nil?
-  YARD::Registry.resolve(namespace, name, true)
-end
+  YARD::Registry.resolve(namespace, name, false, true)
+end

data/lib/yard/core_ext/file.rb

@@ -4,7 +4,7 @@ class File
   # Turns a path +to+ into a relative path from starting
   # point +from+. The argument +from+ is assumed to be
   # a filename. To treat it as a directory, make sure it
-  # ends in {File::SEPARATOR} ('/' on UNIX filesystems).
+  # ends in `File::SEPARATOR` ('/' on UNIX filesystems).
   # 
   # @param [String] from the starting filename 
   #   (or directory with +from_isdir+ set to +true+).

data/lib/yard/core_ext/string.rb

@@ -1,12 +1,8 @@
 class String
-  # @it should turn hello_world into HelloWorld
-  #   "hello_world".camelcase.should == "HelloWorld"
   def underscore
     gsub(/([a-z])([A-Z])/, '\1_\2').downcase 
   end
   
-  # @it should turn HelloWorld into hello_world
-  #   "HelloWorld".underscore.should == "hello_world"
   def camelcase
     gsub(/([a-z])_([a-z])/i) { $1 + $2.upcase }.sub(/^(.)/) { $1.upcase } 
   end

data/lib/yard/core_ext/symbol_hash.rb

@@ -20,5 +20,6 @@ class SymbolHash < Hash
   def delete(key) super(key.to_sym) end
   def has_key?(key) super(key.to_sym) end
   def update(hsh) hsh.each {|k,v| self[k] = v }; self end
-  alias_method :merge, :update
-end
+  alias_method :merge!, :update
+  def merge(hsh) dup.merge!(hsh) end
+end

data/lib/yard/docstring.rb

@@ -0,0 +1,180 @@
+module YARD
+  class Docstring < String
+    attr_reader :ref_tags
+    attr_accessor :object
+    
+    def initialize(content = '', object = nil)
+      @tag_factory = Tags::Library.new
+      @tags, @ref_tags = [], []
+      @object = object
+      
+      replace parse_comments(content)
+    end
+    
+    ##
+    # Gets the first line of a docstring to the period or the first paragraph.
+    # 
+    # @return [String] The first line or paragraph of the docstring; always ends with a period.
+    def summary
+      @summmary ||= (split(/\.|\r?\n\r?\n/).first || '')
+      @summmary += '.' unless @summmary.empty?
+      @summmary
+    end
+    
+    ##
+    # Adds a tag or reftag object to the tag list
+    # 
+    # @param [Tags::Tag, Tags::RefTag] *tags list of tag objects to add
+    def add_tag(*tags)
+      tags.each_with_index do |tag, i|
+        case tag
+        when Tags::Tag
+          tag.object = object
+          @tags << tag
+        when Tags::RefTag
+          @ref_tags << tag
+        else
+          raise ArgumentError, "expected Tag or RefTag, got #{tag.class} (at index #{i})"
+        end
+      end
+    end
+    
+    ## 
+    # Convenience method to return the first tag
+    # object in the list of tag objects of that name
+    #
+    # @example
+    #   doc = YARD::Docstring.new("@return zero when nil")
+    #   doc.tag(:return).text  # => "zero when nil"
+    #
+    # @param [#to_s] name the tag name to return data for
+    # @return [Tags::Tag] the first tag in the list of {#tags}
+    def tag(name)
+      tags.find {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    ##
+    # Returns a list of tags specified by +name+ or all tags if +name+ is not specified.
+    #
+    # @param name the tag name to return data for, or nil for all tags
+    # @return [Array<Tags::Tag>] the list of tags by the specified tag name
+    def tags(name = nil)
+      list = @tags + convert_ref_tags
+      return list unless name
+      list.select {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    ##
+    # Returns true if at least one tag by the name +name+ was declared
+    #
+    # @param [String] name the tag name to search for
+    # @return [Boolean] whether or not the tag +name+ was declared
+    def has_tag?(name)
+      tags.any? {|tag| tag.tag_name.to_s == name.to_s }
+    end
+
+    ##
+    # Returns true if the docstring has no content
+    #
+    # @return [Boolean] whether or not the docstring has content
+    def blank?
+      empty? && @tags.empty? && @ref_tags.empty?
+    end
+
+    private
+    
+    def convert_ref_tags
+      list = @ref_tags.reject {|t| CodeObjects::Proxy === t.owner }
+      list.map {|t| t.tags }.flatten
+    end
+    
+    ##
+    # Creates a {RefTag}
+    def create_ref_tag(tag_name, name, object)
+      @ref_tags << Tags::RefTagList.new(tag_name, object, name)
+    end
+    
+    ##
+    # Creates a tag from the TagFactory 
+    # 
+    def create_tag(tag_name, tag_buf, raw_buf)
+      if tag_buf =~ /\A\s*(?:(\S+)\s+)?\(\s*see\s+(\S+)\s*\)\s*\Z/
+        return create_ref_tag(tag_name, $1, $2)
+      end
+        
+      tag_method = "#{tag_name}_tag"
+      if tag_name && @tag_factory.respond_to?(tag_method)
+        if @tag_factory.method(tag_method).arity == 2
+          add_tag *@tag_factory.send(tag_method, tag_buf, raw_buf.join("\n"))
+        else
+          add_tag *@tag_factory.send(tag_method, tag_buf) 
+        end
+      else
+        log.warn "Unknown tag @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
+      end
+    rescue Tags::TagFormatError
+      log.warn "Invalid tag format for @#{tag_name}" + (object ? " in file `#{object.file}` near line #{object.line}" : "")
+    end
+
+    ##
+    # Parses out comments split by newlines into a new code object
+    #
+    # @param [String] comments 
+    #   the newline delimited array of comments. If the comments
+    #   are passed as a String, they will be split by newlines. 
+    # 
+    # @return [String] the non-metadata portion of the comments to
+    #   be used as a docstring
+    def parse_comments(comments)
+      return '' if !comments || comments.empty?
+      meta_match = /^@(\S+)\s*(.*)/
+      comments = comments.split(/\r?\n/) if comments.is_a? String
+      docstring = ""
+
+      indent, last_indent = comments.first[/^\s*/].length, 0
+      orig_indent = 0
+      last_line = ""
+      tag_name, tag_klass, tag_buf, raw_buf = nil, nil, "", []
+
+      (comments+['']).each_with_index do |line, index|
+        indent = line[/^\s*/].length 
+        empty = (line =~ /^\s*$/ ? true : false)
+        done = comments.size == index
+
+        if tag_name && (((indent < orig_indent && !empty) || done) || 
+            (indent <= last_indent && line =~ meta_match))
+          create_tag(tag_name, tag_buf, raw_buf)
+          tag_name, tag_buf, raw_buf = nil, '', []
+          orig_indent = 0
+        end
+
+        # Found a meta tag
+        if line =~ meta_match
+          orig_indent = indent
+          tag_name, tag_buf = $1, $2 
+          raw_buf = [tag_buf.dup]
+        elsif tag_name && indent >= orig_indent && !empty
+          # Extra data added to the tag on the next line
+          last_empty = last_line =~ /^[ \t]*$/ ? true : false
+          
+          if last_empty
+            tag_buf << "\n\n" 
+            raw_buf << ''
+          end
+          
+          tag_buf << line.gsub(/^[ \t]{#{indent}}/, last_empty ? '' : ' ')
+          raw_buf << line.gsub(/^[ \t]{#{orig_indent}}/, '')
+        elsif !tag_name
+          # Regular docstring text
+          docstring << line << "\n" 
+        end
+
+        last_indent = indent
+        last_line = line
+      end
+
+      # Remove trailing/leading whitespace / newlines
+      docstring.gsub!(/\A[\r\n\s]+|[\r\n\s]+\Z/, '')
+    end
+  end
+end

data/lib/yard/generators/base.rb

@@ -23,7 +23,23 @@ module YARD
         def register_template_path(path)
           template_paths.unshift(path)
         end
-        
+
+        # Calls the +Proc+ object or method name before generating all or a specific
+        # section. The callback should return +false+ if the section is to be
+        # skipped.
+        # 
+        # @overload before_section(method_name)
+        #   @param [Symbol] method_name the name of the method to call before
+        #     running the generator.
+        # 
+        # @overload before_section(proc)
+        #   @param [Proc] proc should return +false+ if section should be skipped.
+        # 
+        # @overload before_section(section, condition)
+        #   Only calls the +Proc+ or method if it matches the passed +section+
+        #   
+        #   @param [Object] section one of the section items in {#sections_for}
+        #   @param [Symbol, Proc] condition see the first two overloads
         def before_section(*args)
           if args.size == 1
             before_section_filters.push [nil, args.first]
@@ -64,9 +80,7 @@ module YARD
       # @param [Class] generator 
       #   the generator class to use.
       # 
-      # @options opts
-      #   :ignore_serializer -> true => value
-      #
+      # @option opts :ignore_serializer [Boolean] (true) whether or not the serializer is ignored.
       # 
       def G(generator, opts = {})
         opts = SymbolHash[:ignore_serializer => true].update(opts)
@@ -82,6 +96,7 @@ module YARD
         opts = SymbolHash[
           :format => :html,
           :template => :default,
+          :markup => :rdoc,
           :serializer => nil,
           :verifier => nil
         ].update(opts).update(extra_opts)
@@ -110,7 +125,7 @@ module YARD
         serializer.before_serialize if serializer && !ignore_serializer
         
         list.each do |object|
-          next unless object && object.is_a?(CodeObjects::Base)
+          next unless object && !object.is_a?(CodeObjects::Proxy)
           
           objout = ""
           @current_object = object
@@ -247,24 +262,29 @@ module YARD
           object, file, locals = current_object, object, (file||{})
         end
         
-        __path = template_path(file.to_s + '.erb', generator_name)
-        __f = find_template(__path)
-        if __f
-          __l = locals.map {|k,v| "#{k} = #{v.inspect}" unless k.to_s == "__f" }.join(";")
+        path = template_path(file.to_s + '.erb', generator_name)
+        filename = find_template(path)
+        if filename
           begin
-            erb("<% #{__l} %>" + File.read(__f)).result(binding)
+            render_method(object, filename, locals, &block)           
           rescue => e
             log.error "#{e.class.class_name}: #{e.message}"
-            log.error "in generator #{self.class} section #{file} on '#{object}'"
+            log.error "in generator #{self.class}: #{filename}"
             log.error e.backtrace[0..10].join("\n")
             exit
           end
         else
-          log.warn "Cannot find template `#{__path}`"
+          log.warn "Cannot find template `#{path}`"
           ""
         end
       end
       
+      def render_method(object, filename, locals = {}, &block)
+        l = locals.map {|k,v| "#{k} = locals[#{k.inspect}]" }.join(";")
+        src = erb("<% #{l} %>" + File.read(filename)).src
+        instance_eval(src, filename, 1)
+      end
+      
       def erb(str)
         ERB.new(str, nil, '<>')
       end
@@ -282,4 +302,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/class_generator.rb

@@ -8,8 +8,10 @@ module YARD
           :header,
           [
             G(InheritanceGenerator), 
-            G(MixinsGenerator), 
+            G(MixinsGenerator, :scope => :class),
+            G(MixinsGenerator, :scope => :instance),
             G(DocstringGenerator), 
+            G(TagsGenerator),
             G(AttributesGenerator), 
             G(ConstantsGenerator),
             G(ConstructorGenerator),
@@ -22,4 +24,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/constants_generator.rb

@@ -1,6 +1,7 @@
 module YARD
   module Generators
     class ConstantsGenerator < Base
+      before_generate :is_namespace?
       before_section :constants, :has_constants?
       before_section :inherited, :has_inherited_constants?
       before_section :included,  :has_included_constants?
@@ -60,7 +61,7 @@ module YARD
       # 
       def included_constants_by_module
         all_consts = current_object.included_constants
-        current_object.mixins.each do |superclass|
+        current_object.instance_mixins.each do |superclass|
           next if superclass.is_a?(CodeObjects::Proxy)
           opts = { :included => false, :inherited => false }
           consts = superclass.constants(opts).select {|c| all_consts.include?(c) }
@@ -70,4 +71,4 @@ module YARD
       end
     end
   end
-end
+end

data/lib/yard/generators/full_doc_generator.rb

@@ -2,12 +2,15 @@ module YARD
   module Generators
     class FullDocGenerator < Base
       before_generate :is_namespace?
+      before_list :setup_options
       before_list :generate_assets
       before_list :generate_index
-      before_list :generate_readme
+      before_list :generate_files
       
       def sections_for(object) 
         case object
+        when CodeObjects::RootObject
+          [:header, [G(RootGenerator)]]
         when CodeObjects::ClassObject
           [:header, [G(ClassGenerator)]]
         when CodeObjects::ModuleObject
@@ -16,6 +19,11 @@ module YARD
       end
       
       protected
+      
+      def setup_options
+        options[:readme] ||= Dir['{README,README.*}']
+        options[:files]  ||= []
+      end
     
       def css_file;         'style.css'             end
       def css_syntax_file;  'syntax_highlight.css'  end
@@ -28,6 +36,12 @@ module YARD
         end.to_s
       end
       
+      def readme_file_exists?; not readme_file.empty?; end
+      
+      def extra_files
+        [readme_file] + options[:files]
+      end
+      
       def generate_assets
         if format == :html && serializer
           [css_file, css_syntax_file, js_file, js_app_file].each do |filename|
@@ -38,22 +52,75 @@ module YARD
         true
       end
       
-      def generate_index
+      def generate_index(all_objects)
         if format == :html && serializer
+          ns = all_objects.select {|o| o.type == :module || o.type == :class }
+          all_namespaces = { 
+            :objects => ns.sort_by {|o| o.path },
+            :root => all_objects.find {|o| o.type == :root && (!o.meths.empty? || !o.constants.empty?) }
+          }
+          all_methods = { :objects => methods_to_show(all_objects) }
+          
           serializer.serialize 'index.html', render(:index)
-          serializer.serialize 'all-namespaces.html', render(:all_namespaces)
-          serializer.serialize 'all-methods.html', render(:all_methods)
+          serializer.serialize 'all-files.html', render(:all_files)
+          serializer.serialize 'all-namespaces.html', render(:all_namespaces, all_namespaces)
+          serializer.serialize 'all-methods.html', render(:all_methods, all_methods)
         end
         true
       end
       
-      def generate_readme
-        if format == :html && serializer && readme_file
-          @contents = File.read(readme_file)
-          serializer.serialize 'readme.html', render(:readme)
+      def generate_files
+        if format == :html && serializer 
+          extra_files.each do |file|
+            next unless File.exists?(file)
+            @contents = File.read(file)
+            file = File.basename(file)
+            serializer.serialize file + '.html', render(:file, :filename => file)
+          end
         end
         true
       end
+      
+      def markup_for(filename)
+        case File.extname(filename).downcase
+        when /^\.(?:mdown|markdown|mkdn|markdn|md)$/
+          :markdown
+        when ".textile"
+          :textile
+        when /^\.html?$/
+          if format == :html
+            nil # no markup, use raw data
+          else
+            # TODO implement some html->plaintext markup
+            :rdoc
+          end
+        else
+          if @contents =~ /\A#!(\S+)\s*$/ # Shebang support
+            markup = $1
+            @contents.gsub!(/\A.+?\r?\n/, '')
+            markup.to_sym
+          else
+            :rdoc
+          end
+        end
+      end
+      
+      def methods_to_show(namespaces)
+        meths = namespaces.inject([]) do |arr, namespace|
+          next(arr) unless namespace.is_a?(CodeObjects::NamespaceObject)
+          more_meths = namespace.meths(:included => false, :inherited => false)
+          more_meths = more_meths.select {|object| object.is_explicit? }
+          arr += more_meths
+        end
+        if options[:verifier]
+          meths.reject! do |object|
+            # FIXME we should be using call_verifier here, but visibility
+            # is checked on the generator, not the object
+            options[:verifier].call(object, object).is_a?(FalseClass)
+          end
+        end
+        meths.sort_by {|object| object.path }
+      end
     end
   end
-end
+end