* lib/rdoc/parsers/parse_c.rb (RDoc::C_Parser#do_includes): replace

  also locally defined modules.

* ext/iconv/iconv.c: rdocified.

* ext/strscan/strscan.c: moved misplaced rdoc.


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

4 files changed, 239 insertions, 225 deletions

diff --git a/ChangeLog b/ChangeLog
index a2e6d5a02e..a5eb7c0a2f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+Fri Mar  4 19:39:55 2005  Nobuyoshi Nakada  <nobu@ruby-lang.org>
+
+	* lib/rdoc/parsers/parse_c.rb (RDoc::C_Parser#do_includes): replace
+	  also locally defined modules.
+
+	* ext/iconv/iconv.c: rdocified.
+
+	* ext/strscan/strscan.c: moved misplaced rdoc.
+
 Fri Mar  4 16:11:20 2005  NAKAMURA Usaku  <usa@ruby-lang.org>
 
 	* eval.c (rb_exec_recursive): matched the declaration to prototype.
@@ -47,7 +56,7 @@ Fri Mar  4 08:09:12 2005  Yukihiro Matsumoto  <matz@ruby-lang.org>
 
 Thu Mar  4 07:07:00 2005  NARUSE, Yui  <naruse@ruby-lang.org>
 
-        * ext/nkf/nkf-utf8/nkf.c: follow nkf 1.63
+	* ext/nkf/nkf-utf8/nkf.c: follow nkf 1.63
 
 Thu Mar  3 23:24:00 2005  NARUSE, Yui  <naruse@ruby-lang.org>
 
@@ -418,7 +427,7 @@ Wed Feb 16 02:47:45 2005  GOTOU Yuuzou  <gotoyuzo@notwork.org>
 
 Tue Feb 15 22:14:34 2005  sheepman  <sheepman@tcn.zaq.ne.jp>
 
-	* ext/readline/readline.c (Readline.readline): use rl_outstream 
+	* ext/readline/readline.c (Readline.readline): use rl_outstream
 	  and rl_instream.  [ruby-dev:25699]
 
 Mon Feb 14 23:58:17 2005  Kouhei Sutou  <kou@cozmixng.org>
@@ -3403,7 +3412,7 @@ Thu Oct 21 21:32:30 2004  IWATSUKI Hiroyuki  <don@na.rim.or.jp>
 
 	* lib/pstore.rb (PStore#transaction): Use the empty content when a
 	  file is not found.  [ruby-dev:24561]
-	
+
 Thu Oct 21 19:06:15 2004  GOTOU Yuuzou  <gotoyuzo@notwork.org>
 
 	* lib/webrick/httpresponse.rb (WEBrick::HTTPResponse#send_body_io):
diff --git a/ext/iconv/iconv.c b/ext/iconv/iconv.c
index 84b14309af..951f89e8a3 100644
--- a/ext/iconv/iconv.c
+++ b/ext/iconv/iconv.c
@@ -10,27 +10,9 @@
   All the files in this distribution are covered under the Ruby's
   license (see the file COPYING).
 
-**********************************************************************/
-
-/*
-=begin
-= Summary
-Ruby extension for codeset conversion.
-
-= Abstract
-Iconv is a wrapper class for UNIX 95 (({iconv()})) function family, which
-translates string between various coding systems.
+  Documentation by Yukihiro Matsumoto and Gavin Sinclair.
 
-See ((<Open Group|URL:http://www.opengroup.org/>))'s on-line documents for more details.
-* ((<iconv.h|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html>))
-* ((<iconv_open()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html>))
-* ((<iconv()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.html>))
-* ((<iconv_close()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html>))
-
-Which coding systems are available, it depends on the platform.
-
-=end
-*/
+**********************************************************************/
 
 #include "ruby.h"
 #include <errno.h>
@@ -39,6 +21,54 @@ Which coding systems are available, it depends on the platform.
 #include "st.h"
 #include "intern.h"
 
+/*
+ * Document-class: Iconv
+ *
+ * == Summary
+ *
+ * Ruby extension for charset conversion.
+ * 
+ * == Abstract
+ *
+ * Iconv is a wrapper class for the UNIX 95 <tt>iconv()</tt> function family,
+ * which translates string between various encoding systems.
+ * 
+ * See Open Group's on-line documents for more details.
+ * * <tt>iconv.h</tt>:       http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html
+ * * <tt>iconv_open()</tt>:  http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html
+ * * <tt>iconv()</tt>:       http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.html
+ * * <tt>iconv_close()</tt>: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html
+ * 
+ * Which coding systems are available is platform-dependent.
+ * 
+ * == Examples
+ *
+ * 1. Instantiate a new Iconv and use method Iconv#iconv.
+ *
+ *      cd = Iconv.new(to, from)
+ *      begin
+ *        input.each { |s| output << cd.iconv(s) }
+ *        output << cd.iconv(nil)                   # Don't forget this!
+ *      ensure
+ *        cd.close
+ *      end
+ *
+ * 2. Invoke Iconv.open with a block.
+ *
+ *      Iconv.open(to, from) do |cd|
+ *        input.each { |s| output << cd.iconv(s) }
+ *        output << cd.iconv(nil)
+ *      end
+ *
+ * 3. Shorthand for (2).
+ *
+ *      Iconv.iconv(to, from, *input.to_a)
+ *
+ * 4. Simple conversion between two charsets.
+ *
+ *      converted_text = Iconv.new('iso-8859-15', 'utf-8').iconv(text)
+ */
+
 /* Invalid value for iconv_t is -1 but 0 for VALUE, I hope VALUE is
    big enough to keep iconv_t */
 #define VALUE2ICONV(v) ((iconv_t)((VALUE)(v) ^ -1))
@@ -80,18 +110,6 @@ static VALUE iconv_init_state _((VALUE cd));
 static VALUE iconv_finish _((VALUE self));
 static VALUE iconv_iconv _((int argc, VALUE *argv, VALUE self));
 
-
-/*
-=begin
-= Classes & Modules
-=end
-*/
-
-/*
-=begin
-== Iconv
-=end
-*/
 static VALUE charset_map;
 
 static VALUE charset_map_get _((void))
@@ -465,36 +483,6 @@ iconv_convert
     return ret;
 }
 
-
-/*
-=begin
-=== Class methods
-=end
-*/
-/*
-=begin
---- Iconv.new(to, from) {|cd| ...}
-    Creates new code converter from a coding-system designated with ((|from|))
-    to another one designated with ((|to|)).
-    :Parameters
-      :((|to|))
-        coding-system name for destination.
-      :((|from|))
-        coding-system name for source.
-    :Exceptions
-      :(({TypeError}))
-        if ((|to|)) or ((|from|)) aren't String
-      :(({ArgumentError}))
-        if designated converter couldn't find out.
-      :(({SystemCallError}))
-        when (({iconv_open(3)})) failed.
-
---- Iconv.open(to, from)
-    Equivalents to ((<Iconv.new>)) except with in the case of called
-    with a block, yields with the new instance and closes it, and
-    returns the result which returned from the block.
-=end
-*/
 static VALUE
 iconv_s_allocate
 #ifdef HAVE_PROTOTYPES
@@ -507,6 +495,24 @@ iconv_s_allocate
     return Data_Wrap_Struct(klass, 0, ICONV_FREE, 0);
 }
 
+/*
+ * Document-method: new
+ * call-seq: Iconv.new(to, from)
+ *
+ * Creates new code converter from a coding-system designated with +from+
+ * to another one designated with +to+.
+ * 
+ * === Parameters
+ *
+ * +to+::   encoding name for destination
+ * +from+:: encoding name for source
+ *
+ * === Exceptions
+ *
+ * TypeError::       if +to+ or +from+ aren't String
+ * ArgumentError::   if designated converter couldn't find out
+ * SystemCallError:: if <tt>iconv_open3</tt> fails
+ */
 static VALUE
 iconv_initialize
 #ifdef HAVE_PROTOTYPES
@@ -524,6 +530,14 @@ iconv_initialize
     return self;
 }
 
+/*
+ * Document-method: open
+ * call-seq: Iconv.open(to, from) { |iconv| ... }
+ *
+ * Equivalent to Iconv.new except that when it is called with a block, it
+ * yields with the new instance and closes it, and returns the result which
+ * returned from the block.
+ */
 static VALUE
 iconv_s_open
 #ifdef HAVE_PROTOTYPES
@@ -546,22 +560,6 @@ iconv_s_open
     }
 }
 
-/*
-=begin
---- Iconv.iconv(to, from, *strs)
-    Shorthand for
-      Iconv.open(to, from) {|cd| (strs + [nil]).collect {|s| cd.iconv(s)}}
-    :Parameters
-      :((|to|)), ((|from|))
-        see ((<Iconv.new>)).
-      :((|strs|))
-        strings to be converted.
-    :Exceptions
-      exceptions thrown by ((<Iconv.new>)), ((<Iconv.open>)) and
-      ((<Iconv#iconv>)).
-=end
-*/
-
 static VALUE
 iconv_s_convert
 #ifdef HAVE_PROTOTYPES
@@ -587,6 +585,24 @@ iconv_s_convert
     return env->ret;
 }
 
+/*
+ * Document-method: iconv
+ * call-seq: Iconv.iconv(to, from, *strs)
+ *
+ * Shorthand for
+ *   Iconv.open(to, from) { |cd|
+ *     (strs + [nil]).collect { |s| cd.iconv(s) }
+ *   }
+ *
+ * === Parameters
+ *
+ * <tt>to, from</tt>:: see Iconv.new
+ * <tt>strs</tt>:: strings to be converted
+ *
+ * === Exceptions
+ *
+ * Exceptions thrown by Iconv.new, Iconv.open and Iconv#iconv.
+*/
 static VALUE
 iconv_s_iconv
 #ifdef HAVE_PROTOTYPES
@@ -612,14 +628,13 @@ iconv_s_iconv
 }
 
 /*
-=begin
---- Iconv.conv(to, from, str)
-    Shorthand for
-      Iconv.iconv(to, from, str).join
-    see ((<Iconv.iconv>))
-=end
-*/
-
+ * Document-method: Iconv::conv
+ * call-seq: Iconv.iconv(to, from, *strs)
+ *
+ * Shorthand for
+ *   Iconv.iconv(to, from, str).join
+ * See Iconv.iconv ???
+ */
 static VALUE
 iconv_s_conv
 #ifdef HAVE_PROTOTYPES
@@ -640,10 +655,10 @@ iconv_s_conv
 }
 
 /*
-=begin
---- Iconv.list {|*aliases| ... }
-    Iterates each alias sets.
-=end
+ * Document-method: list
+ * call-seq: Iconv.list {|*aliases| ... }
+ *
+ * Iterates each alias sets.
  */
 
 #ifdef HAVE_ICONVLIST
@@ -716,22 +731,16 @@ iconv_s_list _((void))
     return Qnil;
 }
 
-
 /*
-=begin
-=== Instance methods
-=end
-*/
-/*
-=begin
---- Iconv#close
-    Finishes conversion.
-    * After calling this, invoking method ((<Iconv#iconv>)) will cause
-      exception, but multiple calls of (({close})) are guaranteed to
-      end successfully.
-    * Returns a string contains the byte sequence to change the
-      output buffer to its initial shift state.
-=end
+ * Document-method: close
+ *
+ * Finishes conversion.
+ *
+ * After calling this, calling Iconv#iconv will cause an exception, but
+ * multiple calls of #close are guaranteed to end successfully.
+ *
+ * Returns a string containing the byte sequence to change the output buffer to
+ * its initial shift state.  <i>???</i>
 */
 static VALUE
 iconv_init_state
@@ -763,29 +772,31 @@ iconv_finish
 }
 
 /*
-=begin
---- Iconv#iconv(str, [ start = 0, [ length = -1 ] ])
-    Converts string and returns converted one.
-    * In the case of ((|str|)) is (({String})), converts (({str[start, length]})).
-      Returns converted string.
-    * In the case of ((|str|)) is (({nil})), places ((|converter|))
-      itself into initial shift state and just returns a string contains
-      the byte sequence to change the output buffer to its initial shift
-      state.
-    * Otherwise, causes exception.
-    :Parameters
-      :((|str|))
-        string to be converted or (({nil})).
-      :((|start|))
-        starting offset.
-      :((|length|))
-        conversion length,
-        (({nil})) or (({-1})) means whole string from (({start})).
-    :Exceptions
-      * ((<Iconv::IllegalSequence>))
-      * ((<Iconv::InvalidCharacter>))
-      * ((<Iconv::OutOfRange>))
-=end
+ * Document-method: iconv
+ * call-seq: iconv(str, start=0, length=-1)
+ *
+ * Converts string and returns the result.
+ * * If +str+ is a String, converts <tt>str[start, length]</tt> and returns the converted string.
+ * * If +str+ is +nil+, places converter itself into initial shift state and
+ *   just returns a string containing the byte sequence to change the output
+ *   buffer to its initial shift state.
+ * * Otherwise, raises an exception.
+ *
+ * === Parameters
+ *
+ * str::    string to be converted, or nil
+ * start::  starting offset
+ * length:: conversion length; nil or -1 means whole the string from start
+ *
+ * === Exceptions
+ *
+ * * IconvIllegalSequence
+ * * IconvInvalidCharacter
+ * * IconvOutOfRange
+ *
+ * === Examples
+ *
+ * See the Iconv documentation.
 */
 static VALUE
 iconv_iconv
@@ -806,33 +817,31 @@ iconv_iconv
 
     return iconv_convert(VALUE2ICONV(cd), str,
 			 NIL_P(n1) ? 0 : NUM2INT(n1),
-                        NIL_P(n2) ? -1 : NUM2INT(n2),
+			 NIL_P(n2) ? -1 : NUM2INT(n2),
 			 NULL);
 }
 
-
-/*
-=begin
-= Exceptions
-=end
-*/
-/*
-=begin
-== Iconv::Failure
-Base exceptional attributes from ((<Iconv>)).
-
-=== Instance methods
-=end
-*/
 /*
-=begin
---- Iconv::Failure#success
-    Returns string(s) translated successfully until the exception occurred.
-    * In the case of failure occurred within ((<Iconv.iconv>)), returned
-      value is an array of strings translated successfully preceding
-      failure and the last element is string on the way.
-=end
-*/
+ * Document-class: Iconv::Failure
+ *
+ * Base attributes for Iconv exceptions.
+ * 
+ * === Iconv::Failure#success
+ *
+ * Returns string(s) translated successfully until the exception occurred.
+ * * In the case of failure occurred within Iconv.iconv, returned
+ *   value is an array of strings translated successfully preceding
+ *   failure and the last element is string on the way.
+ *
+ * === Iconv::Failure#failed
+ * 
+ * Returns substring of the original string passed to Iconv that starts at the
+ * character caused the exception. 
+ *
+ * === Iconv::Failure#inspect
+ *
+ * Returns inspected string like as: #<_class_: _success_, _failed_>
+ */
 static VALUE
 iconv_failure_success
 #ifdef HAVE_PROTOTYPES
@@ -846,12 +855,8 @@ iconv_failure_success
 }
 
 /*
-=begin
---- Iconv::Failure#failed
-    Returns substring of the original string passed to ((<Iconv>)) that
-    starts at the character caused the exception. 
-=end
-*/
+ * Comment!
+ */
 static VALUE
 iconv_failure_failed
 #ifdef HAVE_PROTOTYPES
@@ -864,12 +869,6 @@ iconv_failure_failed
     return rb_attr_get(self, rb_failed);
 }
 
-/*
-=begin
---- Iconv::Failure#inspect
-    Returns inspected string like as: #<(({type})): "(({success}))", "(({failed}))">
-=end
-*/
 static VALUE
 iconv_failure_inspect
 #ifdef HAVE_PROTOTYPES
@@ -891,34 +890,49 @@ iconv_failure_inspect
 }
 
 /*
-  Hmmm, I don't like to write RD inside of function :-<.
-
-=begin
-== Iconv::IllegalSequence
-Input conversion stopped due to an input byte that does not belong to
-the input codeset, or the output codeset does not contain the
-character.
-=== Superclass
-(({ArgumentError}))
-=== Included Modules
-((<Iconv::Failure>))
-
-== Iconv::InvalidCharacter
-Input conversion stopped due to an incomplete character or shift
-sequence at the end of the input buffer.
-=== Superclass
-(({ArgumentError}))
-=== Included Modules
-((<Iconv::Failure>))
-
-== Iconv::OutOfRange
-Iconv library internal error.  Must not occur.
-=== Superclass
-(({RuntimeError}))
-=== Included Modules
-((<Iconv::Failure>))
-=end
-*/
+ * Document-class: Iconv::IllegalSequence
+ * 
+ * Input conversion stopped due to an input byte that does not belong to
+ * the input codeset, or the output codeset does not contain the
+ * character.
+ * 
+ * === Superclass
+ * 
+ * ArgumentError
+ * 
+ * === Included Modules
+ * 
+ * Iconv::Failure
+ */
+
+/*
+ * Document-class: Iconv::InvalidCharacter
+ * 
+ * Input conversion stopped due to an incomplete character or shift
+ * sequence at the end of the input buffer.
+ * 
+ * === Superclass
+ * 
+ * ArgumentError
+ * 
+ * === Included Modules
+ * 
+ * Iconv::Failure
+ */
+
+/*
+ * Document-class: Iconv::OutOfRange
+ * 
+ * Iconv library internal error.  Must not occur.
+ * 
+ * === Superclass
+ * 
+ * RuntimeError
+ * 
+ * === Included Modules
+ * 
+ * Iconv::Failure
+ */
 
 void
 Init_iconv _((void))
@@ -956,24 +970,3 @@ Init_iconv _((void))
     rb_define_singleton_method(rb_cIconv, "charset_map", charset_map_get, 0);
 }
 
-
-/*
-=begin
-== Example
-(1) Instantiate a new ((<Iconv>)), use method ((<Iconv#iconv>)).
-      cd = Iconv.new(to, from)
-      begin
-        input.each {|s| output << cd.iconv(s)}
-        output << cd.iconv(nil)      # don't forget this
-      ensure
-        cd.close
-      end
-(2) Invoke ((<Iconv.open>)) with a block.
-      Iconv.open(to, from) do |cd|
-        input.each {|s| output << cd.iconv(s)}
-        output << cd.iconv(nil)
-      end
-(3) Shorthand for (2).
-      Iconv.iconv(to, from, *input.to_a)
-=end
-*/
diff --git a/ext/strscan/strscan.c b/ext/strscan/strscan.c
index bdd9680367..0775de1fda 100644
--- a/ext/strscan/strscan.c
+++ b/ext/strscan/strscan.c
@@ -303,7 +303,8 @@ strscan_terminate(self)
 }
 
 /*
- * Returns the string being scanned.
+ * Equivalent to #terminate.
+ * This method is obsolete; use #terminate instead.
  */
 static VALUE
 strscan_clear(self)
@@ -313,6 +314,9 @@ strscan_clear(self)
     return strscan_terminate(self);
 }
 
+/*
+ * Returns the string being scanned.
+ */
 static VALUE
 strscan_get_string(self)
     VALUE self;
@@ -744,6 +748,10 @@ strscan_get_byte(self)
                             p->prev + p->regs.end[0]);
 }
 
+/*
+ * Equivalent to #get_byte.
+ * This method is obsolete; use #get_byte instead.
+ */
 static VALUE
 strscan_getbyte(self)
     VALUE self;
@@ -782,6 +790,18 @@ strscan_peek(self, vlen)
 }
 
 /*
+ * Equivalent to #peek.
+ * This method is obsolete; use #peek instead.
+ */
+static VALUE
+strscan_peep(self, vlen)
+    VALUE self, vlen;
+{
+    rb_warning("StringScanner#peep is obsolete; use #peek instead");
+    return strscan_peek(self, vlen);
+}
+
+/*
  * Set the scan pointer to the previous position.  Only one previous position is
  * remembered, and it changes with each scanning operation.
  *
@@ -793,14 +813,6 @@ strscan_peek(self, vlen)
  *   s.unscan             # ScanError: can't unscan: prev match had failed
  */
 static VALUE
-strscan_peep(self, vlen)
-    VALUE self, vlen;
-{
-    rb_warning("StringScanner#peep is obsolete; use #peek instead");
-    return strscan_peek(self, vlen);
-}
-
-static VALUE
 strscan_unscan(self)
     VALUE self;
 {
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index 25ce83dd8e..7e7b952583 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -596,7 +596,7 @@ module RDoc
     def do_includes
       @body.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
         if cls = @classes[c]
-          m = KNOWN_CLASSES[m] || m
+          m = @known_classes[m] || m
           cls.add_include(Include.new(m, ""))
         end
       end