branch: externals/compat
commit 28494d7c792131064f1e1a16a37762cf4bd42dae
Author: Daniel Mendler <m...@daniel-mendler.de>
Commit: Daniel Mendler <m...@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))
