[elpa] externals/compat 28494d7c79 2/3: Explicit functions: Mention reason of existence in the docstring

[ELPA Syncer]

branch: externals/compat
commit 28494d7c792131064f1e1a16a37762cf4bd42dae
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    Explicit functions: Mention reason of existence in the docstring
    
    Replicating the docstring of the original function is not needed.
---
 compat-26.el | 35 +++++++----------------------
 compat-27.el | 11 ++++------
 compat-28.el | 20 +++++++----------
 compat-29.el | 72 ++++--------------------------------------------------------
 4 files changed, 24 insertions(+), 114 deletions(-)

diff --git a/compat-26.el b/compat-26.el
index 504d14bdc6..4578f2a583 100644
--- a/compat-26.el
+++ b/compat-26.el
@@ -28,11 +28,7 @@
 ;;;; Defined in fns.c
 
 (compat-defun assoc (key alist &optional testfn) ;; <OK>
-  "Handle the optional argument TESTFN.
-Equality is defined by the function TESTFN, defaulting to
-`equal'.  TESTFN is called with 2 arguments: a car of an alist
-element and KEY.  With no optional argument, the function behaves
-just like `assoc'."
+  "Handle the optional TESTFN."
   :explicit t
   (if testfn
       (catch 'found
@@ -48,12 +44,7 @@ SEQUENCE may be a list, a vector, a boolean vector, or a 
string."
   (apply #'nconc (mapcar func sequence)))
 
 (compat-defun line-number-at-pos (&optional position absolute) ;; <OK>
-  "Handle optional argument ABSOLUTE:
-
-If the buffer is narrowed, the return value by default counts the lines
-from the beginning of the accessible portion of the buffer.  But if the
-second optional argument ABSOLUTE is non-nil, the value counts the lines
-from the absolute start of the buffer, disregarding the narrowing."
+  "Handle optional argument ABSOLUTE."
   :explicit t
   (if absolute
       (save-restriction
@@ -64,7 +55,7 @@ from the absolute start of the buffer, disregarding the 
narrowing."
 ;;;; Defined in subr.el
 
 (compat-defun alist-get (key alist &optional default remove testfn) ;; <OK>
-  "Handle TESTFN manually."
+  "Handle optional argument TESTFN."
   :explicit t
   (if testfn
       (let (entry)
@@ -113,18 +104,14 @@ from the absolute start of the buffer, disregarding the 
narrowing."
                               ,v)))))))))))
 
 (compat-defun string-trim-left (string &optional regexp) ;; <OK>
-  "Trim STRING of leading string matching REGEXP.
-
-REGEXP defaults to \"[ \\t\\n\\r]+\"."
+  "Handle optional argument REGEXP."
   :explicit t
   (if (string-match (concat "\\`\\(?:" (or regexp "[ \t\n\r]+") "\\)") string)
       (substring string (match-end 0))
     string))
 
 (compat-defun string-trim-right (string &optional regexp) ;; <OK>
-  "Trim STRING of trailing string matching REGEXP.
-
-REGEXP defaults to  \"[ \\t\\n\\r]+\"."
+  "Handle optional argument REGEXP."
   :explicit t
   (let ((i (string-match-p
             (concat "\\(?:" (or regexp "[ \t\n\r]+") "\\)\\'")
@@ -132,9 +119,7 @@ REGEXP defaults to  \"[ \\t\\n\\r]+\"."
     (if i (substring string 0 i) string)))
 
 (compat-defun string-trim (string &optional trim-left trim-right) ;; <OK>
-  "Trim STRING of leading with and trailing matching TRIM-LEFT and TRIM-RIGHT.
-
-TRIM-LEFT and TRIM-RIGHT default to \"[ \\t\\n\\r]+\"."
+  "Handle optional arguments TRIM-LEFT and TRIM-RIGHT."
   :explicit t
   (compat--string-trim-left
    (compat--string-trim-right
@@ -348,17 +333,13 @@ The returned file name can be used directly as argument of
   (or (file-remote-p file 'localname) file))
 
 (compat-defun file-name-quoted-p (name &optional top) ;; <OK>
-  "Whether NAME is quoted with prefix \"/:\".
-If NAME is a remote file name and TOP is nil, check the local part of NAME."
+  "Handle optional argument TOP."
   :explicit t
   (let ((file-name-handler-alist (unless top file-name-handler-alist)))
     (string-prefix-p "/:" (file-local-name name))))
 
 (compat-defun file-name-quote (name &optional top) ;; <OK>
-  "Add the quotation prefix \"/:\" to file NAME.
-If NAME is a remote file name and TOP is nil, the local part of
-NAME is quoted.  If NAME is already a quoted file name, NAME is
-returned unchanged."
+  "Handle optional argument TOP."
   :explicit t
   (let ((file-name-handler-alist (unless top file-name-handler-alist)))
     (if (string-prefix-p "/:" (file-local-name name))
diff --git a/compat-27.el b/compat-27.el
index f692836551..863c93df15 100644
--- a/compat-27.el
+++ b/compat-27.el
@@ -268,10 +268,7 @@ return nil."
   :constant t)
 
 (compat-defun assoc-delete-all (key alist &optional test) ;; <OK>
-  "Delete from ALIST all elements whose car is KEY.
-Compare keys with TEST.  Defaults to `equal'.
-Return the modified alist.
-Elements of ALIST that are not conses are ignored."
+  "Handle optional argument TEST."
   :explicit t
   (unless test (setq test #'equal))
   (while (and (consp (car alist))
@@ -339,7 +336,7 @@ the number of seconds east of Greenwich."
 ;;;; Defined in files.el
 
 (compat-defun file-size-human-readable (file-size &optional flavor space unit) 
;; <OK>
-  "Handle the optional third and forth argument:
+  "Handle the optional arguments SPACE and UNIT.
 
 Optional third argument SPACE is a string put between the number and unit.
 It defaults to the empty string.  We recommend a single space or
@@ -434,7 +431,7 @@ Optional arg PARENTS, if non-nil then creates parent dirs 
as needed."
 ;;;; Defined in regexp-opt.el
 
 (compat-defun regexp-opt (strings &optional paren) ;; <OK>
-  "Handle an empty list of strings."
+  "Handle an empty list of STRINGS."
   :explicit t
   (if (null strings)
       (let ((re "\\`a\\`"))
@@ -493,7 +490,7 @@ The return value is a string (or nil in case we can’t find 
it)."
 
 (compat-defun dired-get-marked-files ;; <UNTESTED>
     (&optional localp arg filter distinguish-one-marked error)
-  "Return the marked files’ names as list of strings."
+  "Handle optional argument ERROR."
   :feature dired
   :explicit t
   (let ((result (dired-get-marked-files localp arg filter 
distinguish-one-marked)))
diff --git a/compat-28.el b/compat-28.el
index 7f0ca8602d..0f5e4649d6 100644
--- a/compat-28.el
+++ b/compat-28.el
@@ -112,8 +112,7 @@ inserted before contatenating."
 ;;;; Defined in filelock.c
 
 (compat-defun unlock-buffer () ;; <UNTESTED>
-  "Handle `file-error' conditions:
-
+  "Handle `file-error' conditions.
 Handles file system errors by calling ‘display-warning’ and
 continuing as if the error did not occur."
   :explicit t
@@ -128,8 +127,7 @@ continuing as if the error did not occur."
 ;;;; Defined in characters.c
 
 (compat-defun string-width (string &optional from to) ;; <OK>
-  "Handle optional arguments FROM and TO:
-
+  "Handle optional arguments FROM and TO.
 Optional arguments FROM and TO specify the substring of STRING to
 consider, and are interpreted as in `substring'."
   :explicit t
@@ -143,8 +141,7 @@ consider, and are interpreted as in `substring'."
 ;;;; Defined in dired.c
 
 (compat-defun directory-files (directory &optional full match nosort count) ;; 
<UNTESTED>
-  "Handle additional optional argument COUNT:
-
+  "Handle additional optional argument COUNT.
 If COUNT is non-nil and a natural number, the function will
  return COUNT number of file names (if so many are present)."
   :explicit t
@@ -157,7 +154,7 @@ If COUNT is non-nil and a natural number, the function will
 
 ;; TODO Check interaction with conditionally defined json functions
 (compat-defun json-serialize (object &rest args) ;; <UNTESTED>
-  "Handle top-level JSON values."
+  "Handle top-level JSON values (RFC 8259)."
   :explicit t
   :min-version "27"
   (if (or (listp object) (vectorp object))
@@ -166,7 +163,7 @@ If COUNT is non-nil and a natural number, the function will
 
 ;; TODO Check interaction with conditionally defined json functions
 (compat-defun json-insert (object &rest args) ;; <UNTESTED>
-  "Handle top-level JSON values."
+  "Handle top-level JSON values (RFC 8259)."
   :explicit t
   :min-version "27"
   (if (or (listp object) (vectorp object))
@@ -175,7 +172,7 @@ If COUNT is non-nil and a natural number, the function will
 
 ;; TODO Check interaction with conditionally defined json functions
 (compat-defun json-parse-string (string &rest args) ;; <UNTESTED>
-  "Handle top-level JSON values."
+  "Handle top-level JSON values (RFC 8259)."
   :explicit t
   :min-version "27"
   (if (string-match-p "\\`[[:space:]]*[[{]" string)
@@ -187,7 +184,7 @@ If COUNT is non-nil and a natural number, the function will
 
 ;; TODO Check interaction with conditionally defined json functions
 (compat-defun json-parse-buffer (&rest args) ;; <UNTESTED>
-  "Handle top-level JSON values."
+  "Handle top-level JSON values (RFC 8259)."
   :explicit t
   :min-version "27"
   (if (looking-at-p "[[:space:]]*[[{]")
@@ -708,8 +705,7 @@ is included in the return value."
 ;;;; Defined in windows.el
 
 (compat-defun count-windows (&optional minibuf all-frames) ;; <UNTESTED>
-  "Handle optional argument ALL-FRAMES:
-
+  "Handle optional argument ALL-FRAMES.
 If ALL-FRAMES is non-nil, count the windows in all frames instead
 just the selected frame."
   :explicit t
diff --git a/compat-29.el b/compat-29.el
index 15d8b8c4c2..6a2e10c425 100644
--- a/compat-29.el
+++ b/compat-29.el
@@ -107,15 +107,7 @@ Unibyte strings are converted to multibyte for comparison."
   (eq t (compare-strings string1 0 nil string2 0 nil t)))
 
 (compat-defun plist-get (plist prop &optional predicate) ;; <OK>
-  "Extract a value from a property list.
-PLIST is a property list, which is a list of the form
-\(PROP1 VALUE1 PROP2 VALUE2...).
-
-This function returns the value corresponding to the given PROP, or
-nil if PROP is not one of the properties on the list.  The comparison
-with PROP is done using PREDICATE, which defaults to `eq'.
-
-This function doesn't signal an error if PLIST is invalid."
+  "Handle optional argument PREDICATE."
   :explicit t
   (if (or (null predicate) (eq predicate 'eq))
       (plist-get plist prop)
@@ -126,16 +118,7 @@ This function doesn't signal an error if PLIST is invalid."
         (setq plist (cddr plist))))))
 
 (compat-defun plist-put (plist prop val &optional predicate) ;; <OK>
-  "Change value in PLIST of PROP to VAL.
-PLIST is a property list, which is a list of the form
-\(PROP1 VALUE1 PROP2 VALUE2 ...).
-
-The comparison with PROP is done using PREDICATE, which defaults to `eq'.
-
-If PROP is already a property on the list, its value is set to VAL,
-otherwise the new PROP VAL pair is added.  The new plist is returned;
-use `(setq x (plist-put x prop val))' to be sure to use the new value.
-The PLIST is modified by side effects."
+  "Handle optional argument PREDICATE."
   :explicit t
   (if (or (null predicate) (eq predicate 'eq))
       (plist-put plist prop val)
@@ -149,16 +132,7 @@ The PLIST is modified by side effects."
       (nconc plist (list prop val)))))
 
 (compat-defun plist-member (plist prop &optional predicate) ;; <OK>
-  "Return non-nil if PLIST has the property PROP.
-PLIST is a property list, which is a list of the form
-\(PROP1 VALUE1 PROP2 VALUE2 ...).
-
-The comparison with PROP is done using PREDICATE, which defaults to
-`eq'.
-
-Unlike `plist-get', this allows you to distinguish between a missing
-property and a property with the value nil.
-The value is actually the tail of PLIST whose car is PROP."
+  "Handle optional argument PREDICATE."
   :explicit t
   (if (or (null predicate) (eq predicate 'eq))
       (plist-member plist prop)
@@ -171,45 +145,7 @@ The value is actually the tail of PLIST whose car is PROP."
 ;;;; Defined in keymap.c
 
 (compat-defun define-key (keymap key def &optional remove) ;; <UNTESTED>
-  "In KEYMAP, define key sequence KEY as DEF.
-This is a legacy function; see `keymap-set' for the recommended
-function to use instead.
-
-KEYMAP is a keymap.
-
-KEY is a string or a vector of symbols and characters, representing a
-sequence of keystrokes and events.  Non-ASCII characters with codes
-above 127 (such as ISO Latin-1) can be represented by vectors.
-Two types of vector have special meanings:
- [remap COMMAND] remaps any key binding for COMMAND.
- [t] creates a default definition, which applies to any event with no
-    other definition in KEYMAP.
-
-DEF is anything that can be a key's definition:
- nil (means key is undefined in this keymap),
- a command (a Lisp function suitable for interactive calling),
- a string (treated as a keyboard macro),
- a keymap (to define a prefix key),
- a symbol (when the key is looked up, the symbol will stand for its
-    function definition, which should at that time be one of the above,
-    or another symbol whose function definition is used, etc.),
- a cons (STRING . DEFN), meaning that DEFN is the definition
-    (DEFN should be a valid definition in its own right) and
-    STRING is the menu item name (which is used only if the containing
-    keymap has been created with a menu name, see `make-keymap'),
- or a cons (MAP . CHAR), meaning use definition of CHAR in keymap MAP,
- or an extended menu item definition.
- (See info node `(elisp)Extended Menu Items'.)
-
-If REMOVE is non-nil, the definition will be removed.  This is almost
-the same as setting the definition to nil, but makes a difference if
-the KEYMAP has a parent, and KEY is shadowing the same binding in the
-parent.  With REMOVE, subsequent lookups will return the binding in
-the parent, and with a nil DEF, the lookups will return nil.
-
-If KEYMAP is a sparse keymap with a binding for KEY, the existing
-binding is altered.  If there is no binding for KEY, the new pair
-binding KEY to DEF is added at the front of KEYMAP."
+  "Handle optional argument REMOVE."
   :explicit t
   (if remove
       (let ((prev (lookup-key keymap key))