* gc.c: [DOC] Improve documentation for ObjectSpace.count_objects

  with regards to `:TOTAL` key, with patch by @schneems [Fixes GH-871]
  https://github.com/ruby/ruby/pull/871 [Bug #11067] [ci skip]

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

2 files changed, 14 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index 47cc178299..3674a97c46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Tue Apr 14 08:59:04 2015  Zachary Scott  <e@zzak.io>
+
+        * gc.c: [DOC] Improve documentation for ObjectSpace.count_objects
+          with regards to `:TOTAL` key, with patch by @schneems [Fixes GH-871]
+          https://github.com/ruby/ruby/pull/871 [Bug #11067]
+
 Mon Apr 13 22:44:07 2015  Tanaka Akira  <akr@fsij.org>
 
 	* test/lib/envutil.rb (File.mkfifo): Defined using mkfifo command.
diff --git a/gc.c b/gc.c
index f311501646..874ff76e6f 100644
--- a/gc.c
+++ b/gc.c
@@ -3056,7 +3056,7 @@ set_zero(st_data_t key, st_data_t val, st_data_t arg)
  *  call-seq:
  *     ObjectSpace.count_objects([result_hash]) -> hash
  *
- *  Counts objects for each type.
+ *  Counts all objects grouped by type.
  *
  *  It returns a hash, such as:
  *	{
@@ -3068,11 +3068,17 @@ set_zero(st_data_t key, st_data_t val, st_data_t arg)
  *	}
  *
  *  The contents of the returned hash are implementation specific.
- *  It may be changed in future.
+ *  It may be changed in future. The +:TOTAL+ key contains the count
+ *  of all currently allocated and previously freed objects.
  *
  *  If the optional argument +result_hash+ is given,
  *  it is overwritten and returned. This is intended to avoid probe effect.
  *
+ *    h = {}
+ *    ObjectSpace.count_objects(h)
+ *    puts h
+ *    # => { :TOTAL=>10000, :T_CLASS=>158280, :T_MODULE=>20672, :T_STRING=>527249 }
+ *
  *  This method is only expected to work on C Ruby.
  *
  */