Import RDoc 3

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@30249 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/rdoc/parser.rb

@@ -1,6 +1,6 @@
 require 'rdoc'
 require 'rdoc/code_objects'
-require 'rdoc/markup/preprocess'
+require 'rdoc/markup/pre_process'
 require 'rdoc/stats'
 
 ##
@@ -43,7 +43,15 @@ class RDoc::Parser
   @parsers = []
 
   class << self
+
+    ##
+    # A Hash that maps file exetensions regular expressions to parsers that
+    # will consume them.
+    #
+    # Use parse_files_matching to register a parser's file extensions.
+
     attr_reader :parsers
+
   end
 
   ##
@@ -67,18 +75,51 @@ class RDoc::Parser
   # content that an RDoc parser shouldn't try to consume.
 
   def self.binary?(file)
+    return false if file =~ /\.(rdoc|txt)$/
+
     s = File.read(file, 1024) or return false
 
-    if s[0, 2] == Marshal.dump('')[0, 2] then
-      true
-    elsif file =~ /erb\.rb$/ then
-      false
-    elsif s.scan(/<%|%>/).length >= 4 || s.index("\x00") then
-      true
-    elsif 0.respond_to? :fdiv then
-      s.count("\x00-\x7F", "^ -~\t\r\n").fdiv(s.size) > 0.3
-    else # HACK 1.8.6
-      (s.count("\x00-\x7F", "^ -~\t\r\n").to_f / s.size) > 0.3
+    have_encoding = s.respond_to? :encoding
+
+    if have_encoding then
+      return false if s.encoding != Encoding::ASCII_8BIT and s.valid_encoding?
+    end
+
+    return true if s[0, 2] == Marshal.dump('')[0, 2] or s.index("\x00")
+
+    if have_encoding then
+      s.force_encoding Encoding.default_external
+
+      not s.valid_encoding?
+    else
+      if 0.respond_to? :fdiv then
+        s.count("\x00-\x7F", "^ -~\t\r\n").fdiv(s.size) > 0.3
+      else # HACK 1.8.6
+        (s.count("\x00-\x7F", "^ -~\t\r\n").to_f / s.size) > 0.3
+      end
+    end
+  end
+
+  ##
+  # Processes common directives for CodeObjects for the C and Ruby parsers.
+  #
+  # Applies +directive+'s +value+ to +code_object+, if appropriate
+
+  def self.process_directive code_object, directive, value
+    case directive
+    when 'nodoc' then
+      code_object.document_self = nil # notify nodoc
+      code_object.document_children = value.downcase != 'all'
+    when 'doc' then
+      code_object.document_self = true
+      code_object.force_documentation = true
+    when 'yield', 'yields' then
+      # remove parameter &block
+      code_object.params.sub!(/,?\s*&\w+/, '') if code_object.params
+
+      code_object.block_params = value
+    when 'arg', 'args' then
+      code_object.params = value
     end
   end
 
@@ -143,6 +184,12 @@ class RDoc::Parser
     RDoc::Parser.parsers.unshift [regexp, self]
   end
 
+  ##
+  # Creates a new Parser storing +top_level+, +file_name+, +content+, 
+  # +options+ and +stats+ in instance variables.
+  #
+  # Usually invoked by +super+
+
   def initialize(top_level, file_name, content, options, stats)
     @top_level = top_level
     @file_name = file_name