From 49af08e1887326f74cabef7b92dfd814ad7c144b Mon Sep 17 00:00:00 2001 From: nobu Date: Fri, 4 Mar 2005 10:40:09 +0000 Subject: [PATCH] * 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 --- ChangeLog | 15 +- ext/iconv/iconv.c | 413 ++++++++++++++++++------------------ ext/strscan/strscan.c | 30 ++- lib/rdoc/parsers/parse_c.rb | 2 +- 4 files changed, 237 insertions(+), 223 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 + + * 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 * eval.c (rb_exec_recursive): matched the declaration to prototype. @@ -47,7 +56,7 @@ Fri Mar 4 08:09:12 2005 Yukihiro Matsumoto Thu Mar 4 07:07:00 2005 NARUSE, Yui - * 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 @@ -418,7 +427,7 @@ Wed Feb 16 02:47:45 2005 GOTOU Yuuzou Tue Feb 15 22:14:34 2005 sheepman - * 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 @@ -3403,7 +3412,7 @@ Thu Oct 21 21:32:30 2004 IWATSUKI Hiroyuki * 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 * 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,28 +10,10 @@ All the files in this distribution are covered under the Ruby's license (see the file COPYING). + Documentation by Yukihiro Matsumoto and Gavin Sinclair. + **********************************************************************/ -/* -=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. - -See (())'s on-line documents for more details. -* (()) -* (()) -* (()) -* (()) - -Which coding systems are available, it depends on the platform. - -=end -*/ - #include "ruby.h" #include #include @@ -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 iconv() function family, + * which translates string between various encoding systems. + * + * See Open Group's on-line documents for more details. + * * iconv.h: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html + * * iconv_open(): http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html + * * iconv(): http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.html + * * iconv_close(): 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 (()) 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 iconv_open3 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 (()). - :((|strs|)) - strings to be converted. - :Exceptions - exceptions thrown by (()), (()) and - (()). -=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 + * + * to, from:: see Iconv.new + * strs:: 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 (()) -=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 (()) 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. ??? */ 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 - * (()) - * (()) - * (()) -=end + * Document-method: iconv + * call-seq: iconv(str, start=0, length=-1) + * + * Converts string and returns the result. + * * If +str+ is a String, converts str[start, length] 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 (()). - -=== Instance methods -=end -*/ -/* -=begin ---- Iconv::Failure#success - Returns string(s) translated successfully until the exception occurred. - * In the case of failure occurred within (()), 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 (()) 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 :-<. + * 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 + */ -=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 -(()) +/* + * 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 + */ -== 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::OutOfRange -Iconv library internal error. Must not occur. -=== Superclass -(({RuntimeError})) -=== Included Modules -(()) -=end -*/ +/* + * 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 (()), use method (()). - 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 (()) 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; @@ -781,6 +789,18 @@ strscan_peek(self, vlen) return extract_beg_len(p, p->curr, len); } +/* + * 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. @@ -792,14 +812,6 @@ strscan_peek(self, vlen) * s.scan(/\d/) # => nil * 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