From 570cb659c71c610484c85507ce6688e2acd82980 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 15 Jun 2024 14:55:31 +0300 Subject: [PATCH] Fix doc strings in ispell.el * lisp/textmodes/ispell.el (ispell-check-version) (ispell-get-casechars, ispell-get-not-casechars) (ispell-get-otherchars, ispell-get-many-otherchars-p) (ispell-get-ispell-args, ispell-get-extended-character-mode) (ispell-get-coding-system, ispell-word, ispell-get-word) (ispell-pdict-save, ispell-command-loop, ispell-help) (ispell-filter, ispell-highlight-spelling-error) (ispell-change-dictionary, ispell-region, ispell-ignore-fcc) (ispell-get-line, ispell-message): Doc fixes (bug#71532) (cherry picked from commit 45a191738c661d6161ec82a4664bf8bee387219c) --- lisp/textmodes/ispell.el | 111 ++++++++++++++++++++++++--------------- 1 file changed, 68 insertions(+), 43 deletions(-) diff --git a/lisp/textmodes/ispell.el b/lisp/textmodes/ispell.el index f523df9881e..67be936ca24 100644 --- a/lisp/textmodes/ispell.el +++ b/lisp/textmodes/ispell.el @@ -649,8 +649,8 @@ this would require some extra guessing in `ispell-aspell-find-dictionary'.") (defun ispell-check-version (&optional interactivep) "Ensure that `ispell-program-name' is valid and has the correct version. -Returns version number if called interactively. -Otherwise returns the library directory name, if that is defined." +Return version number if called interactively, or if INTERACTIVEP is non-nil. +Otherwise return the library directory name, if that is defined." ;; This is a little wasteful as we actually launch ispell twice: once ;; to make sure it's the right version, and once for real. But people ;; get confused by version mismatches *all* the time (and I've got the @@ -1517,23 +1517,30 @@ This is passed to the Ispell process using the `-p' switch.") (decode-coding-string str (ispell-get-coding-system) t)))) (defun ispell-get-casechars () + "Return CASECHARS of a dictionary." (ispell-get-decoded-string 1)) (defun ispell-get-not-casechars () + "Return NOT-CASECHARS of a dictionary." (ispell-get-decoded-string 2)) (defun ispell-get-otherchars () + "Return OTHERCHARS of a dictionary." (ispell-get-decoded-string 3)) (defun ispell-get-many-otherchars-p () + "Return MANY-OTHERCHARS of a dictionary." (nth 4 (or (assoc ispell-current-dictionary ispell-local-dictionary-alist) (assoc ispell-current-dictionary ispell-dictionary-alist)))) (defun ispell-get-ispell-args () + "Return ARGS of a dictionary." (nth 5 (or (assoc ispell-current-dictionary ispell-local-dictionary-alist) (assoc ispell-current-dictionary ispell-dictionary-alist)))) (defun ispell-get-extended-character-mode () + "Return extended character mode of a dictionary." (if ispell-really-hunspell ;; hunspell treats ~word as ordinary words nil ;; in pipe mode. Disable extended-char-mode (nth 6 (or (assoc ispell-current-dictionary ispell-local-dictionary-alist) (assoc ispell-current-dictionary ispell-dictionary-alist))))) (defun ispell-get-coding-system () + "Return encoding of a dictionary." (nth 7 (or (assoc ispell-current-dictionary ispell-local-dictionary-alist) (assoc ispell-current-dictionary ispell-dictionary-alist)))) @@ -1909,6 +1916,7 @@ resume interrupted spell-checking of a buffer or region. Interactively, in Transient Mark mode when the mark is active, call `ispell-region' to check the active region for spelling errors. +Non-interactively, this happens if REGION is non-nil. Word syntax is controlled by the definition of the chosen dictionary, which is in `ispell-local-dictionary-alist' or `ispell-dictionary-alist'. @@ -2053,7 +2061,9 @@ many times (see the doc string of `ispell-dictionary-alist' for details about otherchars). Word syntax is controlled by the definition of the chosen dictionary, -which is in `ispell-local-dictionary-alist' or `ispell-dictionary-alist'." +which is in `ispell-local-dictionary-alist' or `ispell-dictionary-alist'. +EXTRA-OTHERCHARS, if non-nil, is the set of extra characters to add +to the dictionary's OTHERCHARS." (ispell-set-spellchecker-params) ; Initialize variables and dicts alists (let* ((ispell-casechars (ispell-get-casechars)) (ispell-not-casechars (ispell-get-not-casechars)) @@ -2117,7 +2127,11 @@ which is in `ispell-local-dictionary-alist' or `ispell-dictionary-alist'." ;;;###autoload (defun ispell-pdict-save (&optional no-query force-save) "Check to see if the personal dictionary has been modified. -If so, ask if it needs to be saved." +If so, ask if it needs to be saved. +If NO-QUERY is non-nil, save the personal dictionary without asking. +Interactively, if `ispell-silently-savep' is non-nil, don't ask. +If FORCE-SAVE is non-nil, suggest to save the personal dictionary even +if not modified; this always happens interactively." (interactive (list ispell-silently-savep t)) (if (and ispell-pdict-modified-p (listp ispell-pdict-modified-p)) (setq ispell-pdict-modified-p (car ispell-pdict-modified-p))) @@ -2136,19 +2150,20 @@ It is called once per iteration, before displaying a prompt to the user.") (defun ispell-command-loop (miss guess word start end) - "Display possible corrections from list MISS. + "Display possible corrections from MISS using GUESS for WORD in START..END. +MISS lists possible corrections. GUESS lists possibly valid affix construction of WORD. -Returns nil to keep word. -Returns 0 to insert locally into buffer-local dictionary. -Returns string for new chosen word. -Returns list for new replacement word (will be rechecked). - Query-replace when list length is 2. - Automatic query-replace when second element is `query-replace'. -Highlights the word, which is assumed to run from START to END. +Return nil to keep the word unchanged. +Return 0 to insert locally into buffer-local dictionary. +Return a string for the chosen replacement word. +Return a list for new replacement word (will be rechecked). + Use `query-replace' when list length is 2. + Automatic `query-replace' when second element is `query-replace'. +Highlight the word, which is assumed to run from START to END. Global `ispell-pdict-modified-p' becomes a list where the only value indicates whether the dictionary has been modified when option `a' or `i' is used. -Global `ispell-quit' set to start location to continue spell session." +Global `ispell-quit' is set to start location to continue spell session." (let ((count ?0) (choices miss) (window-min-height (min window-min-height @@ -2433,23 +2448,23 @@ Global `ispell-quit' set to start location to continue spell session." Selections are: \\`0'..\\`9' Replace the word with a digit offered in the *Choices* buffer. -\\`SPC' Accept word this time. -\\`i' Accept word and insert into private dictionary. -\\`a' Accept word for this session. -\\`A' Accept word and place in `buffer-local dictionary'. -\\`r' Replace word with typed-in value. Rechecked. -\\`R' Replace word with typed-in value. Query-replaced in buffer. Rechecked. -\\`?' Show these commands. -\\`x' Exit spelling buffer. Move cursor to original point. -\\`X' Exit spelling buffer. Leaves cursor at the current point, and permits - the aborted check to be completed later. -\\`q' Quit spelling session (Kills ispell process). -\\`l' Look up typed-in replacement in alternate dictionary. Wildcards okay. -\\`u' Like \\`i', but the word is lower-cased first. -\\`m' Place typed-in value in personal dictionary, then recheck current word. -\\`C-l' Redraw screen. -\\`C-r' Recursive edit. -\\`C-z' Suspend Emacs or iconify frame." +\\`SPC' Accept word this time. +\\`i' Accept word and insert into private dictionary. +\\`a' Accept word for this session. +\\`A' Accept word and place in `buffer-local dictionary'. +\\`r' Replace word with typed-in value. Rechecked. +\\`R' Replace word with typed-in value. Query-replaced in buffer. Rechecked. +\\`?' Show these commands. +\\`x' Exit spelling buffer. Move cursor to original point. +\\`X' Exit spelling buffer. Leaves cursor at the current point, and permits + the aborted check to be completed later. +\\`q' Quit spelling session (Kills ispell process). +\\`l' Look up typed-in replacement in alternate dictionary. Wildcards okay. +\\`u' Like \\`i', but the word is lower-cased first. +\\`m' Place typed-in value in personal dictionary, then recheck current word. +\\`C-l' Redraw screen. +\\`C-r' Recursive edit. +\\`C-z' Suspend Emacs or iconify frame." (if (equal ispell-help-in-bufferp 'electric) (progn @@ -2600,7 +2615,9 @@ this function signals an error." ;; in this case treats the next input received as fresh input. (defun ispell-filter (_process output) - "Output filter function for ispell, grep, and look." + "Filter function for ispell, grep, and look, process OUTPUT from subprocess. +OUTPUT can contain multiple lines, part of a single line, or both. +OUTPUT must end with a newline." (let ((start 0) (continue t) end) @@ -2705,6 +2722,10 @@ The variable `ispell-highlight-face' selects the face to use for highlighting." (defun ispell-highlight-spelling-error (start end &optional highlight refresh) + "Highlight spelling error between START and END. +Optional argument HIGHLIGHT, if non-nil, means to highlight mis-spelling. +See `ispell-highlight-spelling-error-generic' for the meaning of optional +argument REFRESH, which is passed to that function as the 4th argument." (if (display-color-p) (ispell-highlight-spelling-error-overlay start end highlight) (ispell-highlight-spelling-error-generic start end highlight refresh))) @@ -3020,10 +3041,10 @@ With CLEAR, buffer session localwords are cleaned." ;;;###autoload (defun ispell-change-dictionary (dict &optional arg) "Change to dictionary DICT for Ispell. -With a prefix arg, set it \"globally\", for all buffers. -Without a prefix arg, set it \"locally\", just for this buffer. +If ARG is non-nil (interactively, the prefix arg), set it \"globally\", +for all buffers. Otherwise, set it \"locally\", just for this buffer. -By just answering RET you can find out what the current dictionary is." +By just answering RET you can find out the name of the current dictionary." (interactive (list (completing-read "Use new dictionary (RET for current, SPC to complete): " @@ -3086,7 +3107,7 @@ when needed." ;;;###autoload (defun ispell-region (reg-start reg-end &optional recheckp shift) - "Interactively check a region for spelling errors. + "Interactively check region between REG-START and REG-END for spelling errors. Leave the mark at the last misspelled word that the user was queried about. Return nil if spell session was terminated, otherwise returns shift offset @@ -3341,10 +3362,12 @@ Must be called after `ispell-buffer-local-parsing' due to dependence on mode." (defun ispell-ignore-fcc (start end) - "Delete the Fcc: message header when large attachments are included. -Return value nil if file with large attachments is saved. + "Query whether to delete Fcc header due to attachment between START and END. +Query the user whether Fcc header should be deleted when large attachments are +included in the message. +Return nil if email with large attachments should be saved. This can be used to avoid multiple questions for multiple large attachments. -Returns point to starting location afterwards." +Return point to starting location afterwards." (let ((result t)) (if (and ispell-checking-message ispell-message-fcc-skip) (if (< ispell-message-fcc-skip (- end start)) @@ -3420,8 +3443,8 @@ Point is placed at end of skipped region." (defun ispell-get-line (start end in-comment) - "Grab the next line of data. -Returns a string with the line data." + "Grab the next line of text between START and END. +Return a string with the line data." (let ((ispell-casechars (ispell-get-casechars)) string) (cond ; LOOK AT THIS LINE AND SKIP OR PROCESS @@ -3892,10 +3915,12 @@ Otherwise, it must be a function which is called to get the limit.") (defun ispell-mime-skip-part (boundary) - "Move point across header, or entire MIME part if message is encoded. + "Move point across text that matches BOUNDARY, or across entire message. +BOUNDARY, if non-nil, specifies the part of the message to skip, either +the header, or entire MIME part if the message is encoded. All specified types except `7bit' `8bit' and `quoted-printable' are considered encoded and therefore skipped. See rfc 1521, 2183, ... -If no boundary is given, then entire message is skipped. +If BOUNDARY is nil, the entire message is skipped. This starts one line ABOVE the MIME content messages, on the boundary marker, for operation with the generic region-skipping code. @@ -3976,7 +4001,7 @@ in your init file: (add-hook \\='mail-send-hook #\\='ispell-message) (add-hook \\='mh-before-send-letter-hook #\\='ispell-message) -You can bind this to the key C-c i in GNUS or mail by adding to +You can bind this to a key in GNUS or mail by adding to `news-reply-mode-hook' or `mail-mode-hook' the following lambda expression: (lambda () (local-set-key \"\\C-ci\" \\='ispell-message))" (interactive) -- 2.39.2