* object.c: Add usage documentation for BasicObject. Based on patch

	  by Thomas Sawyer.  [Ruby 1.9 - Bug ruby#5067]


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

ChangeLog

@@ -1,3 +1,8 @@
+Wed Jul 27 15:39:14 2011  Eric Hodel  <[email protected]>
+
+	* 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  <[email protected]>
 
 	* lib/rubygems/uninstaller.rb:  Add missing require and update

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