rdoc 3.6.1 → 3.7

data/lib/rdoc/parser/ruby.rb

@@ -350,7 +350,9 @@ class RDoc::Parser::Ruby < RDoc::Parser
 
   def get_constant_with_optional_parens
     skip_tkspace false
+
     nest = 0
+
     while TkLPAREN === (tk = peek_tk) or TkfLPAREN === tk do
       get_tk
       skip_tkspace
@@ -631,7 +633,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
       cls.offset = offset
       cls.line   = line_no
 
-      cls.comment = comment if cls.document_self
+      cls.add_comment comment, @top_level if cls.document_self
 
       @top_level.add_to_classes_or_modules cls
       @stats.add_class cls
@@ -650,7 +652,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
           other.offset  = offset
           other.line    = line_no
 
-          other.comment = comment
+          other.add_comment comment, @top_level
         end
 
         # notify :nodoc: all if not a constant-named class/module
@@ -826,14 +828,19 @@ class RDoc::Parser::Ruby < RDoc::Parser
   ##
   # Parses an +include+ in +context+ with +comment+
 
-  def parse_include(context, comment)
+  def parse_include context, comment
     loop do
       skip_tkspace_comment
 
       name = get_constant_with_optional_parens
-      context.add_include RDoc::Include.new(name, comment) unless name.empty?
+
+      unless name.empty? then
+        incl = context.add_include RDoc::Include.new(name, comment)
+        incl.record_location @top_level
+      end
 
       return unless TkCOMMA === peek_tk
+
       get_tk
     end
   end
@@ -1231,7 +1238,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     mod.record_location @top_level
 
     read_documentation_modifiers mod, RDoc::CLASS_MODIFIERS
-    mod.comment = comment if mod.document_self
+    mod.add_comment comment, @top_level if mod.document_self
     parse_statements(mod)
 
     @top_level.add_to_classes_or_modules mod
@@ -1295,9 +1302,12 @@ class RDoc::Parser::Ruby < RDoc::Parser
           while TkCOMMENT === tk do
             comment << tk.text << "\n"
 
-            tk = get_tk        # this is the newline
-            skip_tkspace false # leading spaces
             tk = get_tk
+
+            if TkNL === tk then
+              skip_tkspace false # leading spaces
+              tk = get_tk
+            end
           end
 
           unless comment.empty? then
@@ -1313,7 +1323,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
           non_comment_seen = true
         end
 
-        unget_tk tk
+        unget_tk tk # TODO peek instead of get then unget
         keep_comment = true
 
       when TkCLASS then
@@ -1560,7 +1570,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
     else
       new_methods = []
 
-      case vis_type 
+      case vis_type
       when 'module_function' then
         args = parse_symbol_arg
         container.set_visibility_for args, :private, false

data/lib/rdoc/rdoc.rb

@@ -100,6 +100,14 @@ class RDoc::RDoc
     @current = rdoc
   end
 
+  ##
+  # Resets all internal state
+
+  def self.reset
+    RDoc::TopLevel.reset
+    RDoc::Parser::C.reset
+  end
+
   ##
   # Creates a new RDoc::RDoc instance.  Call #document to parse files and
   # generate documentation.
@@ -306,8 +314,12 @@ option)
   # Parses +filename+ and returns an RDoc::TopLevel
 
   def parse_file filename
+    if defined?(Encoding) then
+      encoding = @options.encoding
+      filename = filename.encode encoding
+    end
+
     @stats.add_file filename
-    encoding = @options.encoding if defined?(Encoding)
 
     content = RDoc::Encoding.read_file filename, encoding
 
@@ -396,8 +408,7 @@ The internal error was:
   # current directory, so make sure you're somewhere writable before invoking.
 
   def document options
-    RDoc::TopLevel.reset
-    RDoc::Parser::C.reset
+    RDoc::RDoc.reset
 
     if RDoc::Options === options then
       @options = options

data/lib/rdoc/ri/driver.rb

@@ -344,8 +344,8 @@ Options may also be set in the 'RI' environment variable.
     @stores   = []
 
     RDoc::RI::Paths.each(options[:use_system], options[:use_site],
-                                   options[:use_home], options[:use_gems],
-                                   *options[:extra_doc_dirs]) do |path, type|
+                         options[:use_home], options[:use_gems],
+                         *options[:extra_doc_dirs]) do |path, type|
       @doc_dirs << path
 
       store = RDoc::RI::Store.new path, type
@@ -456,9 +456,13 @@ Options may also be set in the 'RI' environment variable.
     out << RDoc::Markup::Heading.new(1, "#{name}:")
     out << RDoc::Markup::BlankLine.new
 
-    out.push(*methods.map do |method|
-      RDoc::Markup::Verbatim.new method
-    end)
+    if @use_stdout and !@interactive
+      out.push(*methods.map do |method|
+        RDoc::Markup::Verbatim.new method
+      end)
+    else
+      out << RDoc::Markup::IndentedParagraph.new(2, methods.join(', '))
+    end
 
     out << RDoc::Markup::BlankLine.new
   end
@@ -500,6 +504,70 @@ Options may also be set in the 'RI' environment variable.
   def class_cache # :nodoc:
   end
 
+  ##
+  # Builds a RDoc::Markup::Document from +found+, +klasess+ and +includes+
+
+  def class_document name, found, klasses, includes
+    also_in = []
+
+    out = RDoc::Markup::Document.new
+
+    add_class out, name, klasses
+
+    add_includes out, includes
+
+    found.each do |store, klass|
+      comment = klass.comment
+      class_methods    = store.class_methods[klass.full_name]
+      instance_methods = store.instance_methods[klass.full_name]
+      attributes       = store.attributes[klass.full_name]
+
+      if comment.empty? and !(instance_methods or class_methods) then
+        also_in << store
+        next
+      end
+
+      add_from out, store
+
+      unless comment.empty? then
+        out << RDoc::Markup::Rule.new(1)
+        out << comment
+      end
+
+      if class_methods or instance_methods or not klass.constants.empty? then
+        out << RDoc::Markup::Rule.new(1)
+      end
+
+      unless klass.constants.empty? then
+        out << RDoc::Markup::Heading.new(1, "Constants:")
+        out << RDoc::Markup::BlankLine.new
+        list = RDoc::Markup::List.new :NOTE
+
+        constants = klass.constants.sort_by { |constant| constant.name }
+
+        list.push(*constants.map do |constant|
+          parts = constant.comment.parts if constant.comment
+          parts << RDoc::Markup::Paragraph.new('[not documented]') if
+            parts.empty?
+
+          RDoc::Markup::ListItem.new(constant.name, *parts)
+        end)
+
+        out << list
+      end
+
+      add_method_list out, class_methods,    'Class methods'
+      add_method_list out, instance_methods, 'Instance methods'
+      add_method_list out, attributes,       'Attributes'
+
+      out << RDoc::Markup::BlankLine.new
+    end
+
+    add_also_in out, also_in
+
+    out
+  end
+
   ##
   # Hash mapping a known class or module to the stores it can be loaded from
 
@@ -519,6 +587,29 @@ Options may also be set in the 'RI' environment variable.
     @classes
   end
 
+  ##
+  # Returns the stores wherin +name+ is found along with the classes and
+  # includes that match it
+
+  def classes_and_includes_for name
+    klasses = []
+    includes = []
+
+    found = @stores.map do |store|
+      begin
+        klass = store.load_class name
+        klasses  << klass
+        includes << [klass.includes, store] if klass.includes
+        [store, klass]
+      rescue Errno::ENOENT
+      end
+    end.compact
+
+    includes.reject! do |modules,| modules.empty? end
+
+    [found, klasses, includes]
+  end
+
   ##
   # Completes +name+ based on the caches.  For Readline
 
@@ -532,8 +623,9 @@ Options may also be set in the 'RI' environment variable.
     klass_name = method ? name : klass
 
     if name !~ /#|\./ then
-      completions = klasses.grep(/^#{klass_name}[^:]*$/)
-      completions.concat klasses.grep(/^#{name}[^:]*$/) if name =~ /::$/
+      completions = klasses.grep(/^#{Regexp.escape klass_name}[^:]*$/)
+      completions.concat klasses.grep(/^#{Regexp.escape name}[^:]*$/) if
+        name =~ /::$/
 
       completions << klass if classes.key? klass # to complete a method name
     elsif selector then
@@ -577,79 +669,11 @@ Options may also be set in the 'RI' environment variable.
   def display_class name
     return if name =~ /#|\./
 
-    klasses = []
-    includes = []
-
-    found = @stores.map do |store|
-      begin
-        klass = store.load_class name
-        klasses  << klass
-        includes << [klass.includes, store] if klass.includes
-        [store, klass]
-      rescue Errno::ENOENT
-      end
-    end.compact
+    found, klasses, includes = classes_and_includes_for name
 
     return if found.empty?
 
-    also_in = []
-
-    includes.reject! do |modules,| modules.empty? end
-
-    out = RDoc::Markup::Document.new
-
-    add_class out, name, klasses
-
-    add_includes out, includes
-
-    found.each do |store, klass|
-      comment = klass.comment
-      class_methods    = store.class_methods[klass.full_name]
-      instance_methods = store.instance_methods[klass.full_name]
-      attributes       = store.attributes[klass.full_name]
-
-      if comment.empty? and !(instance_methods or class_methods) then
-        also_in << store
-        next
-      end
-
-      add_from out, store
-
-      unless comment.empty? then
-        out << RDoc::Markup::Rule.new(1)
-        out << comment
-      end
-
-      if class_methods or instance_methods or not klass.constants.empty? then
-        out << RDoc::Markup::Rule.new(1)
-      end
-
-      unless klass.constants.empty? then
-        out << RDoc::Markup::Heading.new(1, "Constants:")
-        out << RDoc::Markup::BlankLine.new
-        list = RDoc::Markup::List.new :NOTE
-
-        constants = klass.constants.sort_by { |constant| constant.name }
-
-        list.push(*constants.map do |constant|
-          parts = constant.comment.parts if constant.comment
-          parts << RDoc::Markup::Paragraph.new('[not documented]') if
-            parts.empty?
-
-          RDoc::Markup::ListItem.new(constant.name, *parts)
-        end)
-
-        out << list
-      end
-
-      add_method_list out, class_methods,    'Class methods'
-      add_method_list out, instance_methods, 'Instance methods'
-      add_method_list out, attributes,       'Attributes'
-
-      out << RDoc::Markup::BlankLine.new
-    end
-
-    add_also_in out, also_in
+    out = class_document name, found, klasses, includes
 
     display out
   end
@@ -664,32 +688,7 @@ Options may also be set in the 'RI' environment variable.
 
     filtered = filter_methods found, name
 
-    out = RDoc::Markup::Document.new
-
-    out << RDoc::Markup::Heading.new(1, name)
-    out << RDoc::Markup::BlankLine.new
-
-    filtered.each do |store, methods|
-      methods.each do |method|
-        out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
-
-        unless name =~ /^#{Regexp.escape method.parent_name}/ then
-          out << RDoc::Markup::Heading.new(3, "Implementation from #{method.parent_name}")
-        end
-        out << RDoc::Markup::Rule.new(1)
-
-        if method.arglists then
-          arglists = method.arglists.chomp.split "\n"
-          arglists = arglists.map { |line| line + "\n" }
-          out << RDoc::Markup::Verbatim.new(*arglists)
-          out << RDoc::Markup::Rule.new(1)
-        end
-
-        out << RDoc::Markup::BlankLine.new
-        out << method.comment
-        out << RDoc::Markup::BlankLine.new
-      end
-    end
+    out = method_document name, filtered
 
     display out
   end
@@ -731,6 +730,7 @@ Options may also be set in the 'RI' environment variable.
       display_name name
     end
   end
+
   ##
   # Expands abbreviated klass +klass+ into a fully-qualified class.  "Zl::Da"
   # will be expanded to Zlib::DataError.
@@ -998,6 +998,40 @@ Options may also be set in the 'RI' environment variable.
     found.reject do |path, methods| methods.empty? end
   end
 
+  ##
+  # Builds a RDoc::Markup::Document from +found+, +klasess+ and +includes+
+
+  def method_document name, filtered
+    out = RDoc::Markup::Document.new
+
+    out << RDoc::Markup::Heading.new(1, name)
+    out << RDoc::Markup::BlankLine.new
+
+    filtered.each do |store, methods|
+      methods.each do |method|
+        out << RDoc::Markup::Paragraph.new("(from #{store.friendly_path})")
+
+        unless name =~ /^#{Regexp.escape method.parent_name}/ then
+          out << RDoc::Markup::Heading.new(3, "Implementation from #{method.parent_name}")
+        end
+        out << RDoc::Markup::Rule.new(1)
+
+        if method.arglists then
+          arglists = method.arglists.chomp.split "\n"
+          arglists = arglists.map { |line| line + "\n" }
+          out << RDoc::Markup::Verbatim.new(*arglists)
+          out << RDoc::Markup::Rule.new(1)
+        end
+
+        out << RDoc::Markup::BlankLine.new
+        out << method.comment
+        out << RDoc::Markup::BlankLine.new
+      end
+    end
+
+    out
+  end
+
   ##
   # Returns the type of method (:both, :instance, :class) for +selector+
 

data/lib/rdoc/ri/store.rb

@@ -19,6 +19,8 @@ require 'fileutils'
 #      :modules          => [], # classes and modules in this store
 #      :ancestors        => {}, # class name => ancestor names
 #    }
+#--
+# TODO need to store the list of files and prune classes
 
 class RDoc::RI::Store
 
@@ -43,20 +45,27 @@ class RDoc::RI::Store
 
   attr_reader :cache
 
+  ##
+  # The encoding of the contents in the Store
+
+  attr_accessor :encoding
+
   ##
   # Creates a new Store of +type+ that will load or save to +path+
 
   def initialize path, type = nil
-    @dry_run = false
-    @type    = type
-    @path    = path
+    @dry_run  = false
+    @type     = type
+    @path     = path
+    @encoding = nil
 
     @cache = {
+      :ancestors        => {},
+      :attributes       => {},
       :class_methods    => {},
+      :encoding         => @encoding,
       :instance_methods => {},
-      :attributes       => {},
       :modules          => [],
-      :ancestors        => {},
     }
   end
 
@@ -106,6 +115,22 @@ class RDoc::RI::Store
     File.join @path, *klass_name.split('::')
   end
 
+  ##
+  # Removes empty items and ensures item in each collection are unique and
+  # sorted
+
+  def clean_cache_collection collection # :nodoc:
+    collection.each do |name, item|
+      if item.empty? then
+        collection.delete name
+      else
+        # HACK mongrel-1.1.5 documents its files twice
+        item.uniq!
+        item.sort!
+      end
+    end
+  end
+
   ##
   # Friendly rendition of #path
 
@@ -138,9 +163,29 @@ class RDoc::RI::Store
   # Loads cache file for this store
 
   def load_cache
+    #orig_enc = @encoding
+
     open cache_path, 'rb' do |io|
       @cache = Marshal.load io.read
     end
+
+    load_enc = @cache[:encoding]
+
+    # TODO this feature will be time-consuming to add:
+    # a) Encodings may be incompatible but transcodeable
+    # b) Need to warn in the appropriate spots, wherever they may be
+    # c) Need to handle cross-cache differences in encodings
+    # d) Need to warn when generating into a cache with diffent encodings
+    #
+    #if orig_enc and load_enc != orig_enc then
+    #  warn "Cached encoding #{load_enc} is incompatible with #{orig_enc}\n" \
+    #       "from #{path}/cache.ri" unless
+    #    Encoding.compatible? orig_enc, load_enc
+    #end
+
+    @encoding = load_enc unless @encoding
+
+    @cache
   rescue Errno::ENOENT
   end
 
@@ -192,17 +237,21 @@ class RDoc::RI::Store
   # Writes the cache file for this store
 
   def save_cache
-    # HACK mongrel-1.1.5 documents its files twice
-    @cache[:ancestors].       each do |_, m| m.uniq!; m.sort! end
-    @cache[:attributes].      each do |_, m| m.uniq!; m.sort! end
-    @cache[:class_methods].   each do |_, m| m.uniq!; m.sort! end
-    @cache[:instance_methods].each do |_, m| m.uniq!; m.sort! end
-    @cache[:modules].uniq!; @cache[:modules].sort!
+    clean_cache_collection @cache[:ancestors]
+    clean_cache_collection @cache[:attributes]
+    clean_cache_collection @cache[:class_methods]
+    clean_cache_collection @cache[:instance_methods]
+
+    @cache[:modules].uniq!
+    @cache[:modules].sort!
+    @cache[:encoding] = @encoding # this gets set twice due to assert_cache
 
     return if @dry_run
 
+    marshal = Marshal.dump @cache
+
     open cache_path, 'wb' do |io|
-      Marshal.dump @cache, io
+      io.write marshal
     end
   end
 
@@ -210,11 +259,13 @@ class RDoc::RI::Store
   # Writes the ri data for +klass+
 
   def save_class klass
-    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
+    full_name = klass.full_name
+
+    FileUtils.mkdir_p class_path(full_name) unless @dry_run
 
-    @cache[:modules] << klass.full_name
+    @cache[:modules] << full_name
 
-    path = class_file klass.full_name
+    path = class_file full_name
 
     begin
       disk_klass = nil
@@ -223,7 +274,7 @@ class RDoc::RI::Store
         disk_klass = Marshal.load io.read
       end
 
-      klass.merge disk_klass
+      klass = disk_klass.merge klass
     rescue Errno::ENOENT
     end
 
@@ -233,22 +284,52 @@ class RDoc::RI::Store
       String === ancestor ? ancestor : ancestor.full_name
     end
 
-    @cache[:ancestors][klass.full_name] ||= []
-    @cache[:ancestors][klass.full_name].push(*ancestors)
+    @cache[:ancestors][full_name] ||= []
+    @cache[:ancestors][full_name].push(*ancestors)
 
     attributes = klass.attributes.map do |attribute|
       "#{attribute.definition} #{attribute.name}"
     end
 
     unless attributes.empty? then
-      @cache[:attributes][klass.full_name] ||= []
-      @cache[:attributes][klass.full_name].push(*attributes)
+      @cache[:attributes][full_name] ||= []
+      @cache[:attributes][full_name].push(*attributes)
+    end
+
+    to_delete = []
+
+    unless klass.method_list.empty? then
+      @cache[:class_methods][full_name]    ||= []
+      @cache[:instance_methods][full_name] ||= []
+
+      class_methods, instance_methods =
+        klass.method_list.partition { |meth| meth.singleton }
+
+      class_methods    = class_methods.   map { |method| method.name }
+      instance_methods = instance_methods.map { |method| method.name }
+
+      old = @cache[:class_methods][full_name] - class_methods
+      to_delete.concat old.map { |method|
+        method_file full_name, "#{full_name}::#{method}"
+      }
+
+      old = @cache[:instance_methods][full_name] - instance_methods
+      to_delete.concat old.map { |method|
+        method_file full_name, "#{full_name}##{method}"
+      }
+
+      @cache[:class_methods][full_name]    = class_methods
+      @cache[:instance_methods][full_name] = instance_methods
     end
 
     return if @dry_run
 
+    FileUtils.rm_f to_delete
+
+    marshal = Marshal.dump klass
+
     open path, 'wb' do |io|
-      Marshal.dump klass, io
+      io.write marshal
     end
   end
 
@@ -256,20 +337,24 @@ class RDoc::RI::Store
   # Writes the ri data for +method+ on +klass+
 
   def save_method klass, method
-    FileUtils.mkdir_p class_path(klass.full_name) unless @dry_run
+    full_name = klass.full_name
+
+    FileUtils.mkdir_p class_path(full_name) unless @dry_run
 
     cache = if method.singleton then
               @cache[:class_methods]
             else
               @cache[:instance_methods]
             end
-    cache[klass.full_name] ||= []
-    cache[klass.full_name] << method.name
+    cache[full_name] ||= []
+    cache[full_name] << method.name
 
     return if @dry_run
 
-    open method_file(klass.full_name, method.full_name), 'wb' do |io|
-      Marshal.dump method, io
+    marshal = Marshal.dump method
+
+    open method_file(full_name, method.full_name), 'wb' do |io|
+      io.write marshal
     end
   end