From b8df950282ec7d97c864a606334d28d78c4a869c Mon Sep 17 00:00:00 2001
From: zzak <zzak@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Tue, 18 Jun 2013 13:05:32 +0000
Subject: [PATCH] * ext/objspace/object_tracing.c: Document object_tracing
 methods.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@41385 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog                     |  4 ++
 ext/objspace/object_tracing.c | 98 +++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 94154916ff..540c67eace 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+Tue Jun 18 22:04:35 2013  Zachary Scott  <zachary@zacharyscott.net>
+
+	* ext/objspace/object_tracing.c: Document object_tracing methods.
+
 Tue Jun 18 21:58:17 2013  Zachary Scott  <zachary@zacharyscott.net>
 
 	* gc.c: Rename rb_mObSpace -> rb_mObjSpace
diff --git a/ext/objspace/object_tracing.c b/ext/objspace/object_tracing.c
index b30862999e..6816f503bc 100644
--- a/ext/objspace/object_tracing.c
+++ b/ext/objspace/object_tracing.c
@@ -144,6 +144,32 @@ stop_trace_object_allocations(void *data)
     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)
     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, VALUE obj)
     }
 }
 
+/*
+ * 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, VALUE obj)
     }
 }
 
+/*
+ * 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, VALUE obj)
     }
 }
 
+/*
+ * 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, VALUE obj)
     }
 }
 
+/*
+ * 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)
 {