cl-types: The big renaming to "derived types"

`cl-defstruct` also defines a type and is also in CL, so
"cl-type" is not precise enough to talk about those types
defined with `cl-deftype`.  Use the term "derived type" to be
more clear, as is done in the HyperSpec.

* doc/misc/cl.texi (Derived types): Move `cl-deftype` to this
new subsection.  Document the use of derived types as method specializers.

* lisp/emacs-lisp/cl-extra.el (cl--types-of-memo): Rename from
`cl--type-unique`.
(cl--derived-type-dispatch-list): Rename from `cl--type-dispatch-list`.
(cl--derived-type-generalizer): Rename from `cl--type-generalizer`.
(cl--derived-type-generalizers): Rename from `cl--type-generalizers`.

* lisp/emacs-lisp/cl-lib.el (cl-generic-generalizers) <derived-types>:
Rename from <cl-types-of>.  Catch but don't hide errors when a derived
type cannot be used as an atomic type specifier.

* lisp/emacs-lisp/cl-preloaded.el (cl--derived-type-list): Rename from
`cl--type-list`.
(cl-derived-type-class): Rename from `cl-type-class`.
(cl--derived-type-class-make): Rename from `cl--type-class-make`.
(cl--define-derived-type): Rename from `cl--type-deftype`.

1 files changed, 26 insertions, 2 deletions

diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi
index 4bceddb8196..a1246b11a8a 100644
--- a/doc/misc/cl.texi
+++ b/doc/misc/cl.texi
@@ -888,8 +888,12 @@ floats.  In all other circumstances, @code{cl-coerce} signals an
 error.
 @end defun
 
-@defmac cl-deftype name arglist forms@dots{}
-This macro defines a new type called @var{name}.  It is similar
+@node Derived types
+@subsection Derived types
+
+@defmac cl-deftype name arglist [docstring] [decls] forms@dots{}
+This macro defines a new type called @var{name}.
+Types defined this way are called @dfn{derived types}.  It is similar
 to @code{defmacro} in many ways; when @var{name} is encountered
 as a type name, the body @var{forms} are evaluated and should
 return a type specifier that is equivalent to the type.  The
@@ -923,6 +927,26 @@ The @code{cl-typecase} (@pxref{Conditionals}) and @code{cl-check-type}
 @code{cl-concatenate}, and @code{cl-merge} functions take type-name
 arguments to specify the type of sequence to return.  @xref{Sequences}.
 
+Contrary to Common Lisp, CL-Lib supports the use of derived types
+as method specializers.  This comes with a significant caveat: derived
+types are much too flexible for Emacs to be able to automatically find
+out which type is a subtype of another, so the ordering of
+methods is not well-defined when several methods are applicable for
+a given argument value and the specializer of one or more of those
+methods is a derived type.  To make the order more well-defined, a derived type
+definition can explicitly state that it is a subtype of others using the
+@var{decls} argument:
+
+@example
+(cl-deftype unsigned-byte (&optional bits)
+  (list 'integer 0 (if (eq bits '*) bits (1- (ash 1 bits)))))
+
+(cl-deftype unsigned-8bits ()
+  "Unsigned 8-bits integer."
+  (declare (parents unsigned-byte))
+  '(unsigned-byte 8))
+@end example
+
 @node Equality Predicates
 @section Equality Predicates