rdoc 2.0.0 → 2.1.0

data/lib/rdoc/parser/simple.rb

@@ -0,0 +1,38 @@
+require 'rdoc/parser'
+
+##
+# Parse a non-source file. We basically take the whole thing as one big
+# comment. If the first character in the file is '#', we strip leading pound
+# signs.
+
+class RDoc::Parser::Simple < RDoc::Parser
+
+  parse_files_matching(//)
+
+  ##
+  # Prepare to parse a plain file
+
+  def initialize(top_level, file_name, content, options, stats)
+    super
+
+    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+
+    preprocess.handle @content do |directive, param|
+      warn "Unrecognized directive '#{directive}' in #{@file_name}"
+    end
+  end
+
+  ##
+  # Extract the file contents and attach them to the toplevel as a comment
+
+  def scan
+    @top_level.comment = remove_private_comments(@content)
+    @top_level
+  end
+
+  def remove_private_comments(comment)
+    comment.gsub(/^--[^-].*?^\+\+/m, '').sub(/^--.*/m, '')
+  end
+
+end
+

data/lib/rdoc/rdoc.rb

@@ -1,9 +1,12 @@
 require 'rdoc'
 
-require 'rdoc/parsers/parse_rb.rb'
-require 'rdoc/parsers/parse_c.rb'
-require 'rdoc/parsers/parse_f95.rb'
-require 'rdoc/parsers/parse_simple.rb'
+require 'rdoc/parser'
+
+# Simple must come first
+require 'rdoc/parser/simple'
+require 'rdoc/parser/ruby'
+require 'rdoc/parser/c'
+require 'rdoc/parser/f95'
 
 require 'rdoc/stats'
 require 'rdoc/options'
@@ -17,21 +20,24 @@ require 'time'
 module RDoc
 
   ##
-  # Encapsulate the production of rdoc documentation. Basically
-  # you can use this as you would invoke rdoc from the command
-  # line:
+  # Encapsulate the production of rdoc documentation. Basically you can use
+  # this as you would invoke rdoc from the command line:
   #
-  #    rdoc = RDoc::RDoc.new
-  #    rdoc.document(args)
+  #   rdoc = RDoc::RDoc.new
+  #   rdoc.document(args)
   #
-  # where _args_ is an array of strings, each corresponding to
-  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb
-  # for details.
+  # Where +args+ is an array of strings, each corresponding to an argument
+  # you'd give rdoc on the command line. See rdoc/rdoc.rb for details.
 
   class RDoc
 
     Generator = Struct.new(:file_name, :class_name, :key)
 
+    ##
+    # Accessor for statistics.  Available after each call to parse_files
+
+    attr_reader :stats
+
     ##
     # This is the list of output generator that we support
 
@@ -54,7 +60,7 @@ module RDoc
     end
 
     def initialize
-      @stats = Stats.new
+      @stats = nil
     end
 
     ##
@@ -134,7 +140,7 @@ module RDoc
     # subdirectories.
     #
     # The effect of this is that if you want a file with a non-standard
-    # extension parsed, you must name it explicity.
+    # extension parsed, you must name it explicitly.
 
     def normalized_file_list(options, relative_files, force_doc = false,
                              exclude_pattern = nil)
@@ -146,7 +152,10 @@ module RDoc
         case type = stat.ftype
         when "file"
           next if @last_created and stat.mtime < @last_created
-          file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
+
+          if force_doc or ::RDoc::Parser.can_parse(rel_file_name) then
+            file_list << rel_file_name.sub(/^\.\//, '')
+          end
         when "directory"
           next if rel_file_name == "CVS" || rel_file_name == ".svn"
           dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
@@ -179,6 +188,8 @@ module RDoc
     # Parse each file on the command line, recursively entering directories.
 
     def parse_files(options)
+      @stats = Stats.new options.verbosity
+      
       files = options.files
       files = ["."] if files.empty?
 
@@ -187,27 +198,30 @@ module RDoc
       return [] if file_list.empty?
 
       file_info = []
-      width = file_list.map { |name| name.length }.max + 1
 
-      file_list.each do |fn|
-        $stderr.printf("\n%*s: ", width, fn) unless options.quiet
+      file_list.each do |filename|
+        @stats.add_file filename
 
         content = if RUBY_VERSION >= '1.9' then
-                    File.open(fn, "r:ascii-8bit") { |f| f.read }
+                    File.open(filename, "r:ascii-8bit") { |f| f.read }
                   else
-                    File.read fn
+                    File.read filename
                   end
 
-        if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
-          if enc = Encoding.find($1)
-            content.force_encoding(enc)
+        if defined? Encoding then
+          if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
+            if enc = ::Encoding.find($1)
+              content.force_encoding(enc)
+            end
           end
         end
 
-        top_level = TopLevel.new(fn)
-        parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
+        top_level = ::RDoc::TopLevel.new filename
+
+        parser = ::RDoc::Parser.for top_level, filename, content, options,
+                                    @stats
+
         file_info << parser.scan
-        @stats.num_files += 1
       end
 
       file_info
@@ -241,17 +255,19 @@ module RDoc
 
       file_info = parse_files @options
 
+      @options.title = "RDoc Documentation"
+
       if file_info.empty?
         $stderr.puts "\nNo newer files." unless @options.quiet
       else
-        gen = @options.generator
+        @gen = @options.generator
 
-        $stderr.puts "\nGenerating #{gen.key.upcase}..." unless @options.quiet
+        $stderr.puts "\nGenerating #{@gen.key.upcase}..." unless @options.quiet
 
-        require gen.file_name
+        require @gen.file_name
 
-        gen_class = ::RDoc::Generator.const_get gen.class_name
-        gen = gen_class.for @options
+        gen_class = ::RDoc::Generator.const_get @gen.class_name
+        @gen = gen_class.for @options
 
         pwd = Dir.pwd
 
@@ -259,7 +275,7 @@ module RDoc
 
         begin
           Diagram.new(file_info, @options).draw if @options.diagram
-          gen.generate(file_info)
+          @gen.generate(file_info)
           update_output_dir(".", start_time)
         ensure
           Dir.chdir(pwd)

data/lib/rdoc/ri.rb

@@ -1,4 +1,8 @@
 require 'rdoc'
 
-module RDoc::RI; end
+module RDoc::RI
+
+  class Error < RDoc::Error; end
+
+end
 

data/lib/rdoc/ri/descriptions.rb

@@ -2,11 +2,10 @@ require 'yaml'
 require 'rdoc/markup/fragments'
 require 'rdoc/ri'
 
-#--
+##
 # Descriptions are created by RDoc (in ri_generator) and written out in
 # serialized form into the documentation tree. ri then reads these to generate
 # the documentation
-#++
 
 class RDoc::RI::NamedThing
   attr_reader :name
@@ -83,7 +82,7 @@ class RDoc::RI::ModuleDescription < RDoc::RI::Description
   attr_accessor :constants
   attr_accessor :includes
 
-  # merge in another class desscription into this one
+  # merge in another class description into this one
   def merge_in(old)
     merge(@class_methods, old.class_methods)
     merge(@instance_methods, old.instance_methods)
@@ -94,8 +93,12 @@ class RDoc::RI::ModuleDescription < RDoc::RI::Description
       @comment = old.comment
     else
       unless old.comment.nil? or old.comment.empty? then
-        @comment << RDoc::Markup::Flow::RULE.new
-        @comment.concat old.comment
+        if @comment.nil? or @comment.empty? then
+          @comment = old.comment
+        else
+          @comment << RDoc::Markup::Flow::RULE.new
+          @comment.concat old.comment
+        end
       end
     end
   end

data/lib/rdoc/ri/driver.rb

@@ -11,6 +11,64 @@ require 'rdoc/markup/to_flow'
 
 class RDoc::RI::Driver
 
+  class Hash < ::Hash
+    def self.convert(hash)
+      hash = new.update hash
+
+      hash.each do |key, value|
+        hash[key] = case value
+                    when ::Hash then
+                      convert value
+                    when Array then
+                      value = value.map do |v|
+                        ::Hash === v ? convert(v) : v
+                      end
+                      value
+                    else
+                      value
+                    end
+      end
+
+      hash
+    end
+
+    def method_missing method, *args
+      self[method.to_s]
+    end
+
+    def merge_enums(other)
+      other.each do |k, v|
+        if self[k] then
+          case v
+          when Array then
+            # HACK dunno
+            if String === self[k] and self[k].empty? then
+              self[k] = v
+            else
+              self[k] += v
+            end
+          when Hash then
+            self[k].update v
+          else
+            # do nothing
+          end
+        else
+          self[k] = v
+        end
+      end
+    end
+  end
+
+  class Error < RDoc::RI::Error; end
+
+  class NotFoundError < Error
+    def message
+      "Nothing known about #{super}"
+    end
+  end
+
+  attr_accessor :homepath # :nodoc:
+
   def self.process_args(argv)
     options = {}
     options[:use_stdout] = !$stdout.tty?
@@ -234,7 +292,7 @@ Options may also be set in the 'RI' environment variable.
     @class_cache = if up_to_date then
                      load_cache_for @class_cache_name
                    else
-                     class_cache = {}
+                     class_cache = RDoc::RI::Driver::Hash.new
 
                      classes = map_dirs('**/cdesc*.yaml', :sys) { |f| Dir[f] }
                      populate_class_cache class_cache, classes
@@ -245,6 +303,9 @@ Options may also be set in the 'RI' environment variable.
                      populate_class_cache class_cache, classes, true
                      write_cache class_cache, class_cache_file_path
                    end
+
+    @class_cache = RDoc::RI::Driver::Hash.convert @class_cache
+    @class_cache
   end
 
   def class_cache_file_path
@@ -261,21 +322,29 @@ Options may also be set in the 'RI' environment variable.
 
   def display_class(name)
     klass = class_cache[name]
+    klass = RDoc::RI::Driver::Hash.convert klass
     @display.display_class_info klass, class_cache
   end
 
+  def get_info_for(arg)
+    @names = [arg]
+    run
+  end
+
   def load_cache_for(klassname)
     path = cache_file_for klassname
 
+    cache = nil
+
     if File.exist? path and
        File.mtime(path) >= File.mtime(class_cache_file_path) then
-      File.open path, 'rb' do |fp|
-        Marshal.load fp.read
+      open path, 'rb' do |fp|
+        cache = Marshal.load fp.read
       end
     else
       class_cache = nil
 
-      File.open class_cache_file_path, 'rb' do |fp|
+      open class_cache_file_path, 'rb' do |fp|
         class_cache = Marshal.load fp.read
       end
 
@@ -283,7 +352,7 @@ Options may also be set in the 'RI' environment variable.
       return nil unless klass
 
       method_files = klass["sources"]
-      cache = {}
+      cache = RDoc::RI::Driver::Hash.new
 
       sys_dir = @sys_dirs.first
       method_files.each do |f|
@@ -296,12 +365,45 @@ Options may also be set in the 'RI' environment variable.
           ext_path = f
           ext_path = "gem #{$1}" if f =~ %r%gems/[\d.]+/doc/([^/]+)%
           method["source_path"] = ext_path unless system_file
-          cache[name] = method
+          cache[name] = RDoc::RI::Driver::Hash.convert method
         end
       end
 
       write_cache cache, path
     end
+
+    RDoc::RI::Driver::Hash.convert cache
+  end
+
+  ##
+  # Finds the next ancestor of +orig_klass+ after +klass+.
+
+  def lookup_ancestor(klass, orig_klass)
+    cache = class_cache[orig_klass]
+
+    return nil unless cache
+
+    ancestors = [orig_klass]
+    ancestors.push(*cache.includes.map { |inc| inc['name'] })
+    ancestors << cache.superclass
+
+    ancestor = ancestors[ancestors.index(klass) + 1]
+
+    return ancestor if ancestor
+
+    lookup_ancestor klass, cache.superclass
+  end
+
+  ##
+  # Finds the method
+
+  def lookup_method(name, klass)
+    cache = load_cache_for klass
+    return nil unless cache
+
+    method = cache[name.gsub('.', '#')]
+    method = cache[name.gsub('.', '::')] unless method
+    method
   end
 
   def map_dirs(file_name, system=false)
@@ -318,6 +420,22 @@ Options may also be set in the 'RI' environment variable.
     dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact
   end
 
+  ##
+  # Extract the class and method name parts from +name+ like Foo::Bar#baz
+
+  def parse_name(name)
+    parts = name.split(/(::|\#|\.)/)
+
+    if parts[-2] != '::' or parts.last !~ /^[A-Z]/ then
+      meth = parts.pop
+      parts.pop
+    end
+
+    klass = parts.join
+
+    [klass, meth]
+  end
+
   def populate_class_cache(class_cache, classes, extension = false)
     classes.each do |cdesc|
       desc = read_yaml cdesc
@@ -337,6 +455,8 @@ Options may also be set in the 'RI' environment variable.
           desc["class_method_extensions"] = desc.delete "class_methods"
         end
 
+        klass = RDoc::RI::Driver::Hash.convert klass
+
         klass.merge_enums desc
         klass["sources"] << cdesc
       end
@@ -351,11 +471,6 @@ Options may also be set in the 'RI' environment variable.
     YAML.load data
   end
 
-  def get_info_for(arg)
-    @names = [arg]
-    run
-  end
-
   def run
     if @names.empty? then
       @display.list_known_classes class_cache.keys.sort
@@ -366,17 +481,26 @@ Options may also be set in the 'RI' environment variable.
           if class_cache.key? name then
             display_class name
           else
-            meth = nil
+            klass, = parse_name name
+
+            orig_klass = klass
+            orig_name = name
+
+            until klass == 'Kernel' do
+              method = lookup_method name, klass
 
-            parts = name.split(/::|\#|\./)
-            meth = parts.pop unless parts.last =~ /^[A-Z]/
-            klass = parts.join '::'
+              break method if method
+
+              ancestor = lookup_ancestor klass, orig_klass
+
+              break unless ancestor
+
+              name = name.sub klass, ancestor
+              klass = ancestor
+            end
+
+            raise NotFoundError, orig_name unless method
 
-            cache = load_cache_for klass
-            # HACK Does not support F.n
-            abort "Nothing known about #{name}" unless cache
-            method = cache[name.gsub(/\./, '#')]
-            abort "Nothing known about #{name}" unless method
             @display.display_method_info method
           end
         else
@@ -384,8 +508,9 @@ Options may also be set in the 'RI' environment variable.
             display_class name
           else
             methods = select_methods(/^#{name}/)
+
             if methods.size == 0
-              abort "Nothing known about #{name}"
+              raise NotFoundError, name
             elsif methods.size == 1
               @display.display_method_info methods.first
             else
@@ -395,6 +520,8 @@ Options may also be set in the 'RI' environment variable.
         end
       end
     end
+  rescue NotFoundError => e
+    abort e.message
   end
 
   def select_methods(pattern)
@@ -422,31 +549,3 @@ Options may also be set in the 'RI' environment variable.
 
 end
 
-class Hash # HACK don't add stuff to Hash.
-  def method_missing method, *args
-    self[method.to_s]
-  end
-
-  def merge_enums(other)
-    other.each do |k,v|
-      if self[k] then
-        case v
-        when Array then
-          # HACK dunno
-          if String === self[k] and self[k].empty? then
-            self[k] = v
-          else
-            self[k] += v
-          end
-        when Hash then
-          self[k].merge! v
-        else
-          # do nothing
-        end
-      else
-        self[k] = v
-      end
-    end
-  end
-end
-