rdoc 3.10.pre.3 → 3.10

data/lib/rdoc/markup/to_html_crossref.rb

@@ -131,6 +131,8 @@ class RDoc::Markup::ToHtmlCrossref < RDoc::Markup::ToHtml
 
     ref = @cross_reference.resolve name, text
 
+    text = ref.output_name @context if RDoc::MethodAttr === ref and not label
+
     case ref
     when String then
       ref

data/lib/rdoc/method_attr.rb

@@ -268,14 +268,27 @@ class RDoc::MethodAttr < RDoc::CodeObject
   # Full method/attribute name including namespace
 
   def full_name
-    @full_name || "#{parent_name}#{pretty_name}"
+    @full_name ||= "#{parent_name}#{pretty_name}"
   end
 
   ##
   # '::' for a class method/attribute, '#' for an instance method.
 
   def name_prefix
-    singleton ? '::' : '#'
+    @singleton ? '::' : '#'
+  end
+
+  ##
+  # Name for output to HTML.  For class methods the full name with a "." is
+  # used like +SomeClass.method_name+.  For instance methods the class name is
+  # used if +context+ does not match the parent.
+  #
+  # This is to help prevent people from using :: to call class methods.
+
+  def output_name context
+    return "#{name_prefix}#{@name}" if context == parent
+
+    "#{parent_name}#{@singleton ? '.' : '#'}#{@name}"
   end
 
   ##

data/lib/rdoc/options.rb

@@ -2,6 +2,29 @@ require 'optparse'
 
 ##
 # RDoc::Options handles the parsing and storage of options
+#
+# == Saved Options
+#
+# You can save some options like the markup format in the
+# <tt>.rdoc_options</tt> file in your gem.  The easiest way to do this is:
+#
+#   rdoc --markup tomdoc --write-options
+#
+# Which will automatically create the file and fill it with the options you
+# specified.
+#
+# The following options will not be saved since they interfere with the user's
+# preferences or with the normal operation of RDoc:
+#
+# * +--coverage-report+
+# * +--dry-run+
+# * +--encoding+
+# * +--force-update+
+# * +--format+
+# * +--pipe+
+# * +--quiet+
+# * +--template+
+# * +--verbose+
 
 class RDoc::Options
 
@@ -22,11 +45,43 @@ class RDoc::Options
     '--ri-system'     => 'Ruby installers use other techniques',
   }
 
+  ##
+  # RDoc options ignored (or handled specially) by --write-options
+
+  SPECIAL = %w[
+    coverage_report
+    dry_run
+    encoding
+    files
+    force_output
+    force_update
+    generator
+    generator_name
+    generator_options
+    generators
+    op_dir
+    option_parser
+    pipe
+    rdoc_include
+    static_path
+    stylesheet_url
+    template
+    template_dir
+    update_output_dir
+    verbosity
+    write_options
+  ]
+
   ##
   # Path option validator for OptionParser
 
   Path = Object.new
 
+  ##
+  # Array of Paths option validator for OptionParser
+
+  PathArray = Object.new
+
   ##
   # Template option validator for OptionParser
 
@@ -45,7 +100,7 @@ class RDoc::Options
   ##
   # Encoding of output where.  This is set via --encoding.
 
-  attr_accessor :encoding if Object.const_defined? :Encoding
+  attr_accessor :encoding
 
   ##
   # Files matching this pattern will be excluded
@@ -78,6 +133,11 @@ class RDoc::Options
 
   attr_accessor :generator
 
+  ##
+  # For #==
+
+  attr_reader :generator_name # :nodoc:
+
   ##
   # Loaded generator options.  Used to prevent --help from loading the same
   # options multiple times.
@@ -185,8 +245,13 @@ class RDoc::Options
   attr_accessor :visibility
 
   def initialize # :nodoc:
+    init_ivars
+  end
+
+  def init_ivars # :nodoc:
     @dry_run = false
     @exclude = []
+    @files = nil
     @force_output = false
     @force_update = true
     @generator = nil
@@ -203,7 +268,7 @@ class RDoc::Options
     @rdoc_include = []
     @show_hash = false
     @static_path = []
-    @stylesheet_url = nil
+    @stylesheet_url = nil # TODO remove in RDoc 4
     @tab_width = 8
     @template = nil
     @template_dir = nil
@@ -212,15 +277,67 @@ class RDoc::Options
     @verbosity = 1
     @visibility = :protected
     @webcvs = nil
+    @write_options = false
 
     if Object.const_defined? :Encoding then
       @encoding = Encoding.default_external
       @charset = @encoding.to_s
     else
+      @encoding = nil
       @charset = 'UTF-8'
     end
   end
 
+  def init_with map # :nodoc:
+    init_ivars
+
+    encoding = map['encoding']
+    @encoding = if Object.const_defined? :Encoding then
+                  encoding ? Encoding.find(encoding) : encoding
+                end
+
+    @charset        = map['charset']
+    @exclude        = map['exclude']
+    @generator_name = map['generator_name']
+    @hyperlink_all  = map['hyperlink_all']
+    @line_numbers   = map['line_numbers']
+    @main_page      = map['main_page']
+    @markup         = map['markup']
+    @op_dir         = map['op_dir']
+    @show_hash      = map['show_hash']
+    @tab_width      = map['tab_width']
+    @template_dir   = map['template_dir']
+    @title          = map['title']
+    @visibility     = map['visibility']
+    @webcvs         = map['webcvs']
+
+    @rdoc_include = sanitize_path map['rdoc_include']
+    @static_path  = sanitize_path map['static_path']
+  end
+
+  def yaml_initialize tag, map # :nodoc:
+    init_with map
+  end
+
+  def == other # :nodoc:
+    self.class === other and
+      @encoding       == other.encoding       and
+      @generator_name == other.generator_name and
+      @hyperlink_all  == other.hyperlink_all  and
+      @line_numbers   == other.line_numbers   and
+      @main_page      == other.main_page      and
+      @markup         == other.markup         and
+      @op_dir         == other.op_dir         and
+      @rdoc_include   == other.rdoc_include   and
+      @show_hash      == other.show_hash      and
+      @static_path    == other.static_path    and
+      @tab_width      == other.tab_width      and
+      @template       == other.template       and
+      @title          == other.title          and
+      @visibility     == other.visibility     and
+      @webcvs         == other.webcvs
+  end
+
   ##
   # Check that the files on the command line exist
 
@@ -261,6 +378,24 @@ class RDoc::Options
     @title ||= string
   end
 
+  ##
+  # For dumping YAML
+
+  def encode_with coder # :nodoc:
+    encoding = @encoding ? @encoding.name : nil
+
+    coder.add 'encoding', encoding
+    coder.add 'static_path',  sanitize_path(@static_path)
+    coder.add 'rdoc_include', sanitize_path(@rdoc_include)
+
+    ivars = instance_variables.map { |ivar| ivar.to_s[1..-1] }
+    ivars -= SPECIAL
+
+    ivars.sort.each do |ivar|
+      coder.add ivar, instance_variable_get("@#{ivar}")
+    end
+  end
+
   ##
   # Completes any unfinished option setup business such as filtering for
   # existent files, creating a regexp for #exclude and setting a default
@@ -321,7 +456,7 @@ class RDoc::Options
   ##
   # Parses command line options.
 
-  def parse(argv)
+  def parse argv
     ignore_invalid = true
 
     argv.insert(0, *ENV['RDOCOPT'].split) if ENV['RDOCOPT']
@@ -382,7 +517,7 @@ Usage: #{opt.program_name} [options] [names...]
         template_dir = template_dir_for template
 
         unless template_dir then
-          warn "could not find template #{template}"
+          $stderr.puts "could not find template #{template}"
           nil
         else
           [template, template_dir]
@@ -397,6 +532,20 @@ Usage: #{opt.program_name} [options] [names...]
         directory
       end
 
+      opt.accept PathArray do |directories,|
+        directories = if directories then
+                        directories.split(',').map { |d| d unless d.empty? }
+                      end
+
+        directories.map do |directory|
+          directory = File.expand_path directory
+
+          raise OptionParser::InvalidArgument unless File.exist? directory
+
+          directory
+        end
+      end
+
       opt.separator nil
       opt.separator "Parsing options:"
       opt.separator nil
@@ -511,7 +660,7 @@ Usage: #{opt.program_name} [options] [names...]
 
       opt.separator nil
 
-      opt.on("--include=DIRECTORIES", "-i", Array,
+      opt.on("--include=DIRECTORIES", "-i", PathArray,
              "Set (or add to) the list of directories to",
              "be searched when satisfying :include:",
              "requests. Can be used more than once.") do |value|
@@ -666,32 +815,52 @@ Usage: #{opt.program_name} [options] [names...]
       opt.separator "Generic options:"
       opt.separator nil
 
+      opt.on("--write-options",
+             "Write .rdoc_options to the current",
+             "directory with the given options.  Not all",
+             "options will be used.  See RDoc::Options",
+             "for details.") do |value|
+        @write_options = true
+      end
+
+      opt.separator nil
+
       opt.on("--[no-]dry-run",
              "Don't write any files") do |value|
         @dry_run = value
       end
 
+      opt.separator nil
+
       opt.on("-D", "--[no-]debug",
              "Displays lots on internal stuff.") do |value|
         $DEBUG_RDOC = value
       end
 
+      opt.separator nil
+
       opt.on("--[no-]ignore-invalid",
              "Ignore invalid options and continue",
              "(default true).") do |value|
         ignore_invalid = value
       end
 
+      opt.separator nil
+
       opt.on("--quiet", "-q",
              "Don't show progress as we parse.") do |value|
         @verbosity = 0
       end
 
+      opt.separator nil
+
       opt.on("--verbose", "-v",
              "Display extra progress as RDoc parses") do |value|
         @verbosity = 2
       end
 
+      opt.separator nil
+
       opt.on("--help",
              "Display this help") do
         RDoc::RDoc::GENERATORS.each_key do |generator|
@@ -757,6 +926,13 @@ Usage: #{opt.program_name} [options] [names...]
     @files = argv.dup
 
     finish
+
+    if @write_options then
+      write_options
+      exit
+    end
+
+    self
   end
 
   ##
@@ -773,6 +949,20 @@ Usage: #{opt.program_name} [options] [names...]
     @verbosity = bool ? 0 : 1
   end
 
+  ##
+  # Removes directories from +path+ that are outside the current directory
+
+  def sanitize_path path
+    require 'pathname'
+    dot = Pathname.new('.').expand_path
+
+    path.reject do |item|
+      path = Pathname.new(item).expand_path
+      relative = path.relative_path_from(dot).to_s
+      relative.start_with? '..'
+    end
+  end
+
   ##
   # Set up an output generator for the named +generator_name+.
   #
@@ -812,5 +1002,39 @@ Usage: #{opt.program_name} [options] [names...]
     end
   end
 
+  ##
+  # This is compatibility code for syck
+
+  def to_yaml opts = {} # :nodoc:
+    return super if YAML.const_defined?(:ENGINE) and not YAML::ENGINE.syck?
+
+    YAML.quick_emit self, opts do |out|
+      out.map taguri, to_yaml_style do |map|
+        encode_with map
+      end
+    end
+  end
+
+  ##
+  # Displays a warning using Kernel#warn if we're being verbose
+
+  def warn message
+    super message if @verbosity > 1
+  end
+
+  ##
+  # Writes the YAML file .rdoc_options to the current directory containing the
+  # parsed options.
+
+  def write_options
+    RDoc.load_yaml
+
+    open '.rdoc_options', 'w' do |io|
+      io.set_encoding Encoding::UTF_8 if Object.const_defined? :Encoding
+
+      YAML.dump self, io
+    end
+  end
+
 end
 

data/lib/rdoc/parser/c.rb

@@ -165,7 +165,7 @@ class RDoc::Parser::C < RDoc::Parser
       class_name = @known_classes[var_name]
 
       unless class_name then
-        warn "Enclosing class/module %p for alias %s %s not known" % [
+        @options.warn "Enclosing class/module %p for alias %s %s not known" % [
           var_name, new_name, old_name]
         next
       end
@@ -230,6 +230,17 @@ class RDoc::Parser::C < RDoc::Parser
       handle_class_module(var_name, "class", class_name, parent, nil)
     end
 
+    @content.scan(/([\w\.]+)\s* = \s*rb_struct_define_without_accessor\s*
+              \(
+                 \s*"(\w+)",  # Class name
+                 \s*(\w+),    # Parent class
+                 \s*\w+,      # Allocation function
+                 (\s*"\w+",)* # Attributes
+                 \s*NULL
+              \)/mx) do |var_name, class_name, parent|
+      handle_class_module(var_name, "class", class_name, parent, nil)
+    end
+
     @content.scan(/(\w+)\s*=\s*boot_defclass\s*\(\s*"(\w+?)",\s*(\w+?)\s*\)/) do
       |var_name, class_name, parent|
       parent = nil if parent == "0"
@@ -485,7 +496,7 @@ class RDoc::Parser::C < RDoc::Parser
 
       return body if body
 
-      warn "No definition for #{meth_name}" if @options.verbosity > 1
+      @options.warn "No definition for #{meth_name}"
       false
     else # No body, but might still have an override comment
       comment = find_override_comment class_name, meth_obj
@@ -497,7 +508,7 @@ class RDoc::Parser::C < RDoc::Parser
 
         ''
       else
-        warn "No definition for #{meth_name}" if @options.verbosity > 1
+        @options.warn "No definition for #{meth_name}"
         false
       end
     end
@@ -676,7 +687,8 @@ class RDoc::Parser::C < RDoc::Parser
       end
 
       unless enclosure then
-        warn "Enclosing class/module '#{in_module}' for #{type} #{class_name} not known"
+        @options.warn "Enclosing class/module '#{in_module}' for " \
+                      "#{type} #{class_name} not known"
         return
       end
     else
@@ -733,7 +745,7 @@ class RDoc::Parser::C < RDoc::Parser
     class_obj = find_class var_name, class_name
 
     unless class_obj then
-      warn "Enclosing class/module #{const_name.inspect} not known"
+      @options.warn "Enclosing class/module #{const_name.inspect} not known"
       return
     end
 
@@ -820,7 +832,8 @@ class RDoc::Parser::C < RDoc::Parser
         if File.exist? file_name then
           file_content = (@@known_bodies[file_name] ||= File.read(file_name))
         else
-          warn "unknown source #{source_file} for #{meth_name} in #{@file_name}"
+          @options.warn "unknown source #{source_file} for " \
+                        "#{meth_name} in #{@file_name}"
         end
       else
         file_content = @content