RDoc comments added by Elliott Hughes

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

marshal.c

@@ -691,6 +691,32 @@ dump_ensure(arg)
     return 0;
 }
 
+/*
+ * call-seq:
+ *      dump( obj [, anIO] , limit=--1 ) => anIO
+ *
+ * Serializes obj and all descendent objects. If anIO is
+ * specified, the serialized data will be written to it, otherwise the
+ * data will be returned as a String. If limit is specified, the
+ * traversal of subobjects will be limited to that depth. If limit is
+ * negative, no checking of depth will be performed.
+ *
+ *     class Klass
+ *       def initialize(str)
+ *         @str = str
+ *       end
+ *       def sayHello
+ *         @str
+ *       end
+ *     end
+ *
+ * (produces no output)
+ *
+ *     o = Klass.new("hello\n")
+ *     data = Marshal.dump(o)
+ *     obj = Marshal.load(data)
+ *     obj.sayHello   #=> "hello\n"
+ */
 static VALUE
 marshal_dump(argc, argv)
     int argc;
@@ -1332,6 +1358,17 @@ load_ensure(arg)
     return 0;
 }
 
+/*
+ * call-seq:
+ *     load( source [, proc] ) => obj
+ *     restore( source [, proc] ) => obj
+ * 
+ * Returns the result of converting the serialized data in source into a
+ * Ruby object (possibly with associated subordinate objects). source
+ * may be either an instance of IO or an object that responds to
+ * to_str. If proc is specified, it will be passed each object as it
+ * is deserialized.
+ */
 static VALUE
 marshal_load(argc, argv)
     int argc;
@@ -1383,6 +1420,39 @@ marshal_load(argc, argv)
     return v;
 }
 
+/*
+ * The marshaling library converts collections of Ruby objects into a
+ * byte stream, allowing them to be stored outside the currently
+ * active script. This data may subsequently be read and the original
+ * objects reconstituted.
+ * Marshaled data has major and minor version numbers stored along
+ * with the object information. In normal use, marshaling can only
+ * load data written with the same major version number and an equal
+ * or lower minor version number. If Ruby's ``verbose'' flag is set
+ * (normally using -d, -v, -w, or --verbose) the major and minor
+ * numbers must match exactly. Marshal versioning is independent of
+ * Ruby's version numbers. You can extract the version by reading the
+ * first two bytes of marshaled data.
+ *
+ *     str = Marshal.dump("thing")
+ *     RUBY_VERSION   #=> "1.8.0"
+ *     str[0]         #=> 4
+ *     str[1]         #=> 8
+ *
+ * Some objects cannot be dumped: if the objects to be dumped include
+ * bindings, procedure or method objects, instances of class IO, or
+ * singleton objects, a TypeError will be raised.
+ * If your class has special serialization needs (for example, if you
+ * want to serialize in some specific format), or if it contains
+ * objects that would otherwise not be serializable, you can implement
+ * your own serialization strategy by defining two methods, _dump and
+ * _load:
+ * The instance method _dump should return a String object containing
+ * all the information necessary to reconstitute objects of this class
+ * and all referenced objects up to a maximum depth given as an integer
+ * parameter (a value of -1 implies that you should disable depth checking).
+ * The class method _load should take a String and return an object of this class.
+ */
 void
 Init_marshal()
 {

signal.c

@@ -643,6 +643,34 @@ rb_trap_restore_mask()
 #endif
 }
 
+/*
+ * call-seq:
+ *   Signal.trap( signal, proc ) => obj
+ *   Signal.trap( signal ) {| | block } => obj
+ *
+ * Specifies the handling of signals. The first parameter is a signal
+ * name (a string such as ``SIGALRM'', ``SIGUSR1'', and so on) or a
+ * signal number. The characters ``SIG'' may be omitted from the
+ * signal name. The command or block specifies code to be run when the
+ * signal is raised. If the command is the string ``IGNORE'' or
+ * ``SIG_IGN'', the signal will be ignored. If the command is
+ * ``DEFAULT'' or ``SIG_DFL'', the operating system's default handler
+ * will be invoked. If the command is ``EXIT'', the script will be
+ * terminated by the signal. Otherwise, the given command or block
+ * will be run.
+ * The special signal name ``EXIT'' or signal number zero will be
+ * invoked just prior to program termination.
+ * trap returns the previous handler for the given signal.
+ *
+ *     Signal.trap(0, proc { puts "Terminating: #{$$}" })
+ *     Signal.trap("CLD")  { puts "Child died" }
+ *     fork && Process.wait
+ *
+ * produces:
+ *     Terminating: 27461
+ *     Child died
+ *     Terminating: 27460
+ */
 static VALUE
 sig_trap(argc, argv)
     int argc;
@@ -681,6 +709,15 @@ sig_trap(argc, argv)
 #endif
 }
 
+/*
+ * call-seq:
+ *   Signal.list => a_hash
+ *
+ * Returns a list of signal names mapped to the corresponding
+ * underlying signal numbers.
+ *
+ * Signal.list   #=> {"ABRT"=>6, "ALRM"=>14, "BUS"=>7, "CHLD"=>17, "CLD"=>17, "CONT"=>18, "FPE"=>8, "HUP"=>1, "ILL"=>4, "INT"=>2, "IO"=>29, "IOT"=>6, "KILL"=>9, "PIPE"=>13, "POLL"=>29, "PROF"=>27, "PWR"=>30, "QUIT"=>3, "SEGV"=>11, "STOP"=>19, "SYS"=>31, "TERM"=>15, "TRAP"=>5, "TSTP"=>20, "TTIN"=>21, "TTOU"=>22, "URG"=>23, "USR1"=>10, "USR2"=>12, "VTALRM"=>26, "WINCH"=>28, "XCPU"=>24, "XFSZ"=>25}
+ */
 static VALUE
 sig_list()
 {
@@ -748,6 +785,43 @@ init_sigchld(sig)
 #endif
 }
 
+/*
+ * Many operating systems allow signals to be sent to running
+ * processes. Some signals have a defined effect on the process, while
+ * others may be trapped at the code level and acted upon. For
+ * example, your process may trap the USR1 signal and use it to toggle
+ * debugging, and may use TERM to initiate a controlled shutdown.
+ *
+ *     pid = fork do
+ *       Signal.trap("USR1") do
+ *         $debug = !$debug
+ *         puts "Debug now: #$debug"
+ *       end
+ *       Signal.trap("TERM") do
+ *         puts "Terminating..."
+ *         shutdown()
+ *       end
+ *       # . . . do some work . . .
+ *     end
+ *
+ *     Process.detach(pid)
+ *
+ *     # Controlling program:
+ *     Process.kill("USR1", pid)
+ *     # ...
+ *     Process.kill("USR1", pid)
+ *     # ...
+ *     Process.kill("TERM", pid)
+ *
+ * produces:
+ *     Debug now: true
+ *     Debug now: false
+ *    Terminating...
+ *
+ * The list of available signal names and their interpretation is
+ * system dependent. Signal delivery semantics may also vary between
+ * systems; in particular signal delivery may not always be reliable.
+ */
 void
 Init_signal()
 {