Doc fix.

4 files changed, 77 insertions, 66 deletions

diff --git a/lisp/=diary-ins.el b/lisp/=diary-ins.el
index 1ac2c0bfc0c..49c6836c20f 100644
--- a/lisp/=diary-ins.el
+++ b/lisp/=diary-ins.el
@@ -151,8 +151,9 @@ Prefix arg will make the entry nonmarking."
    arg))
 
 (defun insert-hebrew-diary-entry (arg)
-  "Insert a diary entry for the Hebrew date corresponding to the date
-indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert a diary entry.
+For the Hebrew date corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-month-name-array
           calendar-hebrew-month-name-array-leap-year))
@@ -168,8 +169,9 @@ indicated by point.  Prefix arg will make the entry nonmarking."
      arg)))
 
 (defun insert-monthly-hebrew-diary-entry (arg)
-  "Insert a monthly diary entry for the day of the Hebrew month corresponding
-to the date indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert a monthly diary entry.
+For the day of the Hebrew month corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-date-display-form
           (if european-calendar-style '(day " * ") '("* " day )))
@@ -186,8 +188,9 @@ to the date indicated by point.  Prefix arg will make the entry nonmarking."
      arg)))
 
 (defun insert-yearly-hebrew-diary-entry (arg)
-  "Insert an annual diary entry for the day of the Hebrew year corresponding
-to the date indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert an annual diary entry.
+For the day of the Hebrew year corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-date-display-form
           (if european-calendar-style
@@ -206,8 +209,9 @@ to the date indicated by point.  Prefix arg will make the entry nonmarking."
      arg)))
 
 (defun insert-islamic-diary-entry (arg)
-  "Insert a diary entry for the Islamic date corresponding to the date
-indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert a diary entry.
+For the Islamic date corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-month-name-array calendar-islamic-month-name-array))
     (make-diary-entry
@@ -222,8 +226,9 @@ indicated by point.  Prefix arg will make the entry nonmarking."
      arg)))
 
 (defun insert-monthly-islamic-diary-entry (arg)
-  "Insert a monthly diary entry for the day of the Islamic month corresponding
-to the date indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert a monthly diary entry.
+For the day of the Islamic month corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-date-display-form
           (if european-calendar-style '(day " * ") '("* " day )))
@@ -239,8 +244,9 @@ to the date indicated by point.  Prefix arg will make the entry nonmarking."
      arg)))
 
 (defun insert-yearly-islamic-diary-entry (arg)
-  "Insert an annual diary entry for the day of the Islamic year corresponding
-to the date indicated by point.  Prefix arg will make the entry nonmarking."
+  "Insert an annual diary entry.
+For the day of the Islamic year corresponding to the date indicated by point.
+Prefix arg will make the entry nonmarking."
   (interactive "P")
   (let* ((calendar-date-display-form
           (if european-calendar-style
diff --git a/lisp/comint.el b/lisp/comint.el
index 86fe60fbedc..244f78becd6 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -559,13 +559,14 @@ fetches previous (older) inputs."
   (comint-previous-similar-input (- arg)))
 
 (defun comint-send-input () 
-  "Send input to process.  After the process output mark, sends all text
-from the process mark to point as input to the process.  Before the process
-output mark, calls value of variable comint-get-old-input to retrieve old
-input, copies it to the process mark, and sends it.  A terminal newline is
-also inserted into the buffer and sent to the process.  In either case, value
-of variable comint-input-sentinel is called on the input before sending it.
-The input is entered into the input history ring, if the value of variable
+  "Send input to process.
+After the process output mark, sends all text from the process mark to
+point as input to the process.  Before the process output mark, calls value
+of variable comint-get-old-input to retrieve old input, copies it to the
+process mark, and sends it.  A terminal newline is also inserted into the
+buffer and sent to the process.  In either case, value of variable
+comint-input-sentinel is called on the input before sending it.  The input
+is entered into the input history ring, if the value of variable
 comint-input-filter returns non-nil when called on the input.
 
 If variable comint-eol-on-send is non-nil, then point is moved to the end of
@@ -612,8 +613,9 @@ Similarly for Soar, Scheme, etc."
 	  (set-marker (process-mark proc) (point))))))
 
 (defun comint-get-old-input-default ()
-  "Default for comint-get-old-input: take the current line, and discard
-any initial text matching comint-prompt-regexp."
+  "Default for comint-get-old-input.
+Take the current line, and discard any initial text matching
+comint-prompt-regexp."
   (save-excursion
     (beginning-of-line)
     (comint-skip-prompt)
@@ -666,11 +668,12 @@ in your hook, comint-mode-hook."
 ;;; Just enter m-x send-invisible and type in your line.
 
 (defun comint-read-noecho (prompt &optional stars)
-  "Prompt the user with argument PROMPT. Read a single line of text
-without echoing, and return it. Note that the keystrokes comprising
-the text can still be recovered (temporarily) with \\[view-lossage]. This
-may be a security bug for some applications. Optional argument STARS
-causes input to be echoed with '*' characters on the prompt line."
+  "Prompt the user with argument PROMPT. 
+Read a single line of text without echoing, and return it. Note that
+the keystrokes comprising the text can still be recovered (temporarily)
+with \\[view-lossage]. This may be a security bug for some applications.
+Optional argument STARS causes input to be echoed with '*' characters
+on the prompt line."
   (let ((echo-keystrokes 0)
 	(cursor-in-echo-area t)
 	(answ "")
@@ -687,9 +690,9 @@ causes input to be echoed with '*' characters on the prompt line."
 
 
 (defun send-invisible (str)
-  "Read a string without echoing, and send it to the process running
-in the current buffer. A new-line is additionally sent. String is not 
-saved on comint input history list.
+  "Read a string without echoing.
+Then send it to the process running in the current buffer. A new-line
+is additionally sent. String is not saved on comint input history list.
 Security bug: your string can still be temporarily recovered with
 \\[view-lossage]."
 ; (interactive (list (comint-read-noecho "Enter non-echoed text")))
@@ -1023,8 +1026,9 @@ Useful if you accidentally suspend the top-level process."
 
 
 (defun comint-replace-by-expanded-filename ()
-"Replace the filename at point with an expanded, canonicalised, and
-completed replacement.
+"Expand the filename at point.
+Replace the filename with an expanded, canonicalised, and completed
+ replacement.
 \"Expanded\" means environment variables (e.g., $HOME) and ~'s are
 replaced with the corresponding directories.  \"Canonicalised\" means ..
 and \. are removed, and the filename is made absolute instead of relative.
diff --git a/lisp/completion.el b/lisp/completion.el
index 65e8496c560..a24269799d4 100644
--- a/lisp/completion.el
+++ b/lisp/completion.el
@@ -1502,7 +1502,8 @@ Sets up cmpl-db-downcase-string and cmpl-db-symbol."
        ))
 
 (defun find-cmpl-prefix-entry (prefix-string)
-  "Returns the prefix entry for string. Sets cmpl-db-prefix-symbol.
+  "Returns the prefix entry for string.
+Sets cmpl-db-prefix-symbol.
 Prefix-string must be exactly *completion-prefix-min-length* long
 and downcased.  Sets up cmpl-db-prefix-symbol."
   (and (boundp (setq cmpl-db-prefix-symbol
@@ -1513,8 +1514,9 @@ and downcased.  Sets up cmpl-db-prefix-symbol."
 ;; used to trap lossage in silent error correction
 
 (defun locate-completion-entry (completion-entry prefix-entry)
-  "Locates the completion entry.  Returns a pointer to the element
-before the completion entry or nil if the completion entry is at the head.
+  "Locates the completion entry.
+Returns a pointer to the element before the completion entry or nil if
+the completion entry is at the head.
 Must be called after find-exact-completion."
   (let ((prefix-list (cmpl-prefix-entry-head prefix-entry))
 	 next-prefix-list
@@ -1570,9 +1572,10 @@ Must be called after find-exact-completion."
 
 ;;; WRITES
 (defun add-completion-to-tail-if-new (string)
-  "If the string is not in the database it is added to the end of the
-approppriate prefix list with num-uses = 0.  The database is unchanged if it 
-is there.  string must be longer than *completion-prefix-min-length*.
+  "If STRING is not in the database add it to appropriate prefix list.
+STRING is added to the end of the approppriate prefix list with
+num-uses = 0.  The database is unchanged if it is there.  STRING must be
+longer than *completion-prefix-min-length*.
 This must be very fast.
 Returns the completion entry."
   (or (find-exact-completion string)
@@ -1603,9 +1606,10 @@ Returns the completion entry."
 	)))
 
 (defun add-completion-to-head (string)
-  "If the string is not in the database it is added to the head of the
-approppriate prefix list.  Otherwise it is moved to the head of the list.
-string must be longer than *completion-prefix-min-length*.
+  "If STRING is not in the database, add it to prefix list.
+STRING is added to the head of the approppriate prefix list.  Otherwise
+it is moved to the head of the list.  STRING must be longer than
+*completion-prefix-min-length*.
 Updates the saved string with the supplied string.
 This must be very fast.
 Returns the completion entry."
@@ -1661,8 +1665,8 @@ Returns the completion entry."
       )))
       
 (defun delete-completion (string)
-  "Deletes the completion from the database.  string must be longer than
-*completion-prefix-min-length*."
+  "Deletes the completion from the database.
+String must be longer than *completion-prefix-min-length*."
   ;; Handle pending acceptance
   (if completion-to-accept (accept-completion))
   (if (setq cmpl-db-entry (find-exact-completion string))
@@ -1812,30 +1816,28 @@ completion-search-reset."
     ))
 
 (defun use-completion-under-point ()
-  "Call this to add the completion symbol underneath the point into
-the completion buffer."
+  "Adds the completion symbol underneath the point into the completion buffer."
   (let ((string (and *completep* (symbol-under-point)))
 	(current-completion-source cmpl-source-cursor-moves))
     (if string (add-completion-to-head string))))
 	
 (defun use-completion-before-point ()
-  "Call this to add the completion symbol before point into
+  "Adds the completion symbol before point into
 the completion buffer."
   (let ((string (and *completep* (symbol-before-point)))
 	(current-completion-source cmpl-source-cursor-moves))
     (if string (add-completion-to-head string))))
 
 (defun use-completion-under-or-before-point ()
-  "Call this to add the completion symbol before point into
-the completion buffer."
+  "Adds the completion symbol before point into the completion buffer."
   (let ((string (and *completep* (symbol-under-or-before-point)))
 	(current-completion-source cmpl-source-cursor-moves))
     (if string (add-completion-to-head string))))
 
 (defun use-completion-before-separator ()
-  "Call this to add the completion symbol before point into
-the completion buffer.  Completions added this way will automatically be
-saved if *separator-character-uses-completion-p* is non-nil."
+  "Adds the completion symbol before point into the completion buffer.
+Completions added this way will automatically be saved if
+*separator-character-uses-completion-p* is non-nil."
   (let ((string (and *completep* (symbol-before-point)))
 	(current-completion-source cmpl-source-separator)
 	entry)
@@ -1925,9 +1927,9 @@ String must be longer than *completion-prefix-min-length*."
 	))
 
 (defun completion-search-next (index)
-  "Returns the next completion entry.  If index is out of sequence it resets
-and starts from the top.  If there are no more entries it tries cdabbrev and 
-returns only a string."
+  "Returns the next completion entry.
+If index is out of sequence it resets and starts from the top.
+If there are no more entries it tries cdabbrev and returns only a string."
   (cond
     ((= index (setq cmpl-last-index (1+ cmpl-last-index)))
      (completion-search-peek t))
@@ -2517,8 +2519,7 @@ completion database."
 ;;;---------------------------------------------------------------------------
 
 (defun kill-emacs-save-completions ()
-  "The version of save-completions-to-file called at kill-emacs
-time."
+  "The version of save-completions-to-file called at kill-emacs time."
   (when (and *save-completions-p* *completep* cmpl-initialized-p)
     (cond
       ((not cmpl-completions-accepted-p)
@@ -2542,8 +2543,8 @@ time."
   (concat filename ".BAK"))
 
 (defun save-completions-to-file (&optional filename)
-  "Saves a completion init file.  If file is not specified,
-   then *saved-completions-filename* is used."
+  "Saves a completion init file.
+If file is not specified, then *saved-completions-filename* is used."
   (interactive)
   (setq filename (expand-file-name (or filename *saved-completions-filename*)))
   (when (file-writable-p filename)
@@ -2649,8 +2650,8 @@ time."
 (pushnew 'autosave-completions cmpl-emacs-idle-time-hooks)
 
 (defun load-completions-from-file (&optional filename no-message-p)
-  "loads a completion init file.  If file is not specified,
-   then *saved-completions-filename* is used"
+  "Loads a completion init file.
+If file is not specified, then *saved-completions-filename* is used."
   (interactive)
   (setq filename (expand-file-name (or filename *saved-completions-filename*)))
   (let* ((backup-filename (completion-backup-filename filename))
@@ -2753,8 +2754,8 @@ time."
 	  )))))
 
 (defun initialize-completions ()
-  "Loads the default completions file and sets up so that exiting emacs will
-automatically save the file."
+  "Loads the default completions file.
+Also sets up so that exiting emacs will automatically save the file."
   (interactive)
   (cond ((not cmpl-initialized-p)
 	 (load-completions-from-file)
@@ -2852,9 +2853,8 @@ Patched to remove the most recent completion."
 ;;; the functions defined with this macro get byte compiled.
 
 (defmacro def-completion-wrapper (function-name type &optional new-name)
-  "Add a call to update the completion database before the function is
-executed.  TYPE is the type of the wrapper to be added.  Can be :before or
-:under."
+  "Add a call to update the completion database before function execution.
+TYPE is the type of the wrapper to be added.  Can be :before or :under."
   (completion-advise-1
    function-name ':before
    (ecase type
diff --git a/lisp/emacs-lisp/cust-print.el b/lisp/emacs-lisp/cust-print.el
index da14363d970..2dc18d43f93 100644
--- a/lisp/emacs-lisp/cust-print.el
+++ b/lisp/emacs-lisp/cust-print.el
@@ -217,8 +217,9 @@ uninstall-custom-print-funcs."
 ;; (or princ) -- so far only the printing and formatting subrs.
 
 (defun custom-prin1 (object &optional stream)
-  "Replacement for standard prin1 that uses the appropriate
-printer depending on the values of print-level and print-circle (which see).
+  "Replacement for standard prin1.
+Uses the appropriate printer depending on the values of print-level
+and print-circle (which see).
 
 Output the printed representation of OBJECT, any Lisp object.
 Quoting characters are printed when needed to make output that `read'