rdoc 2.4.3 → 2.5

data/lib/rdoc/task.rb

@@ -1,3 +1,4 @@
+#--
 # Copyright (c) 2003, 2004 Jim Weirich, 2009 Eric Hodel
 #
 # Permission is hereby granted, free of charge, to any person obtaining
@@ -18,6 +19,7 @@
 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
 
 require 'rubygems'
 begin
@@ -39,14 +41,14 @@ require 'rake/tasklib'
 #
 # The RDoc::Task will create the following targets:
 #
-# [<b><em>rdoc</em></b>]
+# [rdoc]
 #   Main task for this RDoc task.
 #
-# [<b>:clobber_<em>rdoc</em></b>]
+# [clobber_rdoc]
 #   Delete all the rdoc files.  This target is automatically added to the main
 #   clobber target.
 #
-# [<b>:re<em>rdoc</em></b>]
+# [rerdoc]
 #   Rebuild the rdoc files from scratch, even if they are not out of date.
 #
 # Simple Example:
@@ -83,7 +85,7 @@ require 'rake/tasklib'
 #   RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
 #                  :rerdoc => "rdoc:force")
 #
-# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc_clean</tt> and
+# This will create the tasks <tt>:rdoc</tt>, <tt>:rdoc:clean</tt> and
 # <tt>:rdoc:force</tt>.
 
 class RDoc::Task < Rake::TaskLib
@@ -149,7 +151,6 @@ class RDoc::Task < Rake::TaskLib
     @main = nil
     @title = nil
     @template = nil
-    @external = false
     @options = []
     yield self if block_given?
     define
@@ -159,17 +160,13 @@ class RDoc::Task < Rake::TaskLib
   # Create the tasks defined by this task lib.
 
   def define
-    if rdoc_task_name != "rdoc" then
-      desc "Build the RDoc HTML Files"
-    else
-      desc "Build the #{rdoc_task_name} HTML Files"
-    end
+    desc "Build the RDoc HTML files"
     task rdoc_task_name
 
-    desc "Force a rebuild of the RDoc files"
+    desc "Force rebuild RDoc HTML files"
     task rerdoc_task_name => [clobber_task_name, rdoc_task_name]
 
-    desc "Remove RDoc products"
+    desc "Remove RDoc HTML files"
     task clobber_task_name do
       rm_r rdoc_dir rescue nil
     end
@@ -177,48 +174,35 @@ class RDoc::Task < Rake::TaskLib
     task :clobber => [clobber_task_name]
 
     directory @rdoc_dir
+
     task rdoc_task_name => [rdoc_target]
     file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
       rm_r @rdoc_dir rescue nil
       @before_running_rdoc.call if @before_running_rdoc
       args = option_list + @rdoc_files
 
-      if @external then
-        argstring = args.join(' ')
-        sh %{ruby -Ivendor vendor/rd #{argstring}}
-      else
-        if Rake.application.options.trace then
-          $stderr.puts "rdoc #{args.join ' '}"
-        end
-        require 'rdoc/rdoc'
-        RDoc::RDoc.new.document(args)
+      if Rake.application.options.trace then
+        $stderr.puts "rdoc #{args.join ' '}"
       end
+      require 'rdoc/rdoc'
+      RDoc::RDoc.new.document(args)
     end
 
     self
   end
 
+  ##
+  # List of options that will be supplied to RDoc
+
   def option_list
     result = @options.dup
-    result << "-o" << @rdoc_dir
-    result << "--main" << quote(main) if main
-    result << "--title" << quote(title) if title
-    result << "-T" << quote(template) if template
+    result << "-o"      << @rdoc_dir
+    result << "--main"  << main     if main
+    result << "--title" << title    if title
+    result << "-T"      << template if template
     result
   end
 
-  def quote(str)
-    if @external
-      "'#{str}'"
-    else
-      str
-    end
-  end
-
-  def option_string
-    option_list.join(' ')
-  end
-
   ##
   # The block passed to this method will be called just before running the
   # RDoc generator. It is allowed to modify RDoc::Task attributes inside the
@@ -236,28 +220,22 @@ class RDoc::Task < Rake::TaskLib
 
   def rdoc_task_name
     case name
-    when Hash
-      (name[:rdoc] || "rdoc").to_s
-    else
-      name.to_s
+    when Hash then (name[:rdoc] || "rdoc").to_s
+    else           name.to_s
     end
   end
 
   def clobber_task_name
     case name
-    when Hash
-      (name[:clobber_rdoc] || "clobber_rdoc").to_s
-    else
-      "clobber_#{name}"
+    when Hash then (name[:clobber_rdoc] || "clobber_rdoc").to_s
+    else           "clobber_#{name}"
     end
   end
 
   def rerdoc_task_name
     case name
-    when Hash
-      (name[:rerdoc] || "rerdoc").to_s
-    else
-      "re#{name}"
+    when Hash then (name[:rerdoc] || "rerdoc").to_s
+    else           "re#{name}"
     end
   end
 

data/lib/rdoc/text.rb

@@ -0,0 +1,130 @@
+##
+# Methods for manipulating comment text
+
+module RDoc::Text
+
+  ##
+  # Expands tab characters in +text+ to eight spaces
+
+  def expand_tabs text
+    expanded = []
+
+    text.each_line do |line|
+      line.gsub!(/^(.{8}*?)([^\t\r\n]{0,7})\t/) do
+        "#{$1}#{$2}#{' ' * (8 - $2.size)}"
+      end until line !~ /\t/
+
+      expanded << line
+    end
+
+    expanded.join
+  end
+
+  ##
+  # Flush +text+ left based on the shortest line
+
+  def flush_left text
+    indents = []
+
+    text.each_line do |line|
+      indents << (line =~ /[^\s]/ || 9999)
+    end
+
+    indent = indents.min
+
+    flush = []
+
+    text.each_line do |line|
+      line[/^ {0,#{indent}}/] = ''
+      flush << line
+    end
+
+    flush.join
+  end
+
+  ##
+  # Convert a string in markup format into HTML.  Removes the first paragraph
+  # tags if +remove_para+ is true.
+  #
+  # Requires the including class to implement #formatter
+
+  def markup text
+    document = parse text
+
+    document.accept formatter
+  end
+
+  ##
+  # Strips hashes, expands tabs then flushes +text+ to the left
+
+  def normalize_comment text
+    return text if text.empty?
+
+    text = strip_hashes text
+    text = expand_tabs text
+    text = flush_left text
+    strip_newlines text
+  end
+
+  ##
+  # Normalizes +text+ then builds a RDoc::Markup::Document from it
+
+  def parse text
+    return text if RDoc::Markup::Document === text
+
+    text = normalize_comment text
+
+    return RDoc::Markup::Document.new if text =~ /\A\n*\z/
+
+    RDoc::Markup::Parser.parse text
+  rescue RDoc::Markup::Parser::Error => e
+    $stderr.puts <<-EOF
+While parsing markup, RDoc encountered a #{e.class}:
+
+#{e}
+\tfrom #{e.backtrace.join "\n\tfrom "}
+
+---8<---
+#{text}
+---8<---
+
+RDoc #{RDoc::VERSION}
+
+Ruby #{RUBY_VERSION}-p#{RUBY_PATCHLEVEL} #{RUBY_RELEASE_DATE}
+
+Please file a bug report with the above information at:
+
+http://rubyforge.org/tracker/?atid=2472&group_id=627&func=browse
+
+    EOF
+    raise
+  end
+
+  ##
+  # Strips leading # characters from +text+
+
+  def strip_hashes text
+    return text if text =~ /^(?>\s*)[^\#]/
+    text.gsub(/^\s*(#+)/) { $1.tr '#',' ' }
+  end
+
+  ##
+  # Strips leading and trailing \n characters from +text+
+
+  def strip_newlines text
+    text.gsub(/\A\n*(.*?)\n*\z/m, '\1')
+  end
+
+  ##
+  # Strips /* */ style comments
+
+  def strip_stars text
+    text = text.gsub %r%Document-method:\s+[\w:.#]+%, ''
+    text.sub!  %r%/\*+%       do " " * $&.length end
+    text.sub!  %r%\*+/%       do " " * $&.length end
+    text.gsub! %r%^[ \t]*\*%m do " " * $&.length end
+    text
+  end
+
+end
+

data/lib/rdoc/tokenstream.rb

@@ -9,25 +9,44 @@ module RDoc; end
 
 module RDoc::TokenStream
 
-  def token_stream
-    @token_stream
+  ##
+  # Adds +tokens+ to the collected tokens
+
+  def add_tokens(*tokens)
+    tokens.flatten.each { |token| @token_stream << token }
   end
 
-  def start_collecting_tokens
+  alias add_token add_tokens
+
+  ##
+  # Starts collecting tokens
+
+  def collect_tokens
     @token_stream = []
   end
 
-  def add_token(tk)
-    @token_stream << tk
-  end
+  alias start_collecting_tokens collect_tokens
 
-  def add_tokens(tks)
-    tks.each  {|tk| add_token(tk)}
-  end
+  ##
+  # Remove the last token from the collected tokens
 
   def pop_token
     @token_stream.pop
   end
 
+  ##
+  # Current token stream
+
+  def token_stream
+    @token_stream
+  end
+
+  ##
+  # Returns a string representation of the token stream
+
+  def tokens_to_s
+    token_stream.map { |token| token.text }.join ''
+  end
+
 end
 

data/lib/rdoc/top_level.rb

@@ -1,4 +1,3 @@
-require 'thread'
 require 'rdoc/context'
 
 ##
@@ -67,40 +66,49 @@ class RDoc::TopLevel < RDoc::Context
   # Finds the class with +name+ in all discovered classes
 
   def self.find_class_named(name)
-    @lock.synchronize do
-      classes_hash.values.find do |c|
-        c.find_class_named name
-      end
-    end
+    classes_hash[name]
   end
 
   ##
-  # Finds the file with +name+ in all discovered files
+  # Finds the class with +name+ starting in namespace +from+
 
-  def self.find_file_named(name)
-    @lock.synchronize do
-      @all_files[name]
+  def self.find_class_named_from name, from
+    from = find_class_named from unless RDoc::Context === from
+
+    until RDoc::TopLevel === from do
+      return nil unless from
+
+      klass = from.find_class_named name
+      return klass if klass
+
+      from = from.parent
     end
+
+    find_class_named name
   end
 
   ##
-  # Finds the module with +name+ in all discovered modules
+  # Finds the class or module with +name+
 
-  def self.find_module_named(name)
-    @lock.synchronize do
-      modules_hash.values.find do |c|
-        c.find_module_named name
-      end
-    end
+  def self.find_class_or_module(name)
+    name =~ /^::/
+    name = $' || name
+
+    RDoc::TopLevel.classes_hash[name] || RDoc::TopLevel.modules_hash[name]
   end
 
-  @lock = Mutex.new
+  ##
+  # Finds the file with +name+ in all discovered files
+
+  def self.find_file_named(name)
+    @all_files[name]
+  end
 
   ##
-  # Lock for global class, module and file stores
+  # Finds the module with +name+ in all discovered modules
 
-  def self.lock
-    @lock
+  def self.find_module_named(name)
+    modules_hash[name]
   end
 
   ##
@@ -121,11 +129,9 @@ class RDoc::TopLevel < RDoc::Context
   # Empties RDoc of stored class, module and file information
 
   def self.reset
-    @lock.synchronize do
-      @all_classes = {}
-      @all_modules = {}
-      @all_files   = {}
-    end
+    @all_classes = {}
+    @all_modules = {}
+    @all_files   = {}
   end
 
   reset
@@ -142,9 +148,7 @@ class RDoc::TopLevel < RDoc::Context
     @diagram       = nil
     @parser        = nil
 
-    RDoc::TopLevel.lock.synchronize do
-      RDoc::TopLevel.files_hash[file_name] = self
-    end
+    RDoc::TopLevel.files_hash[file_name] = self
   end
 
   ##
@@ -165,33 +169,24 @@ class RDoc::TopLevel < RDoc::Context
   end
 
   ##
-  # Find class or module named +symbol+ in all discovered classes and
-  # modules
-
-  def find_class_or_module_named(symbol)
-    RDoc::TopLevel.classes_hash.each_value do |c|
-      return c if c.full_name == symbol
-    end
-
-    RDoc::TopLevel.modules_hash.each_value do |m|
-      return m if m.full_name == symbol
-    end
+  # See RDoc::TopLevel.find_class_or_module
 
-    nil
+  def find_class_or_module name
+    RDoc::TopLevel.find_class_or_module name
   end
 
   ##
   # Finds a class or module named +symbol+
 
   def find_local_symbol(symbol)
-    find_class_or_module_named(symbol) || super
+    find_class_or_module(symbol) || super
   end
 
   ##
   # Finds a module or class with +name+
 
   def find_module_named(name)
-    find_class_or_module_named(name) || find_enclosing_module_named(name)
+    find_class_or_module(name) || find_enclosing_module_named(name)
   end
 
   ##
@@ -238,5 +233,16 @@ class RDoc::TopLevel < RDoc::Context
     http_url RDoc::RDoc.current.generator.file_dir
   end
 
+  def pretty_print q # :nodoc:
+    q.group 2, "[#{self.class}: ", "]" do
+      q.text "base name: #{base_name.inspect}"
+      q.breakable
+
+      items = @modules.map { |n,m| m }
+      items.push(*@modules.map { |n,c| c })
+      q.seplist items do |mod| q.pp mod end
+    end
+  end
+
 end