[WIP] docstrings

lisp/transient.el

@@ -3549,7 +3549,10 @@ was not invoked from PREFIX, then return the set, saved or default value
 for PREFIX.
 
 PREFIX may also be a list of prefixes.  If no prefix is active, the
-fallback value of the first of these prefixes is used."
+fallback value of the first of these prefixes is used.
+
+The generic function `transient-prefix-value' is used to determine the
+returned value."
   (when (listp prefix)
     (setq prefix (car (or (memq transient-current-command prefix) prefix))))
   (if-let ((obj (get prefix 'transient--prefix)))
@@ -3558,25 +3561,30 @@ fallback value of the first of these prefixes is used."
 
 (cl-defgeneric transient-prefix-value (obj)
   "Return the value of the prefix object OBJ.
-
-This function is called by `transient-args' (which see), meaning this
-function is how the value of a transient is determined so that the
-invoked suffix command can use it.")
+This function is used by `transient-args'.")
 
 (cl-defmethod transient-prefix-value ((obj transient-prefix))
-  "Return a list of the values of the suffixes the prefix object OBJ."
+  "Return a list of the values of the suffixes the prefix object OBJ.
+Use `transient-infix-value' to collect the values of individual suffix
+objects."
   (mapcan #'transient--get-wrapped-value
           (transient-suffixes (oref obj command))))
 
 (defun transient-suffixes (prefix)
-  "Return the suffix objects of the transient prefix command PREFIX."
+  "Return the suffix objects of the transient prefix command PREFIX.
+If PREFIX is not the current prefix, initialize the suffixes so that
+they can be returned.  Doing so doesn't have any side-effects."
   (if (eq transient-current-command prefix)
       transient-current-suffixes
     (let ((transient--prefix (transient--init-prefix prefix)))
       (transient--flatten-suffixes
        (transient--init-suffixes prefix)))))
 
 (defun transient-get-value ()
+  "Return the value of the current prefix.
+This is intended for internal use, as well as in `transient-set-value'
+and `transient-save-value' methods.  Unlike `transient-args', this does
+not include the values of suffixes whose `unsavable' slot is non-nil."
   (transient--with-emergency-exit :get-value
     (mapcan (lambda (obj)
               (and (or (not (slot-exists-p obj 'unsavable))
@@ -3585,6 +3593,12 @@ invoked suffix command can use it.")
             (or transient--suffixes transient-current-suffixes))))
 
 (defun transient--get-wrapped-value (obj)
+  "Return a list of the value(s) of suffix object OBJ.
+Internally a suffix only ever has one value, stored in its `value' slot,
+but callers of `transient-args', wish to treat the values of certain
+suffixes as multiple values.  That translation is handled here.  The
+object's `multi-value' slot specifies, whether and how to interpret
+the `value' as multiple values."
   (and-let* ((value (transient-infix-value obj)))
     (pcase-exhaustive (and (slot-exists-p obj 'multi-value)
                            (oref obj multi-value))
@@ -3664,17 +3678,17 @@ Append \"=\ to ARG to indicate that it is an option."
 ;;;; Init
 
 (cl-defgeneric transient-init-scope (obj)
-  "Set the scope of the suffix object OBJ.
+  "Set the scope of the prefix or suffix object OBJ.
 
 The scope is actually a property of the transient prefix, not of
 individual suffixes.  However it is possible to invoke a suffix
 command directly instead of from a transient.  In that case, if
 the suffix expects a scope, then it has to determine that itself
 and store it in its `scope' slot.
 
-This function is called for all suffix commands, but unless a
-concrete method is implemented this falls through to the default
-implementation, which is a noop.")
+This function is called for all prefix and suffix commands, but
+unless a concrete method is implemented, this falls through to
+a default implementation, which is a noop.")
 
 (cl-defmethod transient-init-scope ((_   transient-prefix))
   "Noop." nil)
@@ -3685,17 +3699,19 @@ implementation, which is a noop.")
 ;;;; Get
 
 (defun transient-scope (&optional prefix)
-  "Return the value of the `scope' slot of the current prefix.
+  "Return the scope of the transient prefix command PREFIX, or nil.
 
-If the current command wasn't invoked from a prefix, return nil.
+If the current command wasn't invoked from any prefix, return nil.
 
 If PREFIX is non-nil, it must a single prefix or a list of prefixes.
-If the current prefix is one of these prefixes, return its scope,
-otherwise return nil.
+If, and only if, the current prefix is one of these prefixes, return
+its scope, otherwise return nil.
+
+If PREFIX is nil (for backward compatibility it may also be omitted),
+return the scope of the current prefix, regardless of which prefix it
+is.  This usage is rarely appropriate; it is better to be explicit.
 
-If PREFIX is nil (for backward compatibility it may also be omitted)
-then return the scope of the current prefix, whatever that is.  This
-usage is rarely appropriate; it is better to be explicit."
+Return the value of the corresponding object's `scope' slot."
   (declare (advertised-calling-convention (prefix) "0.8.0"))
   (and transient-current-command
        (or (not prefix)