* io.c: rdoc for File::open and 1.9 feature in file modes.

* transcode.c: rdoc for String#encode

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

1 files changed, 95 insertions, 28 deletions

diff --git a/io.c b/io.c
index 93855f917b..b6f85f5861 100644
--- a/io.c
+++ b/io.c
@@ -4914,7 +4914,26 @@ rb_open_file(int argc, VALUE *argv, VALUE io)
     return io;
 }
 
+
+/*
+ *  Document-method: File::open
+ *
+ *  call-seq:
+ *     File.open(filename, mode="r" [, opt])                 => file
+ *     File.open(filename [, mode [, perm]] [, opt])         => file
+ *     File.open(filename, mode="r" [, opt]) {|file| block } => obj
+ *     File.open(filename [, mode [, perm]] [, opt]) {|file| block } => obj
+ *
+ *  With no associated block, <code>open</code> is a synonym for
+ *  <code>File.new</code>. If the optional code block is given, it will
+ *  be passed <i>file</i> as an argument, and the File object will
+ *  automatically be closed when the block terminates. In this instance,
+ *  <code>File.open</code> returns the value of the block.
+ */
+
 /*
+ *  Document-method: IO::open
+ *
  *  call-seq:
  *     IO.open(fd, mode_string="r" [, opt] )               => io
  *     IO.open(fd, mode_string="r" [, opt] ) {|io| block } => obj
@@ -5815,6 +5834,48 @@ rb_io_stdio_file(rb_io_t *fptr)
  *  <code>IO</code> object or integer file descriptor and mode
  *  string. See also <code>IO#fileno</code> and
  *  <code>IO.for_fd</code>.
+ *  
+ *  === Parameters
+ *  fd:: numeric file descriptor
+ *  mode:: file mode. a string or an integer
+ *  opt:: hash for specifiying mode by name.
+ *
+ *  ==== Mode
+ *  When <code>mode</code> is an integer it must be combination of
+ *  the modes defined in <code>File::Constants</code>.
+ *
+ *  When <code>mode</code> is a string it must be in one of the 
+ *  following forms:
+ *  - "fmode",
+ *  - "fmode:extern",
+ *  - "fmode:extern:intern".
+ *  <code>extern</code> is the external encoding name for the IO. 
+ *  <code>intern</code> is the internal encoding.
+ *  <code>fmode</code> must be combination of the directives. See
+ *  the description of class +IO+ for a description of the directives.
+ *
+ *  ==== Options
+ *  <code>opt</code> can have the following keys
+ *  :mode ::
+ *    same as <code>mode</code> parameter
+ *  :external_encoding :: 
+ *    external encoding for the IO. "-" is a 
+ *    synonym for the default external encoding.
+ *  :internal_encoding ::
+ *    internal encoding for the IO. 
+ *    "-" is a synonym for the default internal encoding.
+ *    If the value is nil no conversion occurs. 
+ *  :encoding :: 
+ *    specifies external and internal encodings as "extern:intern".
+ *  :textmode ::
+ *    If the value is truth value, same as "b" in argument <code>mode</code>.
+ *  :binmode ::
+ *    If the value is truth value, same as "t" in argument <code>mode</code>.
+ *  
+ *  Also <code>opt</code> can have same keys in <code>String#encode</code> for
+ *  controlling conversion between the external encoding and the internal encoding.
+ *
+ *  === Example1
  *
  *     puts IO.new($stdout).fileno # => 1
  *
@@ -5826,6 +5887,16 @@ rb_io_stdio_file(rb_io_t *fptr)
  *
  *     Hello
  *     World
+ *
+ *  === Example2
+ *     io = IO.new(2, mode: 'w:UTF-16LE', cr_newline: true)
+ *     io.puts "Hello, World!"
+ *
+ *     io = IO.new(2, mode: 'w', cr_newline: true, external_encoding: Encoding::UTF_16LE)
+ *     io.puts "Hello, World!"
+ *
+ *  both of aboves print "Hello, World!" in UTF-16LE to standard error output with 
+ *  converting EOL generated by <code>puts</code> to CR.
  */
 
 static VALUE
@@ -5862,22 +5933,28 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io)
     return io;
 }
 
-
 /*
  *  call-seq:
  *     File.new(filename, mode="r" [, opt])            => file
  *     File.new(filename [, mode [, perm]] [, opt])    => file
  *
-
  *  Opens the file named by _filename_ according to
  *  _mode_ (default is ``r'') and returns a new
- *  <code>File</code> object. See the description of class +IO+ for
- *  a description of _mode_. The file mode may optionally be
- *  specified as a +Fixnum+ by _or_-ing together the
- *  flags (O_RDONLY etc, again described under +IO+). Optional
- *  permission bits may be given in _perm_. These mode and permission
- *  bits are platform dependent; on Unix systems, see
- *  <code>open(2)</code> for details.
+ *  <code>File</code> object. 
+ * 
+ *  === Parameters
+ *  See the description of class +IO+ for a description of _mode_. 
+ *  The file mode may optionally be specified as a +Fixnum+ 
+ *  by _or_-ing together the flags (O_RDONLY etc, 
+ *  again described under +IO+). 
+ *
+ *  Optional permission bits may be given in _perm_. 
+ *  These mode and permission bits are platform dependent; 
+ *  on Unix systems, see <code>open(2)</code> for details.
+ *
+ *  Optional _opt_ parameter is same as in <code.IO.open</code>.
+ *
+ *  === Examples
  *
  *     f = File.new("testfile", "r")
  *     f = File.new("newfile",  "w+")
@@ -5903,24 +5980,6 @@ rb_file_initialize(int argc, VALUE *argv, VALUE io)
     return io;
 }
 
-/*
- *  call-seq:
- *     IO.new(fd, mode_string [, opt])   => io
- *
- *  Returns a new <code>IO</code> object (a stream) for the given
- *  integer file descriptor and mode string. See also
- *  <code>IO#fileno</code> and <code>IO.for_fd</code>.
- *
- *     a = IO.new(2,"w")      # '2' is standard error
- *     $stderr.puts "Hello"
- *     a.puts "World"
- *
- *  <em>produces:</em>
- *
- *     Hello
- *     World
- */
-
 static VALUE
 rb_io_s_new(int argc, VALUE *argv, VALUE klass)
 {
@@ -8399,8 +8458,11 @@ rb_get_argv(void)
  *         |  otherwise creates a new file for reading and
  *         |  writing.
  *    -----+--------------------------------------------------------
- *     "b" |  (DOS/Windows only) Binary file mode (may appear with
+ *     "b" |  Binary file mode (may appear with
  *         |  any of the key letters listed above).
+ *         |  Suppresses EOL <-> CRLF conversion on Windows. And
+ *         |  sets external encoding to ASCII-8BIT unless explicitly
+ *         |  specified.
  *    -----+--------------------------------------------------------
  *     "t" |  Text file mode (may appear with
  *         |  any of the key letters listed above except "b").
@@ -8463,6 +8525,11 @@ Init_IO(void)
     rb_cIO = rb_define_class("IO", rb_cObject);
     rb_include_module(rb_cIO, rb_mEnumerable);
 
+#if 0
+    /* This is necessary only for forcing rdoc handle File::open */
+    rb_define_singleton_method(rb_cFile, "open",  rb_io_s_open, -1);
+#endif
+
     rb_define_alloc_func(rb_cIO, io_alloc);
     rb_define_singleton_method(rb_cIO, "new", rb_io_s_new, -1);
     rb_define_singleton_method(rb_cIO, "open",  rb_io_s_open, -1);