* gc.c: Documentation for GC, GC::Profiler, ObjectSpace, and

  ObjectSpace::WeakMap [ruby-core:50245] [Bug #7449]


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

1 files changed, 116 insertions, 76 deletions

diff --git a/gc.c b/gc.c
index 8588d5025e..515fb8cde1 100644
--- a/gc.c
+++ b/gc.c
@@ -1669,26 +1669,33 @@ id2ref(VALUE obj, VALUE objid)
  *  Document-method: object_id
  *
  *  call-seq:
- *     obj.__id__       -> fixnum
- *     obj.object_id    -> fixnum
+ *     obj.__id__       -> integer
+ *     obj.object_id    -> integer
  *
- *  Returns an integer identifier for <i>obj</i>. The same number will
- *  be returned on all calls to <code>id</code> for a given object, and
- *  no two active objects will share an id.
- *  <code>Object#object_id</code> is a different concept from the
- *  <code>:name</code> notation, which returns the symbol id of
- *  <code>name</code>. Replaces the deprecated <code>Object#id</code>.
+ *  Returns an integer identifier for +obj+.
+ *
+ *  The same number will be returned on all calls to +id+ for a given object,
+ *  and no two active objects will share an id.
+ *
+ *  Object#object_id is a different concept from the +:name+ notation, which
+ *  returns the symbol id of +name+.
+ *
+ *  Replaces the deprecated Object#id.
  */
 
 /*
  *  call-seq:
  *     obj.hash    -> fixnum
  *
- *  Generates a <code>Fixnum</code> hash value for this object. This
- *  function must have the property that <code>a.eql?(b)</code> implies
- *  <code>a.hash == b.hash</code>. The hash value is used by class
- *  <code>Hash</code>. Any hash value that exceeds the capacity of a
- *  <code>Fixnum</code> will be truncated before being used.
+ *  Generates a Fixnum hash value for this object.
+ *
+ *  This function must have the property that <code>a.eql?(b)</code> implies
+ *  <code>a.hash == b.hash</code>.
+ *
+ *  The hash value is used by Hash class.
+ *
+ *  Any hash value that exceeds the capacity of a Fixnum will be truncated
+ *  before being used.
  */
 
 VALUE
@@ -1753,17 +1760,22 @@ set_zero(st_data_t key, st_data_t val, st_data_t arg)
  *
  *  Counts objects for each type.
  *
- *  It returns a hash as:
- *  {:TOTAL=>10000, :FREE=>3011, :T_OBJECT=>6, :T_CLASS=>404, ...}
- *
- *  If the optional argument, result_hash, is given,
- *  it is overwritten and returned.
- *  This is intended to avoid probe effect.
+ *  It returns a hash, such as:
+ *	{
+ *	  :TOTAL=>10000,
+ *	  :FREE=>3011,
+ *	  :T_OBJECT=>6,
+ *	  :T_CLASS=>404,
+ *	  # ...
+ *	}
  *
- *  The contents of the returned hash is implementation defined.
+ *  The contents of the returned hash are implementation specific.
  *  It may be changed in future.
  *
- *  This method is not expected to work except C Ruby.
+ *  If the optional argument +result_hash+ is given,
+ *  it is overwritten and returned. This is intended to avoid probe effect.
+ *
+ *  This method is only expected to work on C Ruby.
  *
  */
 
@@ -3136,18 +3148,19 @@ gc_count(VALUE self)
  *
  *  The hash includes information about internal statistics about GC such as:
  *
- *  {  :count=>0,
- *     :heap_used=>12,
- *     :heap_length=>12,
- *     :heap_increment=>0,
- *     :heap_live_num=>7539,
- *     :heap_free_num=>88,
- *     :heap_final_num=>0,
- *     :total_allocated_object=>7630,
- *     :total_freed_object=>88
- *  }
+ *	{
+ *	    :count=>0,
+ *	    :heap_used=>12,
+ *     	    :heap_length=>12,
+ *     	    :heap_increment=>0,
+ *     	    :heap_live_num=>7539,
+ *     	    :heap_free_num=>88,
+ *     	    :heap_final_num=>0,
+ *     	    :total_allocated_object=>7630,
+ *     	    :total_freed_object=>88
+ *	}
  *
- *  The contents of the hash are implementation defined and may be changed in
+ *  The contents of the hash are implementation specific and may be changed in
  *  the future.
  *
  *  This method is only expected to work on C Ruby.
@@ -3202,9 +3215,9 @@ gc_stat(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
- *    GC.stress                 -> true or false
+ *    GC.stress	    -> true or false
  *
- *  returns current status of GC stress mode.
+ *  Returns current status of GC stress mode.
  */
 
 static VALUE
@@ -3220,10 +3233,10 @@ gc_stress_get(VALUE self)
  *
  *  Updates the GC stress mode.
  *
- *  When stress mode is enabled the GC is invoked at every GC opportunity:
+ *  When stress mode is enabled, the GC is invoked at every GC opportunity:
  *  all memory and object allocations.
  *
- *  Enabling stress mode makes Ruby very slow, it is only for debugging.
+ *  Enabling stress mode will degrade performance, it is only for debugging.
  */
 
 static VALUE
@@ -3239,7 +3252,7 @@ gc_stress_set(VALUE self, VALUE flag)
  *  call-seq:
  *     GC.enable    -> true or false
  *
- *  Enables garbage collection, returning <code>true</code> if garbage
+ *  Enables garbage collection, returning +true+ if garbage
  *  collection was previously disabled.
  *
  *     GC.disable   #=> false
@@ -3262,7 +3275,7 @@ rb_gc_enable(void)
  *  call-seq:
  *     GC.disable    -> true or false
  *
- *  Disables garbage collection, returning <code>true</code> if garbage
+ *  Disables garbage collection, returning +true+ if garbage
  *  collection was already disabled.
  *
  *     GC.disable   #=> false
@@ -3661,8 +3674,9 @@ ruby_mimmalloc(size_t size)
  *  call-seq:
  *     GC.malloc_allocated_size -> Integer
  *
- *  Returns the size of memory allocated by malloc().  Only available if ruby
- *  was built with CALC_EXACT_MALLOC_SIZE.
+ *  Returns the size of memory allocated by malloc().
+ *
+ *  Only available if ruby was built with +CALC_EXACT_MALLOC_SIZE+.
  */
 
 static VALUE
@@ -3675,8 +3689,9 @@ gc_malloc_allocated_size(VALUE self)
  *  call-seq:
  *     GC.malloc_allocations -> Integer
  *
- *  Returns the number of malloc() allocations.  Only available if ruby was
- *  built with CALC_EXACT_MALLOC_SIZE.
+ *  Returns the number of malloc() allocations.
+ *
+ *  Only available if ruby was built with +CALC_EXACT_MALLOC_SIZE+.
  */
 
 static VALUE
@@ -3809,6 +3824,7 @@ wmap_finalize(VALUE self, VALUE objid)
     return self;
 }
 
+/* Creates a weak reference from the given key to the given value */
 static VALUE
 wmap_aset(VALUE self, VALUE wmap, VALUE orig)
 {
@@ -3831,6 +3847,7 @@ wmap_aset(VALUE self, VALUE wmap, VALUE orig)
     return nonspecial_obj_id(orig);
 }
 
+/* Retrieves a weakly referenced object with the given key */
 static VALUE
 wmap_aref(VALUE self, VALUE wmap)
 {
@@ -4101,28 +4118,51 @@ gc_profile_clear(void)
 
 /*
  *  call-seq:
- *     GC::Profiler.raw_data -> [Hash, ...]
+ *     GC::Profiler.raw_data	-> [Hash, ...]
  *
  *  Returns an Array of individual raw profile data Hashes ordered
- *  from earliest to latest by <tt>:GC_INVOKE_TIME</tt>.  For example:
+ *  from earliest to latest by +:GC_INVOKE_TIME+.
+ *
+ *  For example:
  *
- *    [{:GC_TIME=>1.3000000000000858e-05,
- *      :GC_INVOKE_TIME=>0.010634999999999999,
- *      :HEAP_USE_SIZE=>289640,
- *      :HEAP_TOTAL_SIZE=>588960,
- *      :HEAP_TOTAL_OBJECTS=>14724,
- *      :GC_IS_MARKED=>false},
- *      ...
+ *    [
+ *	{
+ *	   :GC_TIME=>1.3000000000000858e-05,
+ *	   :GC_INVOKE_TIME=>0.010634999999999999,
+ *	   :HEAP_USE_SIZE=>289640,
+ *	   :HEAP_TOTAL_SIZE=>588960,
+ *	   :HEAP_TOTAL_OBJECTS=>14724,
+ *	   :GC_IS_MARKED=>false
+ *	},
+ *      # ...
  *    ]
  *
  *  The keys mean:
  *
- *  +:GC_TIME+:: Time taken for this run in seconds
- *  +:GC_INVOKE_TIME+:: Time the GC was invoked since startup in seconds
- *  +:HEAP_USE_SIZE+:: Bytes of heap used
- *  +:HEAP_TOTAL_SIZE+:: Size of heap in bytes
- *  +:HEAP_TOTAL_OBJECTS+:: Number of objects
- *  +:GC_IS_MARKED+:: Is the GC in the mark phase
+ *  +:GC_TIME+::
+ *	Time elapsed in seconds for this GC run
+ *  +:GC_INVOKE_TIME+::
+ *	Time elapsed in seconds from startup to when the GC was invoked
+ *  +:HEAP_USE_SIZE+::
+ *	Total bytes of heap used
+ *  +:HEAP_TOTAL_SIZE+::
+ *	Total size of heap in bytes
+ *  +:HEAP_TOTAL_OBJECTS+::
+ *	Total number of objects
+ *  +:GC_IS_MARKED+::
+ *	Returns +true+ if the GC is in mark phase
+ *
+ *  If ruby was built with +GC_PROFILE_MORE_DETAIL+, you will also have access
+ *  to the following hash keys:
+ *
+ *  +:GC_MARK_TIME+::
+ *  +:GC_SWEEP_TIME+::
+ *  +:ALLOCATE_INCREASE+::
+ *  +:ALLOCATE_LIMIT+::
+ *  +:HEAP_USE_SLOTS+::
+ *  +:HEAP_LIVE_OBJECTS+::
+ *  +:HEAP_FREE_OBJECTS+::
+ *  +:HAVE_FINALIZE+::
  *
  */
 
@@ -4204,7 +4244,7 @@ gc_profile_dump_on(VALUE out, VALUE (*append)(VALUE, VALUE))
 
 /*
  *  call-seq:
- *     GC::Profiler.result -> String
+ *     GC::Profiler.result  -> String
  *
  *  Returns a profile data report such as:
  *
@@ -4224,9 +4264,9 @@ gc_profile_result(void)
 /*
  *  call-seq:
  *     GC::Profiler.report
- *     GC::Profiler.report io
+ *     GC::Profiler.report(io)
  *
- *  Writes the GC::Profiler#result to <tt>$stdout</tt> or the given IO object.
+ *  Writes the GC::Profiler.result to <tt>$stdout</tt> or the given IO object.
  *
  */
 
@@ -4248,7 +4288,7 @@ gc_profile_report(int argc, VALUE *argv, VALUE self)
 
 /*
  *  call-seq:
- *     GC::Profiler.total_time -> float
+ *     GC::Profiler.total_time	-> float
  *
  *  The total time used for garbage collection in seconds
  */
@@ -4270,7 +4310,7 @@ gc_profile_total_time(VALUE self)
 
 /*
  *  call-seq:
- *    GC::Profiler.enabled?                 -> true or false
+ *    GC::Profiler.enabled?	-> true or false
  *
  *  The current status of GC profile mode.
  */
@@ -4284,7 +4324,7 @@ gc_profile_enable_get(VALUE self)
 
 /*
  *  call-seq:
- *    GC::Profiler.enable          -> nil
+ *    GC::Profiler.enable	-> nil
  *
  *  Starts the GC profiler.
  *
@@ -4301,7 +4341,7 @@ gc_profile_enable(void)
 
 /*
  *  call-seq:
- *    GC::Profiler.disable          -> nil
+ *    GC::Profiler.disable	-> nil
  *
  *  Stops the GC profiler.
  *
@@ -4364,27 +4404,25 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
 /*
  * Document-class: ObjectSpace
  *
- *  The <code>ObjectSpace</code> module contains a number of routines
+ *  The ObjectSpace 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.
+ *  ObjectSpace 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>
+ *  _produces:_
  *
  *     Finalizer three on 537763470
  *     Finalizer one on 537763480
@@ -4395,7 +4433,7 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
 /*
  *  Document-class: ObjectSpace::WeakMap
  *
- *  An <code>ObjectSpace::WeakMap</code> object holds references to
+ *  An ObjectSpace::WeakMap object holds references to
  *  any objects, but those objects can get disposed by GC.
  */
 
@@ -4410,7 +4448,7 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
  *
  *    require 'rdoc/rdoc'
  *
- *    puts GC::Profiler.result
+ *    GC::Profiler.report
  *
  *    GC::Profiler.disable
  *
@@ -4418,9 +4456,11 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
  */
 
 /*
- *  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 ObjectSpace module.
+ *  The GC module provides an interface to Ruby's mark and
+ *  sweep garbage collection mechanism.
+ *
+ *  Some of the underlying methods are also available via the ObjectSpace
+ *  module.
  *
  *  You may obtain information about the operation of the GC through
  *  GC::Profiler.