Shorten some over-wide docstrings in functions and macros

* 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)

lisp/allout-widgets.el

@@ -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.
 

lisp/array.el

@@ -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-forward]	  Copy current field into the column to the right.
-    *   \\[array-copy-backward]	  Copy the current field into the column to the left.
+    *   \\[array-copy-backward]	  Copy current field into the column to the left.
-    *   \\[array-copy-down]	  Copy the current field into the row below.
+    *   \\[array-copy-down]	  Copy current field into the row below.
-    *   \\[array-copy-up]	  Copy the current field into the row above.
+    *   \\[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-forward]   Copy 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-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)

lisp/calc/calc-units.el

@@ -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)))

lisp/cedet/ede/generic.el

@@ -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
+PROJECTFILE is a file name that identifies a project of this type to EDE, such
-a Makefile, or SConstruct file.
+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

lisp/cedet/semantic/analyze.el

@@ -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'"

lisp/cedet/semantic/bovine/c.el

@@ -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)))
 

lisp/cedet/semantic/bovine/make.el

@@ -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)

lisp/cedet/semantic/db-typecache.el

@@ -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))

lisp/cedet/semantic/doc.el

@@ -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

lisp/cedet/semantic/tag-ls.el

@@ -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'
+Modes that override this function can call
-to do the default equality tests if ATTR is not special for that mode.")
+`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."

lisp/emacs-lisp/advice.el

@@ -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
+Example:
-         (funcall ad--addoit-function a (car args) (car (cdr args)) (nth 2 args))."
+   (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)))

lisp/emacs-lisp/bytecomp.el

@@ -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
+ "to take a hash table and a value from the stack, and jump to
-the value maps to, if any.")
+the address the value maps to, if any.")
 
 ;; unused: 182-191
 

lisp/emacs-lisp/cl-generic.el

@@ -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
+The function can use `cl-generic-call-method' to create functions that call
-methods.")
+those methods.")
 
 (unless (ignore-errors (cl-generic-generalizers t))
   ;; Temporary definition to let the next defmethod succeed.

lisp/emacs-lisp/seq.el

@@ -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)

lisp/faces.el

@@ -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))

lisp/info.el

@@ -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
+is searched using the text property PROP.  Move point to the closest found
-of either a cross-reference found by `re-search-forward' or a link found by
+position of either a cross-reference found by `re-search-forward' or a link
-`next-single-char-property-change'.  Return the new position of point, or nil."
+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
+The previous cross-reference is searched using the regexp PAT, and the previous
-is searched using the text property PROP.  Move point to the closest found position
+link is searched using the text property PROP.  Move point to the closest found
-of either a cross-reference found by `re-search-backward' or a link found by
+position of either a cross-reference found by `re-search-backward' or a link
-`previous-single-char-property-change'.  Return the new position of point, or nil."
+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)))

lisp/isearch.el

@@ -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,

lisp/kmacro.el

@@ -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 "")

lisp/org/org-agenda.el

@@ -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)

lisp/ses.el

@@ -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)

lisp/w32-fns.el

@@ -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"))