Improve the general description.

2 files changed, 28 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 7281cac..c117e70 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2009-11-02  Donal K. Fellows  <dkf@users.sf.net>
+
+	* doc/object.n (DESCRIPTION): Substantive revision to make it clearer
+	what the fundamental semantics of an object actually are.
+
 2009-11-01  Joe Mistachkin  <joe@mistachkin.com>
 
 	* doc/Cancel.3: Minor cosmetic fixes.
@@ -8,17 +13,17 @@
 	invocation.  This led to confusion because it was the only such tool
 	path to include double quotes around its invocation.  Also, it was
 	somewhat inflexible in the event that somebody needed to override the
-	tool command to include arguments.  Therefore, even though it may
-	look "wrong", there are now two double quotes on either side of the
-	tool path definition.  This fixes the problem that currently prevents
-	the htmlhelp target from building and maintains flexibility in case
+	tool command to include arguments.  Therefore, even though it may look
+	"wrong", there are now two double quotes on either side of the tool
+	path definition.  This fixes the problem that currently prevents the
+	htmlhelp target from building and maintains flexibility in case
 	somebody needs to override it via the command line or an environment
 	variable.
 
 2009-11-01  Joe English  <jenglish@users.sourceforge.net>
 
-	* doc/Eval.3, doc/Cancel.3: Move TIP#285 routines out of 
-	Tcl_Eval(3) into their own manpage.
+	* doc/Eval.3, doc/Cancel.3: Move TIP#285 routines out of Eval.3 into
+	their own manpage.
 
 2009-10-31  Donal K. Fellows  <dkf@users.sf.net>
 
diff --git a/doc/object.n b/doc/object.n
index 0836728..68d642b 100644
--- a/doc/object.n
+++ b/doc/object.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
-'\" RCS: @(#) $Id: object.n,v 1.4 2008/10/17 10:22:25 dkf Exp $
+'\" RCS: @(#) $Id: object.n,v 1.5 2009/11/02 09:54:45 dkf Exp $
 '\"
 .so man.macros
 .TH object n 0.1 TclOO "TclOO Commands"
@@ -26,12 +26,24 @@ package require TclOO
 .SH DESCRIPTION
 .PP
 The \fBoo::object\fR class is the root class of the object hierarchy; every
-object (and hence every class) is an instance of this class. Objects are
-always referred to by their name, and may be \fBrename\fRd while maintaining
-their identity. Each object has a unique namespace associated with it.
+object is an instance of this class. Since classes are themselves objects,
+they are instances of this class too. Objects are always referred to by their
+name, and may be \fBrename\fRd while maintaining their identity.
+.PP
 Instances of objects may be made with either the \fBcreate\fR or \fBnew\fR
 methods of the \fBoo::object\fR object itself, or by invoking those methods on
-any of the subclass objects; see \fBoo::class\fR for more details.
+any of the subclass objects; see \fBoo::class\fR for more details. The
+configuration of individual objects (i.e., instance-specific methods, mixed-in
+classes, etc.) may be controlled with the \fBoo::objdefine\fR command.
+.PP
+Each object has a unique namespace associated with it, the instance namespace.
+This namespace holds all the instance variables of the object, and will be the
+current namespace whenever a method of the object is invoked (including a
+method of the class of the object). When the object is destroyed, its instance
+namespace is deleted. The instance namespace contains the object's \fBmy\fR
+command, which may be used to invoke non-exported methods of the object or to
+create a reference to the object for the purpose of invokation which persists
+across renamings of the object.
 .SS CONSTRUCTOR
 The \fBoo::object\fR class does not define an explicit constructor.
 .SS DESTRUCTOR