From 3eb7d2b33e3f8555d81db5369eb6fb7100a91e63 Mon Sep 17 00:00:00 2001
From: drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Wed, 27 Jul 2011 06:44:39 +0000
Subject: [PATCH] 	* object.c:  Add usage documentation for BasicObject. 
 Based on patch 	  by Thomas Sawyer.  [Ruby 1.9 - Bug #5067]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32700 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ChangeLog |  5 +++++
 object.c  | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 7b65d7eb6a..31661c9beb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+Wed Jul 27 15:39:14 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* object.c:  Add usage documentation for BasicObject.  Based on patch
+	  by Thomas Sawyer.  [Ruby 1.9 - Bug #5067]
+
 Wed Jul 27 12:24:17 2011  Eric Hodel  <drbrain@segment7.net>
 
 	* lib/rubygems/uninstaller.rb:  Add missing require and update
diff --git a/object.c b/object.c
index f51bb15df5..5d21709a5d 100644
--- a/object.c
+++ b/object.c
@@ -2614,6 +2614,53 @@ rb_f_array(VALUE obj, VALUE arg)
  *
  *  BasicObject is the parent class of all classes in Ruby.  It's an explicit
  *  blank class.
+ *
+ *  BasicObject can be used for creating object hierarchies independent of
+ *  Ruby's object hierarchy, proxy objects like the Delegator class, or other
+ *  uses where namespace pollution from Ruby's methods and classes must be
+ *  avoided.
+ *
+ *  To avoid polluting BasicObject for other users an appropriately named
+ *  subclass of BasicObject should be created instead of directly modifying
+ *  BasicObject:
+ *
+ *    class MyObjectSystem < BasicObject
+ *    end
+ *
+ *  BasicObject does not include Kernel (for methods like +puts+) and
+ *  BasicObject is outside of the namespace of the standard library so common
+ *  classes will not be found without a using a full class path.
+ *
+ *  A variety of strategies can be used to provide useful portions of the
+ *  standard library to subclasses of BasicObject.  A subclass could
+ *  <code>include Kernel</code> to obtain +puts+, +exit+, etc.  A custom
+ *  Kernel-like module could be created and included or delegation can be used
+ *  via #method_missing:
+ *
+ *    class MyObjectSystem < BasicObject
+ *      DELEGATE = [:puts, :p]
+ *
+ *      def method_missing(name, *args, &block)
+ *        super unless DELEGATE.include? name
+ *        ::Kernel.send(name, *args, &block)
+ *      end
+ *
+ *      def respond_to_missing?(name, include_private = false)
+ *        DELGATE.include?(name) or super
+ *      end
+ *    end
+ *
+ *  Access to classes and modules from the Ruby standard library can be
+ *  obtained in a BasicObject subclass by referencing the desired constant
+ *  from the root like <code>::File</code> or <code>::Enumerator</code>.
+ *  Like #method_missing, #const_missing can be used to delegate constant
+ *  lookup to +Object+:
+ *
+ *    class MyObjectSystem < BasicObject
+ *      def self.const_missing(name)
+ *        ::Object.const_get(name)
+ *      end
+ *    end
  */
 
 /*  Document-class: Object