Improve documentation of derived modes and their parents

* doc/lispref/modes.texi (Derived Modes): Expand documentation of
functions that manipulate parent modes of a derived mode.
Document 'provided-mode-derived-p'.  Improve indexing.

* lisp/subr.el (derived-mode-all-parents)
(derived-mode-add-parents, provided-mode-derived-p)
(derived-mode-p): Doc fixes.

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 8c5fd63918aea477b671fb6fe0864b4789f9d3a3..1d961249633d6d87984ee4178ad52c804353c66b 100644 (file)
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -809,6 +809,7 @@ modes, rather than those of the current buffer.
 @node Derived Modes
 @subsection Defining Derived Modes
 @cindex derived mode
+@cindex parent mode
 
   The recommended way to define a new major mode is to derive it from an
 existing one using @code{define-derived-mode}.  If there is no closely
@@ -866,6 +867,9 @@ also a special mode (@pxref{Major Mode Conventions}).
 You can also specify @code{nil} for @var{parent}.  This gives the new
 mode no parent.  Then @code{define-derived-mode} behaves as described
 above, but, of course, omits all actions connected with @var{parent}.
+Conversely, you can use @code{derived-mode-set-parent} and
+@code{derived-mode-add-parents}, described below, to explicitly set
+the ancestry of the new mode.
 
 The argument @var{docstring} specifies the documentation string for the
 new mode.  @code{define-derived-mode} adds some general information
@@ -932,6 +936,7 @@ Do not write an @code{interactive} spec in the definition;
 @code{define-derived-mode} does that automatically.
 @end defmac
 
+@cindex ancestry, of major modes
 @defun derived-mode-p modes
 This function returns non-@code{nil} if the current major mode is
 derived from any of the major modes given by the list of symbols
@@ -940,10 +945,28 @@ Instead of a list, @var{modes} can also be a single mode symbol.
 
 Furthermore, we still support a deprecated calling convention where the
 @var{modes} were passed as separate arguments.
+
+When examining the parent modes of the current major mode, this
+function takes into consideration the current mode's parents set by
+@code{define-derived-mode}, and also its additional parents set by
+@code{derived-mode-add-parents}, described below.
+@end defun
+
+@defun provided-mode-derived-p mode modes
+This function returns non-@code{nil} if @var{mode} is derived from any
+of the major modes given by the list of symbols in @var{modes}.  Like
+with @code{derived-mode-p}, @var{modes} can also be a single symbol,
+and this function also supports a deprecated calling convention where
+the @var{modes} were passed as separate symbol arguments.
+
+When examining the parent modes of @var{mode}, this function takes
+into consideration the parents of @var{mode} set by
+@code{define-derived-mode}, and also its additional parents set by
+@code{derived-mode-add-parents}, described below.
 @end defun
 
-The graph of major modes is accessed with the following lower-level
-functions:
+The graph of a major mode's ancestry can be accessed and modified with
+the following lower-level functions:
 
 @defun derived-mode-set-parent mode parent
 This function declares that @var{mode} inherits from @code{parent}.
@@ -956,14 +979,19 @@ by reusing @code{parent}.
 This function makes it possible to register additional parents beside
 the one that was used when defining @var{mode}.  This can be used when
 the similarity between @var{mode} and the modes in @var{extra-parents}
-is such that it makes sense to treat it as a child of those
-modes for purposes like applying directory-local variables.
+is such that it makes sense to treat @var{mode} as a child of those
+modes for purposes like applying directory-local variables and other
+mode-specific settings.  The additional parent modes are specified as
+a list of symbols in @var{extra-parents}.  Those additional parent
+modes will be considered as one of the @var{mode}s parents by
+@code{derived-mode-p} and @code{provided-mode-derived-p}.
 @end defun
 
 @defun derived-mode-all-parents mode
 This function returns the list of all the modes in the ancestry of
 @var{mode}, ordered from the most specific to the least specific, and
-starting with @var{mode} itself.
+starting with @var{mode} itself.  This includes the additional parent
+modes, if any, added by calling @code{derived-mode-add-parents}.
 @end defun
 
 

diff --git a/lisp/subr.el b/lisp/subr.el
index 0519e56e0571827a88944114a5b827f09269270f..df28989b39976373432e1c9de1bf507a64722092 100644 (file)
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2737,6 +2737,8 @@ By default we choose the head of the first list."
 
 (defun derived-mode-all-parents (mode &optional known-children)
   "Return all the parents of MODE, starting with MODE.
+This includes the parents set by `define-derived-mode' and additional
+ones set by `derived-mode-add-parents'.
 The returned list is not fresh, don't modify it.
 \n(fn MODE)"               ;`known-children' is for internal use only.
   ;; Can't use `with-memoization' :-(
@@ -2785,7 +2787,9 @@ The returned list is not fresh, don't modify it.
 (defun provided-mode-derived-p (mode &optional modes &rest old-modes)
   "Non-nil if MODE is derived from a mode that is a member of the list MODES.
 MODES can also be a single mode instead of a list.
-If you just want to check `major-mode', use `derived-mode-p'.
+This examines the parent modes set by `define-derived-mode' and also
+additional ones set by `derived-mode-add-parents'.
+If you just want to check the current `major-mode', use `derived-mode-p'.
 We also still support the deprecated calling convention:
 \(provided-mode-derived-p MODE &rest MODES)."
   (declare (side-effect-free t)
@@ -2799,8 +2803,10 @@ We also still support the deprecated calling convention:
     (car modes)))
 
 (defun derived-mode-p (&optional modes &rest old-modes)
- "Non-nil if the current major mode is derived from one of MODES.
+ "Return non-nil if the current major mode is derived from one of MODES.
 MODES should be a list of symbols or a single mode symbol instead of a list.
+This examines the parent modes set by `define-derived-mode' and also
+additional ones set by `derived-mode-add-parents'.
 We also still support the deprecated calling convention:
 \(derived-mode-p &rest MODES)."
  (declare (side-effect-free t)
@@ -2820,7 +2826,8 @@ We also still support the deprecated calling convention:
 (defun derived-mode-add-parents (mode extra-parents)
   "Add EXTRA-PARENTS to the parents of MODE.
 Declares the parents of MODE to be its main parent (as defined
-in `define-derived-mode') plus EXTRA-PARENTS."
+in `define-derived-mode') plus EXTRA-PARENTS, which should be a list
+of symbols."
   (put mode 'derived-mode-extra-parents extra-parents)
   (derived-mode--flush mode))