[Emacs-diffs] master 8bab07b: * doc/misc/eieio.texi: Don't advertize now obsolete constructs

[Stefan Monnier]

branch: master
commit 8bab07bc03c7f51b64daecef0168eb11c2f5c1eb
Author: Stefan Monnier <address@hidden>
Commit: Stefan Monnier <address@hidden>

    * doc/misc/eieio.texi: Don't advertize now obsolete constructs
---
 doc/misc/eieio.texi |  107 +++++++++++++++-----------------------------------
 etc/NEWS            |    6 +++
 2 files changed, 38 insertions(+), 75 deletions(-)

diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index fe0b326..5d1a8cf 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -140,13 +140,13 @@ constructor.  The constructor is a function with the same 
name as your
 class which returns a new instance of that class.  Here is an example:
 
 @example
-(setq rec (record "Eric" :name "Eric" :birthday "June" :phone "555-5555"))
+(setq rec (record :name "Eric" :birthday "June" :phone "555-5555"))
 @end example
 
 @noindent
-The first argument is the name given to this instance.  Each instance
-is given a name, so different instances can be easily distinguished
-when debugging.
+For backward compatibility reasons, the first argument can be a string (a name
+given to this instance).  Each instance used to be given a name, so different
+instances could be easily distinguished when debugging.
 
 It can be a bit repetitive to also have a :name slot.  To avoid doing
 this, it is sometimes handy to use the base class @code{eieio-named}.
@@ -244,7 +244,7 @@ EIEIO does not support it.
 This CLOS method tag is non-functional.
 
 @item :default-initargs in @code{defclass}
-Each slot has an @code{:initarg} tag, so this is not really necessary.
+Each slot can have an @code{:initform} tag, so this is not really necessary.
 
 @item Mock object initializers
 Each class contains a mock object used for fast initialization of
@@ -266,10 +266,9 @@ To create a new class, use the @code{defclass} macro:
 @defmac defclass class-name superclass-list slot-list &rest options-and-doc
 
 Create a new class named @var{class-name}.  The class is represented
-by a self-referential symbol with the name @var{class-name}.  @eieio{}
-stores the structure of the class as a symbol property of
address@hidden (@pxref{Symbol Components,,,elisp,GNU Emacs Lisp
-Reference Manual}).
+by a symbol with the name @var{class-name}.  @eieio{} stores the structure of
+the class as a symbol property of @var{class-name} (@pxref{Symbol
+Components,,,elisp,GNU Emacs Lisp Reference Manual}).
 
 The @var{class-name} symbol's variable documentation string is a
 modified version of the doc string found in @var{options-and-doc}.
@@ -292,17 +291,12 @@ or @code{:protection}.
 @end defmac
 
 @noindent
-Whenever defclass is used to create a new class, two predicates are
-created for it, named @address@hidden and
address@hidden@var{CLASS-NAME}-child-p}:
+Whenever defclass is used to create a new class, a predicate is
+created for it, named @address@hidden:
 
 @defun CLASS-NAME-p object
-Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME}.
address@hidden defun
-
address@hidden CLASS-NAME-child-p object
-Return @code{t} if @var{OBJECT} is of the class @var{CLASS-NAME},
-or is of a subclass of @var{CLASS-NAME}.
+Return address@hidden if and only if @var{OBJECT} is of the class
address@hidden
 @end defun
 
 @defvar eieio-error-unsupported-class-tags
@@ -418,7 +412,7 @@ Valid tags are:
 @table @code
 @item :initarg
 A symbol that can be used in the argument list of the constructor to
-specify a value for the new instance being created.
+specify a value for this slot of the new instance being created.
 
 A good symbol to use for initarg is one that starts with a colon @code{:}.
 
@@ -428,13 +422,13 @@ The slot specified like this:
 @end example
 could then be initialized to the number 1 like this:
 @example
-  (myobject "name" :myslot 1)
+  (myobject :myslot 1)
 @end example
 
 @xref{Making New Objects}.
 
 @item :initform
-A expression used as the default value for this slot.
+An expression used as the default value for this slot.
 
 If @code{:initform} is left out, that slot defaults to being unbound.
 It is an error to reference an unbound slot, so if you need
@@ -445,19 +439,13 @@ Use @code{slot-boundp} to test if a slot is unbound
 (@pxref{Predicates}).  Use @code{slot-makeunbound} to set a slot to
 being unbound after giving it a value (@pxref{Accessing Slots}).
 
-The value passed to initform is automatically quoted.  Thus,
+The value passed to initform used to be automatically quoted.  Thus,
 @example
 :initform (1 2 3)
 @end example
-appears as the specified list in the default object.
-A symbol that is a function like this:
address@hidden
-:initform +
address@hidden example
-will set the initial value as that symbol.
-
-After a class has been created with @code{defclass}, you can change
-that default value with @code{oset-default}.  @ref{Accessing Slots}.
+will use the list as a value.  This is incompatible with CLOS (which would
+signal an error since 1 is not a valid function) and will likely change in the
+future, so better quote your initforms if they're just values.
 
 @item :type
 An unquoted type specifier used to validate data set into this slot.
@@ -669,7 +657,7 @@ can do any valid Lispy thing you want with it, such as
 Example of creating an object from a class:
 
 @example
-(record "test" :value 3 :reference nil)
+(record :value 3 :reference nil)
 @end example
 
 @end defun
@@ -692,15 +680,6 @@ for each slot.  For example:
   (make-instance @code{'foo} @code{:slot1} value1 @code{:slotN} valueN)
 @end example
 
-Compatibility note:
-
-If the first element of @var{initargs} is a string, it is used as the
-name of the class.
-
-In @eieio{}, the class' constructor requires a name for use when printing.
address@hidden in CLOS doesn't use names the way Emacs does, so the
-class is used as the name slot instead when @var{initargs} doesn't start with
-a string.
 @end defun
 
 @node Accessing Slots
@@ -717,14 +696,9 @@ This macro sets the value behind @var{slot} to @var{value} 
in
 @end defmac
 
 @defmac oset-default class slot value
-This macro sets the @code{:initform} for @var{slot} in @var{class} to
+This macro sets the value for the class-allocated @var{slot} in @var{class} to
 @var{value}.
 
-This allows the user to set both public and private defaults after the
-class has been constructed, and provides a way to configure the
-default behavior of packages built with classes (the same way
address@hidden does for buffer-local variables).
-
 For example, if a user wanted all @code{data-objects} (@pxref{Building
 Classes}) to inform a special object of his own devising when they
 changed, this can be arranged by simply executing this bit of code:
@@ -737,16 +711,12 @@ changed, this can be arranged by simply executing this 
bit of code:
 @defmac oref obj slot
 @anchor{oref}
 Retrieve the value stored in @var{obj} in the slot named by @var{slot}.
-Slot is the name of the slot when created by @dfn{defclass} or the label
-created by the @code{:initarg} tag.
+Slot is the name of the slot when created by @dfn{defclass}.
 @end defmac
 
address@hidden oref-default obj slot
address@hidden oref-default class slot
 @anchor{oref-default}
-Gets the default value of @var{obj} (maybe a class) for @var{slot}.
-The default value is the value installed in a class with the @code{:initform}
-tag.  @var{slot} can be the slot name, or the tag specified by the 
@code{:initarg}
-tag in the @dfn{defclass} call.
+Get the value of the class-allocated @var{slot} from @var{class}.
 @end defmac
 
 The following accessors are defined by CLOS to reference or modify
@@ -812,7 +782,7 @@ Where each @var{var} is the local variable given to the 
associated
 variable name of the same name as the slot.
 
 @example
-(defclass myclass () (x :initarg 1))
+(defclass myclass () (x :initform 1))
 (setq mc (make-instance 'myclass))
 (with-slots (x) mc x)                      => 1
 (with-slots ((something x)) mc something)  => 1
@@ -986,15 +956,14 @@ allows the first argument to be cast.
 @section Static Methods
 
 Static methods do not depend on an object instance, but instead
-operate on an object's class.  You can create a static method by using
+operate on a class.  You can create a static method by using
 the @code{:static} key with @code{defmethod}.
 
-Do not treat the first argument of a @code{:static} method as an
-object unless you test it first.  Use the functions
address@hidden or @code{oset-default} which will work on a class,
-or on the class of an object.
+The first argument of a @code{:static} method will be a class rather than an
+object.  Use the functions @code{oref-default} or @code{oset-default} which
+will work on a class.
 
-A Class' @code{constructor} method is defined as a @code{:static}
+A class's @code{make-instance} method is defined as a @code{:static}
 method.
 
 @b{Note:} The @code{:static} keyword is unique to @eieio{}.
@@ -1085,13 +1054,6 @@ For example:
 Will fetch the documentation string for @code{eieio-default-superclass}.
 @end defun
 
address@hidden class-constructor class
-Return a symbol used as a constructor for @var{class}.  The
-constructor is a function used to create new instances of
address@hidden  This function provides a way to make an object of a class
-without knowing what it is.  This is not a part of CLOS.
address@hidden defun
-
 @defun eieio-object-name obj
 Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
 This should look like Lisp symbols from other parts of Emacs such as
@@ -1105,11 +1067,6 @@ information into the symbol.
 Returns the class symbol from @var{obj}.
 @end defun
 
address@hidden eieio--object-class obj
-Same as @code{eieio-object-class} except this is a macro, and no
-type-checking is performed.
address@hidden defun
-
 @defun eieio-object-class-name obj
 Returns the symbol of @var{obj}'s class.
 @end defun
@@ -1267,7 +1224,7 @@ Return the list of public slots for @var{obj}.
 @end defun
 
 @defun class-slot-initarg class slot
-For the given @var{class} return the :initarg associated with
+For the given @var{class} return an :initarg associated with
 @var{slot}.  Not all slots have initargs, so the return value can be
 @code{nil}.
 @end defun
@@ -1612,7 +1569,7 @@ is a list of name/value pairs.  These are actually just 
passed to
 Sets slots of @var{obj} with @var{slots} which is a list of name/value
 pairs.
 
-This is called from the default @code{constructor}.
+This is called from the default constructor.
 @end defun
 
 @node Basic Methods
diff --git a/etc/NEWS b/etc/NEWS
index 13cd512..caf6250 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -271,13 +271,19 @@ the old behavior -- *shell* buffer displays in current 
window -- use
 
 
 ** EIEIO
++++
 *** The `:protection' slot option is not obeyed any more.
++++
 *** The `newname' argument to constructors is optional&deprecated.
 If you need your objects to be named, do it by inheriting from `eieio-named'.
++++
 *** The <class>-list-p and <class>-child-p functions are declared obsolete.
++++
 *** The <class> variables are declared obsolete.
++++
 *** The <initarg> variables are declared obsolete.
 *** defgeneric and defmethod are declared obsolete.
++++
 *** `constructor' is now an obsolete alias for `make-instance'.
 
 ** ido