zzak	2013-06-18 22:05:32 +0900 (Tue, 18 Jun 2013)

  New Revision: 41385

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=41385

  Log:
    * ext/objspace/object_tracing.c: Document object_tracing methods.

  Modified files:
    trunk/ChangeLog
    trunk/ext/objspace/object_tracing.c

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 41384)
+++ ChangeLog	(revision 41385)
@@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Tue Jun 18 22:04:35 2013  Zachary Scott  <zachary@z...>
+
+	* ext/objspace/object_tracing.c: Document object_tracing methods.
+
 Tue Jun 18 21:58:17 2013  Zachary Scott  <zachary@z...>
 
 	* gc.c: Rename rb_mObSpace -> rb_mObjSpace
Index: ext/objspace/object_tracing.c
===================================================================
--- ext/objspace/object_tracing.c	(revision 41384)
+++ ext/objspace/object_tracing.c	(revision 41385)
@@ -144,6 +144,32 @@ stop_trace_object_allocations(void *data https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L144
     return Qnil;
 }
 
+/*
+ * call-seq: trace_object_allocations { block }
+ *
+ * Starts tracing object allocations from the ObjectSpace extension module.
+ *
+ * For example:
+ *
+ *	require 'objspace'
+ *
+ *	class C
+ *	  include ObjectSpace
+ *
+ *	  def foo
+ *	    trace_object_allocations do
+ *	      obj = Object.new
+ *	      p "#{allocation_sourcefile(obj)}:#{allocation_sourceline(obj)}"
+ *	    end
+ *	  end
+ *	end
+ *
+ *	C.new.foo #=> "objtrace.rb:8"
+ *
+ * This example has included the ObjectSpace module to make it easier to read,
+ * but you can also use the
+ * "<code>ObjectSpace::trace_object_allocations</code>" notation.
+ */
 static VALUE
 trace_object_allocations(VALUE objspace)
 {
@@ -175,6 +201,13 @@ lookup_allocation_info(VALUE obj) https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L201
     return NULL;
 }
 
+/*
+ * call-seq: allocation_sourcefile(object) -> string
+ *
+ * Returns the source file origin from the given +object+.
+ *
+ * See ::trace_object_allocations for more information and examples.
+ */
 static VALUE
 allocation_sourcefile(VALUE objspace, VALUE obj)
 {
@@ -187,6 +220,13 @@ allocation_sourcefile(VALUE objspace, VA https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L220
     }
 }
 
+/*
+ * call-seq: allocation_sourceline(object) -> string
+ *
+ * Returns the original line from source for from the given +object+.
+ *
+ * See ::trace_object_allocations for more information and examples.
+ */
 static VALUE
 allocation_sourceline(VALUE objspace, VALUE obj)
 {
@@ -199,6 +239,24 @@ allocation_sourceline(VALUE objspace, VA https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L239
     }
 }
 
+/*
+ * call-seq: allocation_class_path(object) -> string
+ *
+ * Returns the class for the given +object+.
+ *
+ *	class A
+ *	  def foo
+ *	    ObjectSpace::trace_object_allocations do
+ *	      obj = Object.new
+ *	      p "#{ObjectSpace::allocation_class_path(obj)}"
+ *	    end
+ *	  end
+ *	end
+ *
+ *	A.new.foo #=> "Class"
+ *
+ * See ::trace_object_allocations for more information and examples.
+ */
 static VALUE
 allocation_class_path(VALUE objspace, VALUE obj)
 {
@@ -211,6 +269,26 @@ allocation_class_path(VALUE objspace, VA https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L269
     }
 }
 
+/*
+ * call-seq: allocation_method_id(object) -> string
+ *
+ * Returns the method identifier for the given +object+.
+ *
+ *	class A
+ *	  include ObjectSpace
+ *
+ *	  def foo
+ *	    trace_object_allocations do
+ *	      obj = Object.new
+ *	      p "#{allocation_class_path(obj)}##{allocation_method_id(obj)}"
+ *	    end
+ *	  end
+ *	end
+ *
+ *	A.new.foo #=> "Class#new"
+ *
+ * See ::trace_object_allocations for more information and examples.
+ */
 static VALUE
 allocation_method_id(VALUE objspace, VALUE obj)
 {
@@ -223,6 +301,26 @@ allocation_method_id(VALUE objspace, VAL https://github.com/ruby/ruby/blob/trunk/ext/objspace/object_tracing.c#L301
     }
 }
 
+/*
+ * call-seq: allocation_allocation_generation(object) -> 
+ *
+ * Returns garbage collector generation for the given +object+.
+ *
+ *	class B
+ *	  include ObjectSpace
+ *
+ *	  def foo
+ *	    trace_object_allocations do
+ *	      obj = Object.new
+ *	      p "Generation is #{allocation_generation(obj)}"
+ *	    end
+ *	  end
+ *	end
+ *
+ *	B.new.foo #=> "Generation is 3"
+ *
+ * See ::trace_object_allocations for more information and examples.
+ */
 static VALUE
 allocation_generation(VALUE objspace, VALUE obj)
 {

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/