* document updates - [ruby-core:04296], [ruby-core:04301],

  [ruby-core:04302], [ruby-core:04307]


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

6 files changed, 204 insertions, 46 deletions

diff --git a/ChangeLog b/ChangeLog
index c3f08aa471..229645d676 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Mon Jan 24 15:44:25 2005  Yukihiro Matsumoto  <matz@ruby-lang.org>
+
+	* document updates - [ruby-core:04296], [ruby-core:04301],
+	  [ruby-core:04302], [ruby-core:04307]
+
 Sun Jan 23 12:41:16 2005  NAKAMURA, Hiroshi  <nakahiro@sarion.co.jp>
 
 	* lib/soap/wsdlDriver.rb: from 1.5.3-ruby1.8.2, operation which has
diff --git a/eval.c b/eval.c
index 3f0dec822a..8351a6b28a 100644
--- a/eval.c
+++ b/eval.c
@@ -8264,15 +8264,14 @@ static VALUE method_arity _((VALUE));
  *  call-seq:
  *     prc.arity -> fixnum
  *  
- *  Returns the number of arguments required by the block. If the block
+ *  Returns the number of arguments that would not be ignored. If the block
  *  is declared to take no arguments, returns 0. If the block is known
  *  to take exactly n arguments, returns n. If the block has optional
  *  arguments, return -n-1, where n is the number of mandatory
- *  arguments. A <code>proc</code> with no argument declarations 
- *  returns -1, as it can accept (and ignore) an arbitrary number of
- *  parameters.
+ *  arguments. A <code>proc</code> with no argument declarations
+ *  is the same a block declaring <code>||</code> as its arguments.
  *     
- *     Proc.new {}.arity          #=> -1
+ *     Proc.new {}.arity          #=>  0
  *     Proc.new {||}.arity        #=>  0
  *     Proc.new {|a|}.arity       #=>  1
  *     Proc.new {|a,b|}.arity     #=>  2
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index 6c9134fc62..25ce83dd8e 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -174,7 +174,7 @@ module RDoc
     # prepare to parse a C file
     def initialize(top_level, file_name, body, options, stats)
       @known_classes = KNOWN_CLASSES.dup
-      @body = handle_ifdefs_in(body)
+      @body = handle_tab_width(handle_ifdefs_in(body))
       @options = options
       @stats   = stats
       @top_level = top_level
@@ -187,6 +187,7 @@ module RDoc
     def scan
       remove_commented_out_lines
       do_classes
+      do_constants
       do_methods
       do_includes
       do_aliases
@@ -240,7 +241,7 @@ module RDoc
       if @body =~ %r{((?>/\*.*?\*/\s+))
                      (static\s+)?void\s+Init_#{class_name}\s*\(\)}xmi
         comment = $1
-      elsif @body =~ %r{Document-(class|module):\s#{class_name}.*?\n((?>.*?\*/))}m
+      elsif @body =~ %r{Document-(class|module):\s#{class_name}\s*?\n((?>.*?\*/))}m
         comment = $2
       end
       class_meth.comment = mangle_comment(comment) if comment
@@ -249,13 +250,13 @@ module RDoc
     ############################################################
 
     def do_classes
-      @body.scan(/(\w+)\s* = \s*rb_define_module\(\s*"(\w+)"\s*\)/mx) do 
+      @body.scan(/(\w+)\s* = \s*rb_define_module\s*\(\s*"(\w+)"\s*\)/mx) do 
         |var_name, class_name|
         handle_class_module(var_name, "module", class_name, nil, nil)
       end
       
       # The '.' lets us handle SWIG-generated files
-      @body.scan(/([\w\.]+)\s* = \s*rb_define_class
+      @body.scan(/([\w\.]+)\s* = \s*rb_define_class\s*
                 \( 
                    \s*"(\w+)",
                    \s*(\w+)\s*
@@ -265,7 +266,7 @@ module RDoc
         handle_class_module(var_name, "class", class_name, parent, nil)
       end
       
-      @body.scan(/(\w+)\s*=\s*boot_defclass\(\s*"(\w+?)",\s*(\w+?)\)/) do
+      @body.scan(/(\w+)\s*=\s*boot_defclass\s*\(\s*"(\w+?)",\s*(\w+?)\s*\)/) do
         |var_name, class_name, parent|
         parent = nil if parent == "0"
         handle_class_module(var_name, "class", class_name, parent, nil)
@@ -281,18 +282,40 @@ module RDoc
         handle_class_module(var_name, "module", class_name, nil, in_module)
       end
       
-      @body.scan(/([\w\.]+)\s* = \s*rb_define_class_under
+      @body.scan(/([\w\.]+)\s* = \s*rb_define_class_under\s*
                 \( 
                    \s*(\w+),
                    \s*"(\w+)",
                    \s*(\w+)\s*
-                \)/mx) do 
+                \s*\)/mx) do 
         
         |var_name, in_module, class_name, parent|
         handle_class_module(var_name, "class", class_name, parent, in_module)
       end
       
     end
+
+		###########################################################
+
+    def do_constants
+      @body.scan(%r{\Wrb_define_
+                     (
+                        variable |
+                        readonly_variable |
+                        const |
+                        global_const |
+                      )
+                 \s*\( 
+                   (?:\s*(\w+),)?
+                   \s*"(\w+)",
+                   \s*(.*?)\s*\)\s*;
+                   }xm) do
+        
+        |type, var_name, const_name, definition|
+        var_name = "rb_cObject" if !var_name or var_name == "rb_mKernel"
+				handle_constants(type, var_name, const_name, definition)
+      end
+    end
     
     ############################################################
     
@@ -305,7 +328,7 @@ module RDoc
                         module_function  |
                         private_method
                      )
-                     \(\s*([\w\.]+),
+                     \s*\(\s*([\w\.]+),
                        \s*"([^"]+)",
                        \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
                        \s*(-?\w+)\s*\)
@@ -325,7 +348,21 @@ module RDoc
                       meth_body, param_count, source_file)
       end
 
-      @body.scan(%r{rb_define_global_function\(
+      @body.scan(%r{rb_define_attr\(
+                               \s*([\w\.]+),
+                               \s*"([^"]+)",
+                               \s*(\d+),
+                               \s*(\d+)\s*\);
+                  }xm) do  #"
+        |var_name, attr_name, attr_reader, attr_writer|
+        
+        #var_name = "rb_cObject" if var_name == "rb_mKernel"
+        handle_attr(var_name, attr_name,
+                    attr_reader.to_i != 0,
+                    attr_writer.to_i != 0)
+      end
+
+      @body.scan(%r{rb_define_global_function\s*\(
                                \s*"([^"]+)",
                                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
                                \s*(-?\w+)\s*\)
@@ -336,7 +373,7 @@ module RDoc
                       meth_body, param_count, source_file)
       end
   
-      @body.scan(/define_filetest_function\(
+      @body.scan(/define_filetest_function\s*\(
                                \s*"([^"]+)",
                                \s*(?:RUBY_METHOD_FUNC\(|VALUEFUNC\()?(\w+)\)?,
                                \s*(-?\w+)\s*\)/xm) do  #"
@@ -350,7 +387,7 @@ module RDoc
     ############################################################
     
     def do_aliases
-      @body.scan(%r{rb_define_alias\(\s*(\w+),\s*"([^"]+)",\s*"([^"]+)"\s*\)}m) do
+      @body.scan(%r{rb_define_alias\s*\(\s*(\w+),\s*"([^"]+)",\s*"([^"]+)"\s*\)}m) do
         |var_name, new_name, old_name|
         @stats.num_methods += 1
         class_name = @known_classes[var_name] || var_name
@@ -362,6 +399,83 @@ module RDoc
 
     ############################################################
 
+    def handle_constants(type, var_name, const_name, definition)
+      #@stats.num_constants += 1
+      class_name = @known_classes[var_name]
+      
+      return unless class_name
+
+      class_obj  = find_class(var_name, class_name)
+
+      unless class_obj
+        $stderr.puts("Enclosing class/module '#{const_name}' for not known")
+        return
+      end
+      
+      comment = find_const_comment(type, const_name)
+
+      con = Constant.new(const_name, definition, mangle_comment(comment))
+      class_obj.add_constant(con)
+    end
+
+    ###########################################################
+
+    def find_const_comment(type, const_name)
+      if @body =~ %r{((?>/\*.*?\*/\s+))
+                     rb_define_#{type}\((?:\s*(\w+),)?\s*"#{const_name}"\s*,.*?\)\s*;}xmi
+        $1
+      elsif @body =~ %r{Document-(?:const|global|variable):\s#{const_name}\s*?\n((?>.*?\*/))}m
+        $1
+      else
+        ''
+      end
+    end
+
+    ###########################################################
+
+    def handle_attr(var_name, attr_name, reader, writer)
+      rw = ''
+      if reader 
+        #@stats.num_methods += 1
+        rw << 'R'
+      end
+      if writer
+        #@stats.num_methods += 1
+        rw << 'W'
+      end
+
+      class_name = @known_classes[var_name]
+
+      return unless class_name
+      
+      class_obj  = find_class(var_name, class_name)
+
+      if class_obj
+        comment = find_attr_comment(attr_name)
+        unless comment.empty?
+          comment = mangle_comment(comment)
+        end
+        att = Attr.new('', attr_name, rw, comment)
+        class_obj.add_attribute(att)
+      end
+
+    end
+
+    ###########################################################
+
+    def find_attr_comment(attr_name)
+      if @body =~ %r{((?>/\*.*?\*/\s+))
+                     rb_define_attr\((?:\s*(\w+),)?\s*"#{attr_name}"\s*,.*?\)\s*;}xmi
+        $1
+      elsif @body =~ %r{Document-attr:\s#{attr_name}\s*?\n((?>.*?\*/))}m
+        $1
+      else
+        ''
+      end
+    end
+
+    ###########################################################
+
     def handle_method(type, var_name, meth_name, 
                       meth_body, param_count, source_file = nil)
       @stats.num_methods += 1
@@ -469,12 +583,10 @@ module RDoc
     ############################################################
 
     def find_override_comment(meth_name)
-      comment = nil
       name = Regexp.escape(meth_name)
-      if @body =~ %r{Document-method:\s#{name}.*?\n((?>.*?\*/))}m
-        comment = $1
+      if @body =~ %r{Document-method:\s#{name}\s*?\n((?>.*?\*/))}m
+        $1
       end
-      comment
     end
 
     ############################################################
@@ -482,7 +594,7 @@ module RDoc
     # Look for includes of the form
     #     rb_include_module(rb_cArray, rb_mEnumerable);
     def do_includes
-      @body.scan(/rb_include_module\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
+      @body.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
         if cls = @classes[c]
           m = KNOWN_CLASSES[m] || m
           cls.add_include(Include.new(m, ""))
@@ -512,6 +624,18 @@ module RDoc
       @classes[raw_name]
     end
 
+    def handle_tab_width(body)
+      if /\t/ =~ body
+        tab_width = Options.instance.tab_width
+        body.split(/\n/).map do |line|
+          1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
+          line
+        end .join("\n")
+      else
+        body
+      end
+    end
+
     # Remove #ifdefs that would otherwise confuse us
     
     def handle_ifdefs_in(body)
diff --git a/lib/rdoc/parsers/parse_rb.rb b/lib/rdoc/parsers/parse_rb.rb
index e306598dee..fd95b2b7c8 100644
--- a/lib/rdoc/parsers/parse_rb.rb
+++ b/lib/rdoc/parsers/parse_rb.rb
@@ -1883,6 +1883,7 @@ module RDoc
       name_t = get_tk
       back_tk = skip_tkspace
       meth = nil
+      added_container = false
 
       dot = get_tk
       if dot.kind_of?(TkDOT) or dot.kind_of?(TkCOLON2)
@@ -1897,8 +1898,21 @@ module RDoc
           prev_container = container
           container = container.find_module_named(name_t.name)
           if !container
-            warn("Couldn't find #{name_t.name}. Assuming it's a module")
-            container = prev_container.add_module(NormalModule, name_t.name)
+            added_container = true
+            obj = name_t.name.split("::").inject(Object) do |state, item|
+              state.const_get(item)
+            end rescue nil
+
+            type = obj.class == Class ? NormalClass : NormalModule
+            if not [Class, Module].include?(obj.class)
+              warn("Couldn't find #{name_t.name}. Assuming it's a module")
+            end
+
+            if type == NormalClass then
+              container = prev_container.add_class(type, name_t.name, obj.superclass.name)
+            else
+              container = prev_container.add_module(type, name_t.name)
+            end
           end
 	else
 	  # warn("Unexpected token '#{name_t2.inspect}'")
@@ -1940,7 +1954,9 @@ module RDoc
       parse_method_parameters(meth)
 
       if meth.document_self
-	container.add_method(meth)
+        container.add_method(meth)
+      elsif added_container
+        container.document_self = false
       end
 
       # Having now read the method parameters and documentation modifiers, we
diff --git a/lib/rdoc/parsers/parse_simple.rb b/lib/rdoc/parsers/parse_simple.rb
index b01104574e..3f1a546964 100644
--- a/lib/rdoc/parsers/parse_simple.rb
+++ b/lib/rdoc/parsers/parse_simple.rb
@@ -30,8 +30,12 @@ module RDoc
     
     def scan
       #    @body.gsub(/^(\s\n)+/, '')
-      @top_level.comment = @body
+      @top_level.comment = remove_private_comments(@body)
       @top_level
     end
+
+    def remove_private_comments(comment)
+      comment.gsub(/^--.*?^\+\+/m, '').sub(/^--.*/m, '')
+    end
   end
 end
diff --git a/lib/timeout.rb b/lib/timeout.rb
index 0ba5293d1d..734d87f204 100644
--- a/lib/timeout.rb
+++ b/lib/timeout.rb
@@ -1,38 +1,39 @@
+# = timeout.rb
 #
-# timeout.rb -- execution timeout
+# execution timeout
 #
-# Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
-# Copyright (C) 2000  Information-technology Promotion Agency, Japan
-#
-#= SYNOPSIS
+# = Synopsis
 #
 #   require 'timeout'
-#   status = timeout(5) {
-#     # something may take time
+#   status = Timeout::timeout(5) {
+#     # Something that should be interrupted if it takes too much time...
 #   }
 #
-#= DESCRIPTION
-#
-# timeout executes the block.  If the block execution terminates successfully
-# before timeout, it returns true.  If not, it terminates the execution and
-# raise TimeoutError exception.
-#
-#== Parameters
-#
-#  : timout
+# = Description
 #
-#    The time in seconds to wait for block termination.   
+# A way of performing a potentially long-running operation in a thread, and terminating
+# it's execution if it hasn't finished by a fixed amount of time.
 #
-#  : [exception]
+# Previous versions of timeout didn't provide use a module for namespace. This version
+# provides both Timeout.timeout, and a backwards-compatible #timeout.
 #
-#    The exception class to be raised on timeout.
+# = Copyright
 #
-#=end
+# Copyright:: (C) 2000  Network Applied Communication Laboratory, Inc.
+# Copyright:: (C) 2000  Information-technology Promotion Agency, Japan
 
 module Timeout
+  # Raised by Timeout#timeout when the block times out.
   class Error<Interrupt
   end
 
+  # Executes the method's block. If the block execution terminates before +sec+
+  # seconds has passed, it returns true. If not, it terminates the execution
+  # and raises +exception+ (which defaults to Timeout::Error).
+  #
+  # Note that this is both a method of module Timeout, so you can 'include Timeout'
+  # into your classes so they have a #timeout method, as well as a module method,
+  # so you can call it directly as Timeout.timeout().
   def timeout(sec, exception=Error)
     return yield if sec == nil or sec.zero?
     begin
@@ -47,13 +48,22 @@ module Timeout
       y.kill if y and y.alive?
     end
   end
+
   module_function :timeout
 end
 
-# compatible
+# Identical to:
+#
+#   Timeout::timeout(n, e, &block).
+#
+# Defined for backwards compatibility with earlier versions of timeout.rb, see
+# Timeout#timeout.
 def timeout(n, e=Timeout::Error, &block)
   Timeout::timeout(n, e, &block)
 end
+
+# Another name for Timeout::Error, defined for backwards compatibility with
+# earlier versions of timeout.rb.
 TimeoutError = Timeout::Error
 
 if __FILE__ == $0