rdoc 4.0.0.preview2 → 4.0.0.preview2.1

data/lib/rdoc/ri/driver.rb

@@ -1331,12 +1331,16 @@ The ri pager can be set with the 'RI_PAGER' environment variable or the
     elsif parts.length == 2 or parts.last =~ /::|#|\./ then
       type = parts.pop
       meth = nil
+    elsif parts[1] == ':' then
+      klass = parts.shift
+      type  = parts.shift
+      meth  = parts.join
     elsif parts[-2] != '::' or parts.last !~ /^[A-Z]/ then
       meth = parts.pop
       type = parts.pop
     end
 
-    klass = parts.join
+    klass ||= parts.join
 
     [klass, type, meth]
   end

data/lib/rdoc/ruby_lex.rb

@@ -857,7 +857,7 @@ class RDoc::RubyLex
   end
 
   IDENT_RE = if defined? Encoding then
-               /[\w\u0080-\uFFFF]/u
+               eval '/[\w\u{0080}-\u{FFFFF}]/u' # 1.8 can't parse \u{}
              else
                /[\w\x80-\xFF]/
              end

data/lib/rdoc/rubygems_hook.rb

@@ -68,10 +68,12 @@ class RDoc::RubygemsHook
 
   ##
   # Creates a new documentation generator for +spec+.  RDoc and ri data
-  # generation can be disabled through +generate_rdoc+ and +generate_ri+
-  # respectively.
+  # generation can be enabled or disabled through +generate_rdoc+ and
+  # +generate_ri+ respectively.
+  #
+  # Only +generate_ri+ is enabled by default.
 
-  def initialize spec, generate_rdoc = true, generate_ri = true
+  def initialize spec, generate_rdoc = false, generate_ri = true
     @doc_dir   = spec.doc_dir
     @force     = false
     @rdoc      = nil
@@ -139,13 +141,11 @@ class RDoc::RubygemsHook
 
     setup
 
-    options = ::RDoc::Options.new
-    options.default_title = "#{@spec.full_name} Documentation"
-    options.files = []
-    options.files.concat @spec.require_paths
-    options.files.concat @spec.extra_rdoc_files
+    options = nil
 
     args = @spec.rdoc_options
+    args.concat @spec.require_paths
+    args.concat @spec.extra_rdoc_files
 
     case config_args = Gem.configuration[:rdoc]
     when String then
@@ -155,7 +155,13 @@ class RDoc::RubygemsHook
     end
 
     delete_legacy_args args
-    options.parse args
+
+    Dir.chdir @spec.full_gem_path do
+      options = ::RDoc::Options.new
+      options.default_title = "#{@spec.full_name} Documentation"
+      options.parse args
+    end
+
     options.quiet = !Gem.configuration.really_verbose
 
     @rdoc = new_rdoc
@@ -167,7 +173,7 @@ class RDoc::RubygemsHook
     store.main     = options.main_page
     store.title    = options.title
 
-    @rdoc.store = RDoc::Store.new
+    @rdoc.store = store
 
     say "Parsing documentation for #{@spec.full_name}"
 

data/lib/rdoc/servlet.rb

@@ -2,21 +2,60 @@ require 'rdoc'
 require 'time'
 require 'webrick'
 
+##
+# This is a WEBrick servlet that allows you to browse ri documentation.
+#
+# You can show documentation through either `ri --server` or, with RubyGems
+# 2.0 or newer, `gem server`.  For ri, the server runs on port 8214 by
+# default.  For RubyGems the server runs on port 8808 by default.
+#
+# You can use this servlet in your own project by mounting it on a WEBrick
+# server:
+#
+#   require 'webrick'
+#
+#   server = WEBrick::HTTPServer.new Port: 8000
+#
+#   server.mount '/', RDoc::Servlet
+#
+# If you want to mount the servlet some other place than the root, provide the
+# base path when mounting:
+#
+#   server.mount '/rdoc', RDoc::Servlet, '/rdoc'
+
 class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
 
   @server_stores = Hash.new { |hash, server| hash[server] = {} }
   @cache         = Hash.new { |hash, store|  hash[store]  = {} }
 
+  ##
+  # Maps an asset type to its path on the filesystem
+
   attr_reader :asset_dirs
 
+  ##
+  # An RDoc::Options instance used for rendering options
+
   attr_reader :options
 
-  def self.get_instance server, *options
+  ##
+  # Creates an instance of this servlet that shares cached data between
+  # requests.
+
+  def self.get_instance server, *options # :nodoc:
     stores = @server_stores[server]
 
     new server, stores, @cache, *options
   end
 
+  ##
+  # Creates a new WEBrick servlet.
+  #
+  # Use +mount_path+ when mounting the servlet somewhere other than /.
+  #
+  # +server+ is provided automatically by WEBrick when mounting.  +stores+ and
+  # +cache+ are provided automatically by the servlet.
+
   def initialize server, stores, cache, mount_path = nil
     super server
 
@@ -44,6 +83,9 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     }
   end
 
+  ##
+  # Serves the asset at the path in +req+ for +generator_name+ via +res+.
+
   def asset generator_name, req, res
     asset_dir = @asset_dirs[generator_name]
 
@@ -60,6 +102,9 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
                        end
   end
 
+  ##
+  # GET request entry point.  Fills in +res+ for the path, etc. in +req+.
+
   def do_GET req, res
     req.path.sub!(/^#{Regexp.escape @mount_path}/o, '') if @mount_path
 
@@ -82,6 +127,13 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     error e, req, res
   end
 
+  ##
+  # Fills in +res+ with the class, module or page for +req+ from +store+.
+  #
+  # +path+ is relative to the mount_path and is used to determine the class,
+  # module or page name (/RDoc/Servlet.html becomes RDoc::Servlet).
+  # +generator+ is used to create the page.
+
   def documentation_page store, generator, path, req, res
     name = path.sub(/.html$/, '').gsub '/', '::'
 
@@ -94,6 +146,10 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     end
   end
 
+  ##
+  # Creates the JSON search index on +res+ for the given +store+.  +generator+
+  # must respond to \#json_index to build.  +req+ is ignored.
+
   def documentation_search store, generator, req, res
     json_index = @cache[store].fetch :json_index do
       @cache[store][:json_index] =
@@ -104,6 +160,10 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     res.body = "var search_data = #{json_index}"
   end
 
+  ##
+  # Returns the RDoc::Store and path relative to +mount_path+ for
+  # documentation at +path+.
+
   def documentation_source path
     _, source_name, path = path.split '/', 3
 
@@ -119,8 +179,11 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
     return store, path
   end
 
-  def error e, req, res
-    backtrace = e.backtrace.join "\n"
+  ##
+  # Generates an error page for the +exception+ while handling +req+ on +res+.
+
+  def error exception, req, res
+    backtrace = exception.backtrace.join "\n"
 
     res.content_type = 'text/html'
     res.status = 500
@@ -130,7 +193,7 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
 <head>
 <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
 
-<title>Error - #{ERB::Util.html_escape e.class}</title>
+<title>Error - #{ERB::Util.html_escape exception.class}</title>
 
 <link type="text/css" media="screen" href="#{@mount_path}/rdoc.css" rel="stylesheet">
 </head>
@@ -138,10 +201,17 @@ class RDoc::Servlet < WEBrick::HTTPServlet::AbstractServlet
 <h1>Error</h1>
 
 <p>While processing <code>#{ERB::Util.html_escape req.request_uri}</code> the
-RDoc server has encountered a <code>#{ERB::Util.html_escape e.class}</code>
+RDoc (#{ERB::Util.html_escape RDoc::VERSION}) server has encountered a
+<code>#{ERB::Util.html_escape exception.class}</code>
 exception:
 
-<pre>#{ERB::Util.html_escape e.message}</pre>
+<pre>#{ERB::Util.html_escape exception.message}</pre>
+
+<p>Please report this to the
+<a href="https://github.com/rdoc/rdoc/issues">RDoc issues tracker</a>.  Please
+include the RDoc version, the URI above and exception class, message and
+backtrace.  If you're viewing a gem's documentation, include the gem name and
+version.  If you're viewing Ruby's documentation, include the version of ruby.
 
 <p>Backtrace:
 
@@ -152,6 +222,9 @@ exception:
     BODY
   end
 
+  ##
+  # Instantiates a Darkfish generator for +store+
+
   def generator_for store
     generator = RDoc::Generator::Darkfish.new store, @options
     generator.file_output = false
@@ -168,6 +241,11 @@ exception:
     generator
   end
 
+  ##
+  # Handles the If-Modified-Since HTTP header on +req+ for +path+.  If the
+  # file has not been modified a Not Modified response is returned.  If the
+  # file has been modified a Last-Modified header is added to +res+.
+
   def if_modified_since req, res, path = nil
     last_modified = File.stat(path).mtime if path
 
@@ -183,6 +261,14 @@ exception:
     end
   end
 
+  ##
+  # Returns an Array of installed documentation.
+  #
+  # Each entry contains the documentation name (gem name, 'Ruby
+  # Documentation', etc.), the path relative to the mount point, whether the
+  # documentation exists, the type of documentation (See RDoc::RI::Paths#each)
+  # and the filesystem to the RDoc::Store for the documentation.
+
   def installed_docs
     ri_paths.map do |path, type|
       store = RDoc::Store.new path, type
@@ -202,15 +288,24 @@ exception:
     end
   end
 
+  ##
+  # Returns a 404 page built by +generator+ for +req+ on +res+.
+
   def not_found generator, req, res
     res.body = generator.generate_servlet_not_found req.path
     res.status = 404
   end
 
+  ##
+  # Enumerates the ri paths.  See RDoc::RI::Paths#each
+
   def ri_paths &block
     RDoc::RI::Paths.each true, true, true, :all, &block
   end
 
+  ##
+  # Generates the root page on +res+.  +req+ is ignored.
+
   def root req, res
     generator = RDoc::Generator::Darkfish.new nil, @options
 
@@ -219,6 +314,9 @@ exception:
     res.content_type = 'text/html'
   end
 
+  ##
+  # Generates a search index for the root page on +res+.  +req+ is ignored.
+
   def root_search req, res
     search_index = []
     info         = []
@@ -259,6 +357,10 @@ exception:
     res.content_type = 'application/javascript'
   end
 
+  ##
+  # Displays documentation for +req+ on +res+, whether that be HTML or some
+  # asset.
+
   def show_documentation req, res
     store, path = documentation_source req.path
 
@@ -280,6 +382,9 @@ exception:
     res.content_type ||= 'text/html'
   end
 
+  ##
+  # Returns an RDoc::Store for the given +source_name+ ('ruby' or a gem name).
+
   def store_for source_name
     case source_name
     when 'ruby' then

data/lib/rdoc/store.rb

@@ -59,7 +59,7 @@ class RDoc::Store
       @name  = name
     end
 
-    def message
+    def message # :nodoc:
       "store at #{@store.path} missing file #{@file} for #{@name}"
     end
 
@@ -69,7 +69,19 @@ class RDoc::Store
   # Stores the name of the C variable a class belongs to.  This helps wire up
   # classes defined from C across files.
 
-  attr_reader :c_enclosure_classes
+  attr_reader :c_enclosure_classes # :nodoc:
+
+  attr_reader :c_enclosure_names # :nodoc:
+
+  ##
+  # Maps C variables to class or module names for each parsed C file.
+
+  attr_reader :c_class_variables
+
+  ##
+  # Maps C variables to singleton class names for each parsed C file.
+
+  attr_reader :c_singleton_class_variables
 
   ##
   # If true this Store will not write any files
@@ -114,15 +126,17 @@ class RDoc::Store
     @type     = type
 
     @cache = {
-      :ancestors        => {},
-      :attributes       => {},
-      :class_methods    => {},
-      :encoding         => @encoding,
-      :instance_methods => {},
-      :main             => nil,
-      :modules          => [],
-      :pages            => [],
-      :title            => nil,
+      :ancestors                   => {},
+      :attributes                  => {},
+      :class_methods               => {},
+      :c_class_variables           => {},
+      :c_singleton_class_variables => {},
+      :encoding                    => @encoding,
+      :instance_methods            => {},
+      :main                        => nil,
+      :modules                     => [],
+      :pages                       => [],
+      :title                       => nil,
     }
 
     @classes_hash = {}
@@ -130,11 +144,34 @@ class RDoc::Store
     @files_hash   = {}
 
     @c_enclosure_classes = {}
+    @c_enclosure_names   = {}
+
+    @c_class_variables           = {}
+    @c_singleton_class_variables = {}
 
     @unique_classes = nil
     @unique_modules = nil
   end
 
+  ##
+  # Adds +module+ as an enclosure (namespace) for the given +variable+ for C
+  # files.
+
+  def add_c_enclosure variable, namespace
+    @c_enclosure_classes[variable] = namespace
+  end
+
+  ##
+  # Adds C variables from an RDoc::Parser::C
+
+  def add_c_variables c_parser
+    filename = c_parser.top_level.relative_name
+
+    @c_class_variables[filename] = make_variable_map c_parser.classes
+
+    @c_singleton_class_variables[filename] = c_parser.singleton_classes
+  end
+
   ##
   # Adds the file with +name+ as an RDoc::TopLevel to the store.  Returns the
   # created RDoc::TopLevel.
@@ -304,6 +341,28 @@ class RDoc::Store
     @files_hash
   end
 
+  ##
+  # Finds the enclosure (namespace) for the given C +variable+.
+
+  def find_c_enclosure variable
+    @c_enclosure_classes.fetch variable do
+      break unless name = @c_enclosure_names[variable]
+
+      mod = find_class_or_module name
+
+      unless mod then
+        loaded_mod = load_class_data name
+
+        file = loaded_mod.in_files.first
+        file.store = self
+
+        mod = file.add_module RDoc::NormalModule, name
+      end
+
+      @c_enclosure_classes[variable] = mod
+    end
+  end
+
   ##
   # Finds the class with +name+ in all discovered classes
 
@@ -500,22 +559,26 @@ class RDoc::Store
 
     @encoding = load_enc unless @encoding
 
-    @cache[:pages] ||= []
-    @cache[:main]  ||= nil
+    @cache[:pages]                       ||= []
+    @cache[:main]                        ||= nil
+    @cache[:c_class_variables]           ||= {}
+    @cache[:c_singleton_class_variables] ||= {}
+
+    @cache[:c_class_variables].each do |_, map|
+      map.each do |variable, name|
+        @c_enclosure_names[variable] = name
+      end
+    end
 
     @cache
   rescue Errno::ENOENT
   end
 
   ##
-  # Loads ri data for +klass_name+
+  # Loads ri data for +klass_name+ and hooks it up to this store.
 
   def load_class klass_name
-    file = class_file klass_name
-
-    obj = open file, 'rb' do |io|
-      Marshal.load io.read
-    end
+    obj = load_class_data klass_name
 
     obj.store = self
 
@@ -525,6 +588,17 @@ class RDoc::Store
     when RDoc::NormalModule then
       @modules_hash[klass_name] = obj
     end
+  end
+
+  ##
+  # Loads ri data for +klass_name+
+
+  def load_class_data klass_name
+    file = class_file klass_name
+
+    open file, 'rb' do |io|
+      Marshal.load io.read
+    end
   rescue Errno::ENOENT => e
     error = MissingFileError.new(self, file, klass_name)
     error.set_backtrace e.backtrace
@@ -583,6 +657,20 @@ class RDoc::Store
     @cache[:main] = page
   end
 
+  ##
+  # Converts the variable => ClassModule map +variables+ from a C parser into 
+  # a variable => class name map.
+
+  def make_variable_map variables
+    map = {}
+
+    variables.each { |variable, class_module|
+      map[variable] = class_module.full_name
+    }
+
+    map
+  end
+
   ##
   # Path to the ri data for +method_name+ in +klass_name+
 
@@ -688,6 +776,9 @@ class RDoc::Store
 
     @cache[:encoding] = @encoding # this gets set twice due to assert_cache
 
+    @cache[:c_class_variables].merge!           @c_class_variables
+    @cache[:c_singleton_class_variables].merge! @c_singleton_class_variables
+
     return if @dry_run
 
     marshal = Marshal.dump @cache