Add RDoc comments

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

1 files changed, 150 insertions, 0 deletions

diff --git a/gc.c b/gc.c
index 9e4ac5ae38..c521e58fea 100644
--- a/gc.c
+++ b/gc.c
@@ -176,6 +176,20 @@ static int during_gc;
 static int need_call_final = 0;
 static st_table *finalizer_table = 0;
 
+
+/*
+ *  call-seq:
+ *     GC.enable    => true or false
+ *  
+ *  Enables garbage collection, returning <code>true</code> if garbage
+ *  collection was previously disabled.
+ *     
+ *     GC.disable   #=> false
+ *     GC.enable    #=> true
+ *     GC.enable    #=> false
+ *     
+ */
+
 VALUE
 rb_gc_enable()
 {
@@ -185,6 +199,18 @@ rb_gc_enable()
     return old;
 }
 
+/*
+ *  call-seq:
+ *     GC.disable    => true or false
+ *  
+ *  Disables garbage collection, returning <code>true</code> if garbage
+ *  collection was already disabled.
+ *     
+ *     GC.disable   #=> false
+ *     GC.disable   #=> true
+ *     
+ */
+
 VALUE
 rb_gc_disable()
 {
@@ -1359,6 +1385,16 @@ rb_gc()
     gc_sweep();
 }
 
+/*
+ *  call-seq:
+ *     GC.start                     => nil
+ *     gc.garbage_collect           => nil
+ *     ObjectSpace.garbage_collect  => nil
+ *
+ *  Initiates garbage collection, unless manually disabled.
+ *     
+ */
+
 VALUE
 rb_gc_start()
 {
@@ -1406,6 +1442,38 @@ Init_stack(addr)
 #endif
 }
 
+
+/*
+ * Document-class: ObjectSpace
+ *
+ *  The <code>ObjectSpace</code> module contains a number of routines
+ *  that interact with the garbage collection facility and allow you to
+ *  traverse all living objects with an iterator.
+ *     
+ *  <code>ObjectSpace</code> also provides support for object
+ *  finalizers, procs that will be called when a specific object is
+ *  about to be destroyed by garbage collection.
+ *     
+ *     include ObjectSpace
+ *     
+ *     
+ *     a = "A"
+ *     b = "B"
+ *     c = "C"
+ *     
+ *     
+ *     define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
+ *     define_finalizer(a, proc {|id| puts "Finalizer two on #{id}" })
+ *     define_finalizer(b, proc {|id| puts "Finalizer three on #{id}" })
+ *     
+ *  <em>produces:</em>
+ *     
+ *     Finalizer three on 537763470
+ *     Finalizer one on 537763480
+ *     Finalizer two on 537763480
+ *     
+ */
+
 void
 Init_heap()
 {
@@ -1482,6 +1550,39 @@ os_obj_of(of)
     return INT2FIX(n);
 }
 
+/*
+ *  call-seq:
+ *     ObjectSpace.each_object([module]) {|obj| ... } => fixnum
+ *  
+ *  Calls the block once for each living, nonimmediate object in this
+ *  Ruby process. If <i>module</i> is specified, calls the block
+ *  for only those classes or modules that match (or are a subclass of)
+ *  <i>module</i>. Returns the number of objects found. Immediate
+ *  objects (<code>Fixnum</code>s, <code>Symbol</code>s
+ *  <code>true</code>, <code>false</code>, and <code>nil</code>) are
+ *  never returned. In the example below, <code>each_object</code>
+ *  returns both the numbers we defined and several constants defined in
+ *  the <code>Math</code> module.
+ *     
+ *     a = 102.7
+ *     b = 95       # Won't be returned
+ *     c = 12345678987654321
+ *     count = ObjectSpace.each_object(Numeric) {|x| p x }
+ *     puts "Total count: #{count}"
+ *     
+ *  <em>produces:</em>
+ *     
+ *     12345678987654321
+ *     102.7
+ *     2.71828182845905
+ *     3.14159265358979
+ *     2.22044604925031e-16
+ *     1.7976931348623157e+308
+ *     2.2250738585072e-308
+ *     Total count: 7
+ *     
+ */
+
 static VALUE
 os_each_obj(argc, argv)
     int argc;
@@ -1500,6 +1601,9 @@ os_each_obj(argc, argv)
 
 static VALUE finalizers;
 
+/* deprecated
+ */
+
 static VALUE
 add_final(os, block)
     VALUE os, block;
@@ -1513,6 +1617,9 @@ add_final(os, block)
     return block;
 }
 
+/*
+ * deprecated
+ */
 static VALUE
 rm_final(os, block)
     VALUE os, block;
@@ -1522,6 +1629,9 @@ rm_final(os, block)
     return block;
 }
 
+/*
+ * deprecated
+ */
 static VALUE
 finals()
 {
@@ -1529,6 +1639,10 @@ finals()
     return finalizers;
 }
 
+/*
+ * deprecated
+ */
+
 static VALUE
 call_final(os, obj)
     VALUE os, obj;
@@ -1539,6 +1653,14 @@ call_final(os, obj)
     return obj;
 }
 
+/*
+ *  call-seq:
+ *     ObjectSpace.undefine_finalizer(obj)
+ *  
+ *  Removes all finalizers for <i>obj</i>.
+ *     
+ */
+
 static VALUE
 undefine_final(os, obj)
     VALUE os, obj;
@@ -1549,6 +1671,15 @@ undefine_final(os, obj)
     return obj;
 }
 
+/*
+ *  call-seq:
+ *     ObjectSpace.define_finalizer(obj, aProc=proc())
+ *  
+ *  Adds <i>aProc</i> as a finalizer, to be called when <i>obj</i>
+ *  is about to be destroyed.
+ *     
+ */
+
 static VALUE
 define_final(argc, argv, os)
     int argc;
@@ -1678,6 +1809,19 @@ rb_gc_call_finalizer_at_exit()
     }
 }
 
+/*
+ *  call-seq:
+ *     ObjectSpace._id2ref(object_id) -> an_object
+ *  
+ *  Converts an object id to a reference to the object. May not be
+ *  called on an object id passed as a parameter to a finalizer.
+ *     
+ *     s = "I am a string"                    #=> "I am a string"
+ *     r = ObjectSpace._id2ref(s.object_id)   #=> "I am a string"
+ *     r == s                                 #=> true
+ *     
+ */
+
 static VALUE
 id2ref(obj, id)
     VALUE obj, id;
@@ -1704,6 +1848,12 @@ id2ref(obj, id)
     return (VALUE)ptr;
 }
 
+/*
+ *  The <code>GC</code> module provides an interface to Ruby's mark and
+ *  sweep garbage collection mechanism. Some of the underlying methods
+ *  are also available via the <code>ObjectSpace</code> module.
+ */
+
 void
 Init_GC()
 {