Merge 8.7

1 files changed, 34 insertions, 5 deletions

diff --git a/doc/define.n b/doc/define.n
index 91d927c..775cdc4 100644
--- a/doc/define.n
+++ b/doc/define.n
@@ -9,7 +9,7 @@
 .BS
 '\" Note:  do not modify the .SH NAME line immediately below!
 .SH NAME
-oo::define, oo::objdefine \- define and configure classes and objects
+oo::define, oo::objdefine, oo::Slot \- define and configure classes and objects
 .SH SYNOPSIS
 .nf
 package require tcl::oo
@@ -18,6 +18,13 @@ package require tcl::oo
 \fBoo::define\fI class subcommand arg\fR ?\fIarg ...\fR?
 \fBoo::objdefine\fI object defScript\fR
 \fBoo::objdefine\fI object subcommand arg\fR ?\fIarg ...\fR?
+
+\fBoo::Slot\fR \fIarg...\fR
+.fi
+.SH "CLASS HIERARCHY"
+.nf
+\fBoo::object\fR
+   \(-> \fBoo::Slot\fR
 .fi
 .BE
 .SH DESCRIPTION
@@ -514,8 +521,10 @@ Some of the configurable definitions of a class or object are \fIslotted
 definitions\fR. This means that the configuration is implemented by a slot
 object, that is an instance of the class \fBoo::Slot\fR, which manages a list
 of values (class names, variable names, etc.) that comprises the contents of
-the slot. The class defines six operations (as methods) that may be done on
-the slot:
+the slot.
+.PP
+The \fBoo::Slot\fR class defines six operations (as methods) that may be done
+on the slot:
 .\" METHOD: -append
 .TP
 \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
@@ -554,6 +563,10 @@ This replaces the slot definition with the given \fImember\fR elements.
 A consequence of this is that any use of a slot's default operation where the
 first member argument begins with a hyphen will be an error. One of the above
 operations should be used explicitly in those circumstances.
+.PP
+You only need to make an instance of \fBoo::Slot\fR if you are definining your
+own slot that behaves like a standard slot.
+.PP
 .SS "SLOT IMPLEMENTATION"
 .\" METHOD: --default-operation
 Internally, slot objects also define a method \fB\-\-default\-operation\fR
@@ -597,6 +610,16 @@ Implementations \fIshould not\fR enforce uniqueness and ordering constraints
 in this method; that is the responsibility of the \fBSet\fR method.
 .RE
 .VE TIP516
+.\" METHOD: Resolve
+.TP
+\fIslot\fR \fBResolve \fIelement\fR
+.VS
+This converts an element of the slotted collection into its resolved form; for
+a simple value, it could just return the value, but for a slot that contains
+references to commands or classes it should convert those into their
+fully-qualified forms (so they can be compared with \fBstring equals\fR): that
+could be done by forwarding to \fBnamespace which\fR or similar.
+.VE
 .\" METHOD: Set
 .TP
 \fIslot\fR \fBSet \fIelementList\fR
@@ -619,8 +642,14 @@ The implementation of these methods is slot-dependent (and responsible for
 accessing the correct part of the class or object definition). Slots also have
 an unknown method handler to tie all these pieces together, and they hide
 their \fBdestroy\fR method so that it is not invoked inadvertently. It is
-\fIrecommended\fR that any user changes to the slot mechanism be restricted to
-defining new operations whose names start with a hyphen.
+\fIrecommended\fR that any user changes to the slot mechanism itself be
+restricted to defining new operations whose names start with a hyphen.
+.PP
+Note that slot instances are not expected to contain the storage for the slot
+they manage; that will be in or attached to the class or object that they
+manage. Those instances should provide their own implementations of the
+\fBGet\fR and \fBSet\fR methods (and optionally \fBResolve\fR; that defaults
+to a do-nothing pass-through).
 .PP
 .VS TIP516
 Most slot operations will initially \fBResolve\fR their argument list, combine