ruby · trans · Jul 7, 2011 · Jul 7, 2011 · Jul 22, 2011 · Jul 22, 2011
diff --git a/object.c b/object.c
@@ -2560,6 +2560,41 @@ rb_f_array(VALUE obj, VALUE arg)
  *
  *  BasicObject is the parent class of all classes in Ruby.  It's an explicit
  *  blank class.
+ *
+ *  BasicObject is useful for creating object heirarchies independent of
+ *  Ruby's standard <code>Kernel<-Object</code> heirarchy. Consequently
+ *  BasicObject defines only the most essential methods necessary to be
+ *  functional --it does not provide even the most common Kernel methods
+ *  such as <code>#p</code> or <code>#puts</code>. Also, BasicObject does
+ *  not resolve constants beyond itself. This means even core classes and
+ *  modules, such as +Regexp+ and +Enumerable+, cannot be accessed simply
+ *  by name.
+ *
+ *  To work around these features/limitations, a variety of strategies
+ *  can be used. For example, +Kernel+ can be included into a subclass
+ *  of BasicObject and the sublcass would bahave almost entirely as if
+ *  is had subclassed +Object+. To more surgically select methods
+ *  delegation can be used, for example <code>#method_missing</code>:
+ *
+ *    class Foo < BasicObject
+ *      METHODS = [:puts, :p]
+ *      def method_missing(sym, *args, &blk)
+ *        super(sym *args, &blk) unless METHODS.include?(sym)
+ *        ::Kernel.send(sym, *args, &blk)
+ *      end
+ *     end
+ *
+ *  The simplists work around for constant lookup is to use the toplevel
+ *  prefix (<code>::</code>). In more complex cases, this may not be enough,
+ *  for example if code is evaluated dynamically within the scope of the
+ *  BasicObject subclass. To handle these cases use +const_missing+ and
+ *  delegate constant lookup to +Object+.
+ * 
+ *      class Foo < BasicObject
+ *        def self.const_missing(name)
+ *          ::Object.const_get(name)
+ *        end
+ *      end
  */
 
 /*  Document-class: Object