]> git.eshelyaron.com Git - emacs.git/commitdiff
Shorten some over-wide docstrings in functions and macros
authorStefan Kangas <stefan@marxist.se>
Sat, 19 Dec 2020 16:14:33 +0000 (17:14 +0100)
committerStefan Kangas <stefan@marxist.se>
Sat, 19 Dec 2020 17:21:06 +0000 (18:21 +0100)
* lisp/allout-widgets.el (allout-widgets-tally-string):
* lisp/array.el (array-mode):
* lisp/calc/calc-units.el (calc-spn):
* lisp/cedet/ede/generic.el (ede-generic-new-autoloader):
* lisp/cedet/semantic/analyze.el (semantic-analyze-find-tag-sequence-default)
(semantic-analyze-find-tag-sequence):
* lisp/cedet/semantic/bovine/c.el (semantic-c-evaluate-symbol-for-hideif):
* lisp/cedet/semantic/bovine/make.el (semantic-lex-make-command):
* lisp/cedet/semantic/db-typecache.el (semanticdb-typecache-include-tags):
* lisp/cedet/semantic/doc.el (semantic-documentation-for-tag):
* lisp/cedet/semantic/tag-ls.el (semantic--tag-attribute-similar-p):
* lisp/emacs-lisp/advice.el (ad-map-arglists):
* lisp/emacs-lisp/bytecomp.el (byte-constant2)
(byte-save-restriction, byte-catch-OBSOLETE, byte-unwind-protect):
* lisp/emacs-lisp/cl-generic.el (cl-generic-combine-methods):
* lisp/emacs-lisp/seq.el (seq-partition, seq-set-equal-p)
(seq-filter):
* lisp/faces.el (face-attribute-specified-or, face-equal):
* lisp/info.el (Info-prev-reference-or-link)
(Info-next-reference-or-link):
* lisp/isearch.el (with-isearch-suspended):
* lisp/kmacro.el (kmacro-step-edit-macro, kmacro-set-counter):
* lisp/org/org-agenda.el (org-agenda-filter-by-category):
* lisp/ses.el (ses-cell-symbol):
* lisp/w32-fns.el (w32-shell-dos-semantics): Shorten doc strings to
not exceed 80-column limits.  (Bug#44858)

21 files changed:
lisp/allout-widgets.el
lisp/array.el
lisp/calc/calc-units.el
lisp/cedet/ede/generic.el
lisp/cedet/semantic/analyze.el
lisp/cedet/semantic/bovine/c.el
lisp/cedet/semantic/bovine/make.el
lisp/cedet/semantic/db-typecache.el
lisp/cedet/semantic/doc.el
lisp/cedet/semantic/tag-ls.el
lisp/emacs-lisp/advice.el
lisp/emacs-lisp/bytecomp.el
lisp/emacs-lisp/cl-generic.el
lisp/emacs-lisp/seq.el
lisp/faces.el
lisp/info.el
lisp/isearch.el
lisp/kmacro.el
lisp/org/org-agenda.el
lisp/ses.el
lisp/w32-fns.el

index 7e7957762bac54c52b4c3ffa276a8fa6fcd9c7ce..21517aea01c2186d6cd9be6bdb2315d6eefd911a 100644 (file)
@@ -254,7 +254,7 @@ or deleted while this variable is nil.")
 (defvar allout-widgets-mode-inhibit)    ; defined below
 ;;;_   > allout-widgets-tally-string
 (defun allout-widgets-tally-string ()
-  "Return a string giving the number of tracked widgets, or empty string if not tracking.
+  "Return a string with number of tracked widgets, or empty string if not tracking.
 
 The string is formed for appending to the allout-mode mode-line lighter.
 
index 0ad565b5bc740e113d56f74d7d4e2cadf1871e80..de2de3ce6cbcbed51150f1fb81d7b87e53c8ab4d 100644 (file)
@@ -817,14 +817,16 @@ The variables are:
 Variables you assign:
      array-max-row:          The number of rows in the array.
      array-max-column:       The number of columns in the array.
-     array-columns-per-line: The number of columns in the array per line of buffer.
+     array-columns-per-line: The number of columns in the array
+                             per line of buffer.
      array-field-width:      The width of each field, in characters.
      array-rows-numbered:    A logical variable describing whether to ignore
-                       row numbers in the buffer.
+                             row numbers in the buffer.
 
 Variables which are calculated:
      array-line-length:      The number of characters in a buffer line.
-     array-lines-per-row:    The number of buffer lines used to display each row.
+     array-lines-per-row:    The number of buffer lines used to
+                             display each row.
 
   The following commands are available (an asterisk indicates it may
 take a numeric prefix argument):
@@ -834,17 +836,17 @@ take a numeric prefix argument):
     *          \\[array-next-row]        Move down one row.
     *          \\[array-previous-row]    Move up one row.
 
-    *   \\[array-copy-forward]   Copy the current field into the column to the right.
-    *   \\[array-copy-backward]          Copy the current field into the column to the left.
-    *   \\[array-copy-down]      Copy the current field into the row below.
-    *   \\[array-copy-up]        Copy the current field into the row above.
+    *   \\[array-copy-forward]   Copy current field into the column to the right.
+    *   \\[array-copy-backward]          Copy current field into the column to the left.
+    *   \\[array-copy-down]      Copy current field into the row below.
+    *   \\[array-copy-up]        Copy current field into the row above.
 
-    *   \\[array-copy-column-forward]   Copy the current column into the column to the right.
-    *   \\[array-copy-column-backward]   Copy the current column into the column to the left.
+    *   \\[array-copy-column-forward]   Copy current column into the column to the right.
+    *   \\[array-copy-column-backward]   Copy current column into the column to the left.
     *   \\[array-copy-row-down]   Copy the current row into the row below.
     *   \\[array-copy-row-up]   Copy the current row into the row above.
 
-        \\[array-fill-rectangle]   Copy the field at mark into every cell with row and column
+        \\[array-fill-rectangle]   Copy field at mark into every cell with row and column
                   between that of point and mark.
 
        \\[array-what-position]   Display the current array row and column.
@@ -855,7 +857,7 @@ take a numeric prefix argument):
         \\[array-expand-rows]   Expand the array (remove row numbers and
                   newlines inside rows)
 
-        \\[array-display-local-variables]   Display the current values of local variables.
+        \\[array-display-local-variables]   Display current values of local variables.
 
 Entering array mode calls the function `array-mode-hook'."
   (make-local-variable 'array-buffer-line)
index 742b2bb8728c58b0a6117d175e4de078a902c1c2..e2ef6ee6ba655853879ff3d1ef3858a8d39c4ace 100644 (file)
@@ -2157,7 +2157,7 @@ If non-nil, return a list consisting of the note and the cents coefficient."
    (calc-unary-op "midi" 'calcFunc-midi arg)))
 
 (defun calc-spn (arg)
-  "Return the scientific pitch notation corresponding to the expression on the stack."
+  "Return scientific pitch notation corresponding to the expression on the stack."
   (interactive "P")
   (calc-slow-wrapper
    (calc-unary-op "spn" 'calcFunc-spn arg)))
index b9805f6fac9ccd0a9fe2635b1fb9b88c9e2fc84b..0f202ddfc88a25cce931411548998e94742405ff 100644 (file)
@@ -258,8 +258,8 @@ If one doesn't exist, create a new one for this directory."
 INTERNAL-NAME is obsolete and ignored.
 EXTERNAL-NAME is a human readable name to describe the project; it
 must be unique among all autoloaded projects.
-PROJECTFILE is a file name that identifies a project of this type to EDE, such as
-a Makefile, or SConstruct file.
+PROJECTFILE is a file name that identifies a project of this type to EDE, such
+as a Makefile, or SConstruct file.
 CLASS is the EIEIO class that is used to track this project.  It should subclass
 `ede-generic-project'."
   (ede-add-project-autoload
index cafdc3bee149064acd24e9731c0f2760b2ed02f5..f2d2279c00183593cd109f319b4de36ca8e82960 100644 (file)
@@ -235,7 +235,8 @@ scoped.  These are not local variables, but symbols available in a structure
 which doesn't need to be dereferenced.
 Optional argument TYPERETURN is a symbol in which the types of all found
 will be stored.  If nil, that data is thrown away.
-Optional argument THROWSYM specifies a symbol the throw on non-recoverable error.
+Optional argument THROWSYM specifies a symbol the throw on non-recoverable
+error.
 Remaining arguments FLAGS are additional flags to apply when searching.")
 
 (defun semantic-analyze-find-tag-sequence-default
@@ -246,7 +247,8 @@ Remaining arguments FLAGS are additional flags to apply when searching.")
 SCOPE are extra tags which are in scope.
 TYPERETURN is a symbol in which to place a list of tag classes that
 are found in SEQUENCE.
-Optional argument THROWSYM specifies a symbol the throw on non-recoverable error.
+Optional argument THROWSYM specifies a symbol the throw on non-recoverable
+error.
 Remaining arguments FLAGS are additional flags to apply when searching.
 This function knows of flags:
   `mustbeclassvariable'"
index 3649d1c2f1fb4a991d15fc7884b97654c5db0f19..7f0c16136ce08da7a1e69194da9111dfc18a632e 100644 (file)
@@ -368,7 +368,8 @@ Take the first interesting thing and convert it."
 
 (defun semantic-c-evaluate-symbol-for-hideif (spp-symbol)
   "Lookup the symbol SPP-SYMBOL (a string) to something hideif can use.
-Pulls out the symbol list, and call `semantic-c-convert-spp-value-to-hideif-value'."
+Pull out the symbol list, and call
+`semantic-c-convert-spp-value-to-hideif-value'."
   (interactive "sSymbol name: ")
   (when (symbolp spp-symbol) (setq spp-symbol (symbol-name spp-symbol)))
 
index 07c55b46e26eacb6f2a033fe94d0b2bef6a13fe8..3ca7dcd48e2a6652a6b894cbdad7322613b5df0a 100644 (file)
@@ -50,7 +50,8 @@
    nil)
 
 (define-lex-regex-analyzer semantic-lex-make-command
-  "A command in a Makefile consists of a line starting with TAB, and ending at the newline."
+  "Regexp for a command in a Makefile.
+It consists of a line starting with TAB, and ending at the newline."
   "^\\(\t\\)"
   (let ((start (match-end 0)))
     (while (progn (end-of-line)
index 09f0e52e44d472808956ad1a3cc43e888d6e98a5..3b6f70ab32a779de11ade17cf674c122ddb6f6c0 100644 (file)
@@ -343,7 +343,7 @@ all included files."
   nil)
 
 (cl-defmethod semanticdb-typecache-include-tags ((table semanticdb-table))
-  "Update the typecache for TABLE, and return the merged types from the include tags.
+  "Update typecache for TABLE, and return the merged types from the include tags.
 Include-tags are the tags brought in via includes, all merged together into
 a master list."
   (let* ((cache (semanticdb-get-typecache table))
index 896bc3bb42ec682e0462ca1171c84ce9344902c1..e84e99e1e8d1b7cc922dbb0d74d76855b57b1120 100644 (file)
@@ -40,7 +40,7 @@ TAG might have DOCUMENTATION set in it already.  If not, there may be
 some documentation in a comment preceding TAG's definition which we
 can look for.  When appropriate, this can be overridden by a language specific
 enhancement.
-Optional argument NOSNARF means to only return the lexical analyzer token for it.
+Optional argument NOSNARF means return only the lexical analyzer token for it.
 If NOSNARF is `lex', then only return the lex token."
   (if (not tag) (setq tag (semantic-current-tag)))
   (save-excursion
index 3ee11df7d8ee234e06738de59451afb341776518..d07e5652484882a88476a9a270a2c3065be9622a 100644 (file)
@@ -93,8 +93,9 @@ for a given mode at a more granular level.
 Note that :type, :name, and anything in IGNORABLE-ATTRIBUTES will
 not be passed to this function.
 
-Modes that override this function can call `semantic--tag-attribute-similar-p-default'
-to do the default equality tests if ATTR is not special for that mode.")
+Modes that override this function can call
+`semantic--tag-attribute-similar-p-default' to do the default equality tests if
+ATTR is not special for that mode.")
 
 (defun semantic--tag-attribute-similar-p-default (attr value1 value2 ignorable-attributes)
   "For ATTR, VALUE1, VALUE2 and IGNORABLE-ATTRIBUTES, test for similarity."
index c8a6676b6655608b4e118802bad3ff5e76e28a2c..caa436ce2345d35954c2d2a7c4d6d0530f16776a 100644 (file)
@@ -2405,8 +2405,9 @@ as if they had been supplied to a function with TARGET-ARGLIST directly.
 Excess source arguments will be neglected, missing source arguments will be
 supplied as nil.  Returns a `funcall' or `apply' form with the second element
 being `function' which has to be replaced by an actual function argument.
-Example: (ad-map-arglists \\='(a &rest args) \\='(w x y z)) will return
-         (funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))."
+Example:
+   (ad-map-arglists \\='(a &rest args) \\='(w x y z)) will return
+   (funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))."
   (let* ((parsed-source-arglist (ad-parse-arglist source-arglist))
         (source-reqopt-args (append (nth 0 parsed-source-arglist)
                                     (nth 1 parsed-source-arglist)))
index 64f2c010824ed5a7fa0cbda4557c28ec9269847b..7e1a3304cc8f892124fa7f6415e1c100ebf1b537 100644 (file)
@@ -707,7 +707,8 @@ Each element is (INDEX . VALUE)")
 
 ;; These store their argument in the next two bytes
 (byte-defop 129  1 byte-constant2
-   "for reference to a constant with vector index >= byte-constant-limit")
+   "for reference to a constant with vector
+index >= byte-constant-limit")
 (byte-defop 130  0 byte-goto "for unconditional jump")
 (byte-defop 131 -1 byte-goto-if-nil "to pop value and jump if it's nil")
 (byte-defop 132 -1 byte-goto-if-not-nil "to pop value and jump if it's not nil")
@@ -727,11 +728,14 @@ otherwise pop it")
 (byte-defop 139  0 byte-save-window-excursion-OBSOLETE
   "to make a binding to record entire window configuration")
 (byte-defop 140  0 byte-save-restriction
-  "to make a binding to record the current buffer clipping restrictions")
+  "to make a binding to record the current buffer clipping
+restrictions")
 (byte-defop 141 -1 byte-catch-OBSOLETE   ; Not generated since Emacs 25.
-  "for catch.  Takes, on stack, the tag and an expression for the body")
+  "for catch.  Takes, on stack, the tag and an expression for
+the body")
 (byte-defop 142 -1 byte-unwind-protect
-  "for unwind-protect.  Takes, on stack, an expression for the unwind-action")
+  "for unwind-protect.  Takes, on stack, an expression for
+the unwind-action")
 
 ;; For condition-case.  Takes, on stack, the variable to bind,
 ;; an expression for the body, and a list of clauses.
@@ -791,8 +795,8 @@ otherwise pop it")
 (defconst byte-discardN-preserve-tos byte-discardN)
 
 (byte-defop 183 -2 byte-switch
- "to take a hash table and a value from the stack, and jump to the address
-the value maps to, if any.")
+ "to take a hash table and a value from the stack, and jump to
+the address the value maps to, if any.")
 
 ;; unused: 182-191
 
index b37b05b9a3ad0bdacdccaa430990293a1f4f2da6..9ddf9e7333bced44e6c395f8ea339451f83bb8f9 100644 (file)
@@ -811,8 +811,8 @@ It should return a function that expects the same arguments as the methods, and
 GENERIC is the generic function (mostly used for its name).
 METHODS is the list of the selected methods.
 The METHODS list is sorted from most specific first to most generic last.
-The function can use `cl-generic-call-method' to create functions that call those
-methods.")
+The function can use `cl-generic-call-method' to create functions that call
+those methods.")
 
 (unless (ignore-errors (cl-generic-generalizers t))
   ;; Temporary definition to let the next defmethod succeed.
index 4656277ea16f2c70586834a7ee480cda3d6d5b68..d91a33c140395c044652385fb32c9b54b4ac8f07 100644 (file)
@@ -317,7 +317,7 @@ list."
 
 ;;;###autoload
 (cl-defgeneric seq-filter (pred sequence)
-  "Return a list of all the elements for which (PRED element) is non-nil in SEQUENCE."
+  "Return a list of all elements for which (PRED element) is non-nil in SEQUENCE."
   (let ((exclude (make-symbol "exclude")))
     (delq exclude (seq-map (lambda (elt)
                              (if (funcall pred elt)
@@ -411,7 +411,8 @@ Equality is defined by TESTFN if non-nil or by `equal' if nil."
       nil))
 
 (cl-defgeneric seq-set-equal-p (sequence1 sequence2 &optional testfn)
-  "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements, regardless of order.
+  "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements.
+This does not depend on the order of the elements.
 Equality is defined by TESTFN if non-nil or by `equal' if nil."
   (and (seq-every-p (lambda (item1) (seq-contains-p sequence2 item1 testfn)) sequence1)
        (seq-every-p (lambda (item2) (seq-contains-p sequence1 item2 testfn)) sequence2)))
@@ -444,7 +445,7 @@ The result is a sequence of type TYPE, or a list if TYPE is nil."
          (seq-map function sequence)))
 
 (cl-defgeneric seq-partition (sequence n)
-  "Return a list of the elements of SEQUENCE grouped into sub-sequences of length N.
+  "Return list of elements of SEQUENCE grouped into sub-sequences of length N.
 The last sequence may contain less than N elements.  If N is a
 negative integer or 0, nil is returned."
   (unless (< n 1)
index 7355e1dd0a5690ae442e652db56af0506b1e6c9e..d0307fe173d1aa358fdd197ff35fa0ae5f3c3ec9 100644 (file)
@@ -272,7 +272,7 @@ of a face name is the same for all frames."
 (defun face-equal (face1 face2 &optional frame)
   "Non-nil if faces FACE1 and FACE2 are equal.
 Faces are considered equal if all their attributes are equal.
-If the optional argument FRAME is given, report on FACE1 and FACE2 in that frame.
+If optional argument FRAME is given, report on FACE1 and FACE2 in that frame.
 If FRAME is t, report on the defaults for FACE1 and FACE2 (for new frames).
 If FRAME is omitted or nil, use the selected frame."
   (internal-lisp-face-equal-p face1 face2 frame))
@@ -484,7 +484,7 @@ FACES may be either a single face or a list of faces.
 
 
 (defmacro face-attribute-specified-or (value &rest body)
-  "Return VALUE, unless it's `unspecified', in which case evaluate BODY and return the result."
+  "Return VALUE or, if it's `unspecified', the result of evaluating BODY."
   (let ((temp (make-symbol "value")))
     `(let ((,temp ,value))
        (if (not (eq ,temp 'unspecified))
index c049aa88a5d58ece2a0f09f2d834841e56c64b2e..efaf440d191bcd6b705c90cdcff1bce3ace8902b 100644 (file)
@@ -3105,9 +3105,11 @@ See `Info-scroll-down'."
 (defun Info-next-reference-or-link (pat prop)
   "Move point to the next pattern-based cross-reference or property-based link.
 The next cross-reference is searched using the regexp PAT, and the next link
-is searched using the text property PROP.  Move point to the closest found position
-of either a cross-reference found by `re-search-forward' or a link found by
-`next-single-char-property-change'.  Return the new position of point, or nil."
+is searched using the text property PROP.  Move point to the closest found
+position of either a cross-reference found by `re-search-forward' or a link
+found by `next-single-char-property-change'.
+
+Return the new position of point, or nil."
   (let ((pxref (save-excursion (re-search-forward pat nil t)))
        (plink (next-single-char-property-change (point) prop)))
     (when (and (< plink (point-max)) (not (get-char-property plink prop)))
@@ -3120,10 +3122,12 @@ of either a cross-reference found by `re-search-forward' or a link found by
 
 (defun Info-prev-reference-or-link (pat prop)
   "Move point to the previous pattern-based cross-reference or property-based link.
-The previous cross-reference is searched using the regexp PAT, and the previous link
-is searched using the text property PROP.  Move point to the closest found position
-of either a cross-reference found by `re-search-backward' or a link found by
-`previous-single-char-property-change'.  Return the new position of point, or nil."
+The previous cross-reference is searched using the regexp PAT, and the previous
+link is searched using the text property PROP.  Move point to the closest found
+position of either a cross-reference found by `re-search-backward' or a link
+found by `previous-single-char-property-change'.
+
+Return the new position of point, or nil."
   (let ((pxref (save-excursion (re-search-backward pat nil t)))
        (plink (previous-single-char-property-change (point) prop)))
     (when (and (> plink (point-min)) (not (get-char-property plink prop)))
index 0d5c480c8d4f0d0912b1fd5e34b1c0358131a535..13173a28579f8fa716f045438ef674ddd2ddcc9a 100644 (file)
@@ -1603,7 +1603,8 @@ If this is set inside code wrapped by the macro
   "Exit Isearch mode, run BODY, and reinvoke the pending search.
 You can update the global isearch variables by setting new values to
 `isearch-new-string', `isearch-new-message', `isearch-new-forward',
-`isearch-new-regexp-function', `isearch-new-case-fold', `isearch-new-nonincremental'."
+`isearch-new-regexp-function', `isearch-new-case-fold',
+`isearch-new-nonincremental'."
   ;; This code is very hairy for several reasons, explained in the code.
   ;; Mainly, isearch-mode must be terminated while editing and then restarted.
   ;; If there were a way to catch any change of buffer from the minibuffer,
index 3437dba5e6aac71b1c6310322f698b95526936d1..17db48c329858477e5464d607c0436b4e69346b0 100644 (file)
@@ -289,7 +289,8 @@ the last increment."
 
 (defun kmacro-set-counter (arg)
   "Set the value of `kmacro-counter' to ARG, or prompt for value if no argument.
-With \\[universal-argument] prefix, reset counter to its value prior to this iteration of the macro."
+With \\[universal-argument] prefix, reset counter to its value prior to this iteration of the
+macro."
   (interactive "NMacro counter value: ")
   (if (not (or defining-kbd-macro executing-kbd-macro))
       (kmacro-display-counter (setq kmacro-initial-counter-value arg))
@@ -1272,7 +1273,8 @@ following additional answers: `insert', `insert-1', `replace', `replace-1',
 (defun kmacro-step-edit-macro ()
   "Step edit and execute last keyboard macro.
 
-To customize possible responses, change the \"bindings\" in `kmacro-step-edit-map'."
+To customize possible responses, change the \"bindings\" in
+`kmacro-step-edit-map'."
   (interactive)
   (let ((kmacro-step-edit-active t)
        (kmacro-step-edit-new-macro "")
index 5a2ba027f973f9ec590b477776552f8816a77351..cd63b0ebefa7d55b9927665e34b12579178639e6 100644 (file)
@@ -7558,7 +7558,8 @@ With a prefix argument, do so in all agenda buffers."
   "Filter lines in the agenda buffer that have a specific category.
 The category is that of the current line.
 With a `\\[universal-argument]' prefix argument, exclude the lines of that category.
-When there is already a category filter in place, this command removes the filter."
+When there is already a category filter in place, this command removes the
+filter."
   (interactive "P")
   (if (and org-agenda-filtered-by-category
           org-agenda-category-filter)
index bfafc132bf5b9130294196aca99c39dc68f4dc90..2a28ad3add72704f5950708f34c5777c20a15464 100644 (file)
@@ -430,7 +430,8 @@ when to emit a progress message.")
   local-printer-list)
 
 (defmacro ses-cell-symbol (row &optional col)
-  "From a CELL or a pair (ROW,COL), get the symbol that names the local-variable holding its value.  (0,0) => A1."
+  "Return symbol of the local-variable holding value of CELL or pair (ROW,COL).
+For example, (0,0) => A1."
   (declare (debug t))
   `(ses-cell--symbol ,(if col `(ses-get-cell ,row ,col) row)))
 (put 'ses-cell-symbol 'safe-function t)
index e159d1888e5c5ca330537112a299c54f5fa54275..f1dcc54043d76ad92cdfd9880ca8f1f966dd7b37 100644 (file)
@@ -55,7 +55,7 @@
               w32-system-shells)))
 
 (defun w32-shell-dos-semantics ()
-  "Return non-nil if the interactive shell being used expects MS-DOS shell semantics."
+  "Return non-nil if current interactive shell expects MS-DOS shell semantics."
   (or (w32-system-shell-p (w32-shell-name))
       (and (member (downcase (file-name-nondirectory (w32-shell-name)))
                   '("cmdproxy" "cmdproxy.exe"))