From: Juanma Barranquero Date: Sun, 20 Oct 2019 10:12:27 +0000 (+0200) Subject: lisp/*.el: Fix typos and improve some docstrings X-Git-Tag: emacs-27.0.90~970 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=41ba8231ef072571e1a6feabc15d113e5cf57556;p=emacs.git lisp/*.el: Fix typos and improve some docstrings * lisp/auth-source.el (auth-source-backend-parse-parameters) (auth-source-search-collection) (auth-source-secrets-listify-pattern) (auth-source--decode-octal-string, auth-source-plstore-search): * lisp/registry.el (registry-lookup) (registry-lookup-breaks-before-lexbind) (registry-lookup-secondary, registry-lookup-secondary-value) (registry-search, registry-delete, registry-size, registry-full) (registry-insert, registry-reindex, registry-prune) (registry-collect-prune-candidates): * lisp/subr.el (nbutlast, process-live-p): * lisp/tab-bar.el (tab-bar-list): * lisp/cedet/ede/linux.el (ede-linux--get-archs) (ede-linux--include-path, ede-linux-load): * lisp/erc/erc-log.el (erc-log-all-but-server-buffers): * lisp/erc/erc-pcomplete.el (pcomplete-erc-commands) (pcomplete-erc-ops, pcomplete-erc-not-ops, pcomplete-erc-nicks) (pcomplete-erc-all-nicks, pcomplete-erc-channels) (pcomplete-erc-command-name, pcomplete-erc-parse-arguments): * lisp/eshell/em-term.el (eshell-visual-command-p): * lisp/gnus/gnus-cache.el (gnus-cache-fully-p): * lisp/gnus/nnmail.el (nnmail-get-active) (nnmail-fancy-expiry-target): * lisp/mail/mail-utils.el (mail-string-delete): * lisp/mail/supercite.el (sc-hdr, sc-valid-index-p): * lisp/net/ange-ftp.el (ange-ftp-use-smart-gateway-p): * lisp/net/nsm.el (nsm-save-fingerprint-maybe) (nsm-network-same-subnet, nsm-should-check): * lisp/net/rcirc.el (rcirc-looking-at-input): * lisp/net/tramp-cache.el (tramp-get-hash-table): * lisp/net/tramp-compat.el (tramp-compat-process-running-p): * lisp/net/tramp-smb.el (tramp-smb-get-share) (tramp-smb-get-localname, tramp-smb-read-file-entry) (tramp-smb-get-cifs-capabilities, tramp-smb-get-stat-capability): * lisp/net/zeroconf.el (zeroconf-list-service-names) (zeroconf-list-service-types, zeroconf-list-services) (zeroconf-get-host, zeroconf-get-domain) (zeroconf-get-host-domain): * lisp/nxml/rng-xsd.el (rng-xsd-compile) (rng-xsd-make-date-time-regexp, rng-xsd-convert-date-time): * lisp/obsolete/erc-hecomplete.el (erc-hecomplete) (erc-command-list, erc-complete-at-prompt): * lisp/org/ob-scheme.el (org-babel-scheme-get-buffer-impl): * lisp/org/ob-shell.el (org-babel--variable-assignments:sh-generic) (org-babel--variable-assignments:bash_array) (org-babel--variable-assignments:bash_assoc) (org-babel--variable-assignments:bash): * lisp/org/org-clock.el (org-day-of-week): * lisp/progmodes/cperl-mode.el (cperl-char-ends-sub-keyword-p): * lisp/progmodes/gud.el (gud-find-c-expr, gud-innermost-expr) (gud-prev-expr, gud-next-expr): * lisp/textmodes/table.el (table--at-cell-p, table--probe-cell) (table--get-cell-justify-property) (table--get-cell-valign-property) (table--put-cell-justify-property) (table--put-cell-valign-property): Fix typos. * lisp/so-long.el (fboundp): Doc fix. (so-long-mode-line-info, so-long-mode) (so-long--check-header-modes): Fix typos. * lisp/emulation/viper-mous.el (viper-surrounding-word) (viper-mouse-click-get-word): Fix typos. (viper-mouse-click-search-word): Doc fix. * lisp/erc/erc-backend.el (erc-forward-word, erc-word-at-arg-p) (erc-bounds-of-word-at-point): Fix typos. (erc-decode-string-from-target, define-erc-response-handler): Refill docstring. * lisp/erc/erc-dcc.el (pcomplete/erc-mode/DCC): Fix typo. (erc-dcc-get-host, erc-dcc-auto-mask-p, erc-dcc-get-file): Doc fixes. * lisp/erc/erc-networks.el (erc-network-name): Fix typo. (erc-determine-network): Refill docstring. * lisp/net/dbus.el (dbus-list-hash-table) (dbus-string-to-byte-array, dbus-byte-array-to-string) (dbus-check-event): Fix typos. (dbus-introspect-get-property): Doc fix. * lisp/net/tramp-adb.el (tramp-adb-file-name-handler): Rename ARGS to ARGUMENTS. Doc fix. (tramp-adb-sh-fix-ls-output, tramp-adb-execute-adb-command) (tramp-adb-find-test-command): Fix typos. * lisp/net/tramp.el (tramp-set-completion-function) (tramp-get-completion-function) (tramp-completion-dissect-file-name) (tramp-completion-dissect-file-name1) (tramp-get-completion-methods, tramp-get-completion-user-host) (tramp-get-inode, tramp-get-device, tramp-mode-string-to-int) (tramp-call-process, tramp-call-process-region) (tramp-process-lines): Fix typos. (tramp-interrupt-process): Doc fix. * lisp/org/ob-core.el (org-babel-named-src-block-regexp-for-name) (org-babel-named-data-regexp-for-name): Doc fix. (org-babel-src-block-names, org-babel-result-names): Fix typos. * lisp/progmodes/inf-lisp.el (lisp-input-filter): Doc fix. (lisp-fn-called-at-pt): Fix typo. * lisp/progmodes/xref.el (xref-backend-identifier-at-point): Doc fix. (xref-backend-identifier-completion-table): Fix typo. --- diff --git a/ChangeLog.2 b/ChangeLog.2 index d26ea14d16d..453889de295 100644 --- a/ChangeLog.2 +++ b/ChangeLog.2 @@ -4970,7 +4970,7 @@ * msdos/sed1v2.inp: Adapt to Emacs 25. * src/process.c (remove_slash_colon): Move out of "#ifdef - subprocesses" block, as it its called unconditionally. Move + subprocesses" block, as it is called unconditionally. Move ADD_SUBFEATURE calls into "#ifdef subprocesses" block, as they reference variables only defined in that block. * src/msdos.h: Provide prototypes for IT_set_frame_parameters, @@ -17774,7 +17774,7 @@ 2015-11-08 Dmitry Gutov - Remove dirs in vc project roots from the the vc project library roots + Remove dirs in vc project roots from the vc project library roots * lisp/progmodes/project.el (project-library-roots): Remove directories inside the project roots from the result. diff --git a/ChangeLog.3 b/ChangeLog.3 index 747fd5627ca..a5eec1f5736 100644 --- a/ChangeLog.3 +++ b/ChangeLog.3 @@ -1037,7 +1037,7 @@ If there are directory entries in the list then they are sorted in order of name length. The list of modes for that dir is then recursively sorted with the same mechanism. That way variables tied - to a particular subdirectory override those in in a parent directory. + to a particular subdirectory override those in a parent directory. Previously the behaviour didn’t seem to be well defined anyway and was dependent on the order they appeared in the file. However this order @@ -8841,7 +8841,7 @@ If grow_specpdl fails due to outgrowing max_specpdl_size, it will signal an error *before* growing the specpdl array. Therefore, when handling the signal, specpdl_ptr points past the end of the specpdl - array and any further use of of specpdl before unwinding (e.g., if + array and any further use of specpdl before unwinding (e.g., if edebug binds signal-hook-function) will cause memory corruption. * src/eval.c (signal_or_quit): Don't call `signal-hook-function' if the specpdl_ptr is already past the end of the specpdl array. @@ -12008,7 +12008,7 @@ Improve edit-kbd-macro prompting in case of remapped keys (Bug#29399) * lisp/edmacro.el (edit-kbd-macro): Use substitute-command-keys to - present the current bindings in the prompt. Check the the + present the current bindings in the prompt. Check the non-remapped binding of the entered key sequence as well. 2017-12-02 Lele Gaifax @@ -24195,7 +24195,7 @@ Optimize UCS normalization tests - Brings the the time for `ucs-normalize-part1' from 200s down to 130s. + Brings the time for `ucs-normalize-part1' from 200s down to 130s. * test/lisp/international/ucs-normalize-tests.el (ucs-normalize-tests--parse-column): Use character instead of string of length 1 for terminator. Convert return value into string since @@ -63687,7 +63687,7 @@ 2016-01-29 Lars Ingebrigtsen - Compilation for for systems with getaddrinfo_a + Compilation for systems with getaddrinfo_a * src/process.c (Fmake_network_process): Make stuff work again on systems with getaddrinfo_a. @@ -63701,7 +63701,7 @@ 2016-01-29 Lars Ingebrigtsen - Compilation for for non-GNU systems + Compilation for non-GNU systems * src/process.c (Fmake_network_process): Make compilation work again on hosts that don't have getaddrinfo_a. diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 4c644f1a62e..1938c4c50ba 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -4632,7 +4632,7 @@ decoded text. The decoding functions ignore newline characters in the encoded text. -If optional argument @var{base64url} is is non-@code{nil}, then padding +If optional argument @var{base64url} is non-@code{nil}, then padding is optional, and the URL variant of base 64 encoding is used. @end defun diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS index 249750171b5..7acd96bd502 100644 --- a/etc/ORG-NEWS +++ b/etc/ORG-NEWS @@ -3754,7 +3754,7 @@ that Calc formulas can operate on them. **** org-ctags.el (Paul Sexton) Targets like =<>= can now be found by Emacs' etag - functionality, and Org-mode links can be used to to link to + functionality, and Org-mode links can be used to link to etags, also in non-Org-mode files. For details, see the file /org-ctags.el/. diff --git a/lisp/ChangeLog.17 b/lisp/ChangeLog.17 index ed3b4a9dd8e..4ce684b831b 100644 --- a/lisp/ChangeLog.17 +++ b/lisp/ChangeLog.17 @@ -4647,7 +4647,7 @@ * vc.el: All backends: API simplification: Remove 4th 'default-state' argument from vc-dir-status files and its backend methods - no backend method ever set it. It was used only in the - fallback method to to set a default of 'up-to-date, though a + fallback method to set a default of 'up-to-date, though a convoluted call chain obscured this. * vc-hooks.el: Bind vc-delete-file to Ctrl-x v delete. diff --git a/lisp/auth-source.el b/lisp/auth-source.el index fdd869df3a6..4926f67f0a1 100644 --- a/lisp/auth-source.el +++ b/lisp/auth-source.el @@ -504,7 +504,7 @@ soon as a function returns non-nil.") (add-hook 'auth-source-backend-parser-functions #'auth-source-backends-parser-secrets) (defun auth-source-backend-parse-parameters (entry backend) - "Fills in the extra auth-source-backend parameters of ENTRY. + "Fill in the extra auth-source-backend parameters of ENTRY. Using the plist ENTRY, get the :host, :port, and :user search parameters." (let ((entry (if (stringp entry) @@ -773,7 +773,7 @@ Returns the deleted entries." (apply #'auth-source-search (plist-put spec :delete t))) (defun auth-source-search-collection (collection value) - "Returns t is VALUE is t or COLLECTION is t or COLLECTION contains VALUE." + "Return t if VALUE is t or COLLECTION is t or COLLECTION contains VALUE." (when (and (atom collection) (not (eq t collection))) (setq collection (list collection))) @@ -1514,15 +1514,15 @@ Respects `auth-source-save-behavior'. Uses ;;; Backend specific parsing: Secrets API backend (defun auth-source-secrets-listify-pattern (pattern) - "Convert a pattern with lists to a list of string patterns. + "Convert a PATTERN with lists to a list of string patterns. auth-source patterns can have values of the form :foo (\"bar\" \"qux\"), which means to match any secret with :foo equal to \"bar\" or :foo equal to \"qux\". The secrets backend supports only string values for patterns, so this routine returns a list -of patterns that is equivalent to the single original pattern +of patterns that is equivalent to the single original PATTERN when interpreted such that if a secret matches any pattern in the -list, it matches the original pattern." +list, it matches the original PATTERN." (if (null pattern) '(nil) (let* ((key (pop pattern)) @@ -1935,7 +1935,7 @@ entries for git.gnus.org: (defun auth-source--decode-octal-string (string) - "Convert octal string to utf-8 string. E.g: 'a\134b' to 'a\b'" + "Convert octal string to utf-8 string. E.g: 'a\134b' to 'a\b'" (let ((list (string-to-list string)) (size (length string))) (decode-coding-string @@ -2034,7 +2034,7 @@ entries for git.gnus.org: (cl-defun auth-source-plstore-search (&rest spec &key backend create delete max &allow-other-keys) - "Search the PLSTORE; spec is like `auth-source'." + "Search the PLSTORE; SPEC is like `auth-source'." (let* ((store (oref backend data)) (max (or max 5000)) ; sanity check: default to stop at 5K (ignored-keys '(:create :delete :max :backend :label :require :type)) diff --git a/lisp/cedet/ChangeLog.1 b/lisp/cedet/ChangeLog.1 index 8333dd30f3c..1d34219daa0 100644 --- a/lisp/cedet/ChangeLog.1 +++ b/lisp/cedet/ChangeLog.1 @@ -1324,7 +1324,7 @@ (semantic-analyze-tag-references-default): When doing a lookup, specify noerror. (semantic--analyze-refs-full-lookup): Add optional noerror input - argument. Pass to to full-lookup-simple. + argument. Pass to full-lookup-simple. (semantic-analyze-refs-impl, semantic-analyze-refs-proto): Ignore :typemodifiers during compare. diff --git a/lisp/cedet/ede/linux.el b/lisp/cedet/ede/linux.el index b5a6482bbdf..90e14ce87ce 100644 --- a/lisp/cedet/ede/linux.el +++ b/lisp/cedet/ede/linux.el @@ -118,7 +118,7 @@ If DIR has not been used as a build directory, fall back to (defun ede-linux--get-archs (dir) - "Returns a list of architecture names found in DIR." + "Return a list of architecture names found in DIR." (let ((archs-dir (expand-file-name "arch" dir)) archs) (when (file-directory-p archs-dir) @@ -169,7 +169,7 @@ found in DIR." (defun ede-linux--include-path (dir bdir arch) - "Returns a list with include directories. + "Return a list with include directories. Returned directories might not exist, since they are not created until Linux is built for the first time." (cl-map 'list @@ -186,7 +186,7 @@ until Linux is built for the first time." ;;;###autoload (defun ede-linux-load (dir &optional _rootproj) - "Return an Linux Project object if there is a match. + "Return a Linux Project object if there is a match. Return nil if there isn't one. Argument DIR is the directory it is created for. ROOTPROJ is nil, since there is only one project." diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el index 87b3133b7f5..57d633f8f0b 100644 --- a/lisp/emacs-lisp/rx.el +++ b/lisp/emacs-lisp/rx.el @@ -258,7 +258,7 @@ Return (REGEXP . PRECEDENCE)." ;; -> (any "@" "%" digit "A-Z" space word) ;; -> "[A-Z@%[:digit:][:space:][:word:]]" ;; - ;; Problem: If a subpattern is carefully written to to be + ;; Problem: If a subpattern is carefully written to be ;; optimisable by regexp-opt, how do we prevent the transforms ;; above from destroying that property? ;; Example: (or "a" (or "abc" "abd" "abe")) diff --git a/lisp/emulation/viper-mous.el b/lisp/emulation/viper-mous.el index e076e988866..5451f33d477 100644 --- a/lisp/emulation/viper-mous.el +++ b/lisp/emulation/viper-mous.el @@ -138,7 +138,7 @@ considered related." (declare-function viper-forward-char-carefully "viper-cmd" (&optional arg)) (defun viper-surrounding-word (count click-count) - "Returns word surrounding point according to a heuristic. + "Return word surrounding point according to a heuristic. COUNT indicates how many regions to return. If CLICK-COUNT is 1, `word' is a word in Vi sense. If CLICK-COUNT is 2,then `word' is a Word in Vi sense. @@ -219,7 +219,7 @@ is ignored." (defun viper-mouse-click-get-word (click count click-count) - "Returns word surrounding the position of a mouse click. + "Return word surrounding the position of a mouse click. Click may be in another window. Current window and buffer isn't changed. On single or double click, returns the word as determined by `viper-surrounding-word-function'." @@ -334,12 +334,13 @@ See `viper-surrounding-word' for the definition of a word in this case." (declare-function viper-adjust-window "viper-cmd" ()) (defun viper-mouse-click-search-word (click arg) - "Find the word clicked or double-clicked on. Word may be in another window. + "Find the word clicked or double-clicked on. Word may be in another window. With prefix argument, N, search for N-th occurrence. This command must be bound to a mouse click. The double-click action of the same button must not be bound \(or it must be bound to the same function). See `viper-surrounding-word' for the details on what constitutes a word for -this command." +this command. +\n(fn CLICK N)" (interactive "e\nP") (if viper-frame-of-focus ;; to handle clicks in another frame (select-frame viper-frame-of-focus)) diff --git a/lisp/erc/erc-backend.el b/lisp/erc/erc-backend.el index 3250d0fdfde..72a7f86da2f 100644 --- a/lisp/erc/erc-backend.el +++ b/lisp/erc/erc-backend.el @@ -481,13 +481,13 @@ Currently this is called by `erc-send-input'." (split-string (buffer-string) "\n")))) (defun erc-forward-word () - "Moves forward one word, ignoring any subword settings. If no -subword-mode is active, then this is (forward-word)." + "Move forward one word, ignoring any subword settings. +If no subword-mode is active, then this is (forward-word)." (skip-syntax-forward "^w") (> (skip-syntax-forward "w") 0)) (defun erc-word-at-arg-p (pos) - "Reports whether the char after a given POS has word syntax. + "Report whether the char after a given POS has word syntax. If POS is out of range, the value is nil." (let ((c (char-after pos))) (if c @@ -495,9 +495,9 @@ If POS is out of range, the value is nil." nil))) (defun erc-bounds-of-word-at-point () - "Returns the bounds of a word at point, or nil if we're not at -a word. If no subword-mode is active, then this -is (bounds-of-thing-at-point 'word)." + "Return the bounds of word at point, or nil if we're not at a word. +If no subword-mode is active, then this is +\(bounds-of-thing-at-point 'word)." (if (or (erc-word-at-arg-p (point)) (erc-word-at-arg-p (1- (point)))) (save-excursion @@ -596,7 +596,7 @@ We will store server variables in the buffer given by BUFFER." (erc-login)) )) (defun erc-server-reconnect () -"Reestablish the current IRC connection. + "Reestablish the current IRC connection. Make sure you are in an ERC buffer when running this." (let ((buffer (erc-server-buffer))) (unless (buffer-live-p buffer) @@ -765,8 +765,8 @@ This is determined via `erc-encoding-coding-alist' or (defun erc-decode-string-from-target (str target) "Decode STR as appropriate for TARGET. -This is indicated by `erc-encoding-coding-alist', defaulting to the value of -`erc-server-coding-system'." +This is indicated by `erc-encoding-coding-alist', defaulting to the +value of `erc-server-coding-system'." (unless (stringp str) (setq str "")) (let ((coding (erc-coding-system-for-target target))) @@ -1118,7 +1118,8 @@ NAME is the response name as sent by the server (see the IRC RFC for meanings). This creates: - - a hook variable `erc-server-NAME-functions' initialized to `erc-server-NAME'. + - a hook variable `erc-server-NAME-functions' initialized to + `erc-server-NAME'. - a function `erc-server-NAME' with body FN-BODY. If ALIASES is non-nil, each alias in ALIASES is `defalias'ed to diff --git a/lisp/erc/erc-dcc.el b/lisp/erc/erc-dcc.el index f8bd5bf3083..899fa5d0fed 100644 --- a/lisp/erc/erc-dcc.el +++ b/lisp/erc/erc-dcc.el @@ -309,7 +309,7 @@ Should be set to a string or nil. If nil, use the value of :type '(choice (const ask) (const auto) (const ignore))) (defun erc-dcc-get-host (proc) - "Returns the local IP address used for an open PROCess." + "Return the local IP address used for an open process PROC." (format-network-address (process-contact proc :local) t)) (defun erc-dcc-host () @@ -413,7 +413,7 @@ where FOO is one of CLOSE, GET, SEND, LIST, CHAT, etc." ;;;###autoload (defun pcomplete/erc-mode/DCC () - "Provides completion for the /DCC command." + "Provide completion for the /DCC command." (pcomplete-here (append '("chat" "close" "get" "list") (when (fboundp 'make-network-process) '("send")))) (pcomplete-here @@ -685,9 +685,10 @@ It extracts the information about the dcc request and adds it to ?n nick ?u login ?h host ?q query))))) (defun erc-dcc-auto-mask-p (spec) - "Takes a full SPEC of a user in the form \"nick!login@host\" and -matches against all the regexp's in `erc-dcc-auto-masks'. If any -match, returns that regexp and nil otherwise." + "Match SPEC against `erc-dcc-auto-masks'. +SPEC is a full spec of a user in the form \"nick!login@host\", which +is matched against all the regexps in `erc-dcc-auto-masks'. Return +the matching regexp, or nil if none found." (let ((lst erc-dcc-auto-masks)) (while (and lst (not (string-match (car lst) spec))) @@ -907,9 +908,9 @@ other client." (make-variable-buffer-local 'erc-dcc-file-name) (defun erc-dcc-get-file (entry file parent-proc) - "This function does the work of setting up a transfer from the remote client -to the local one over a tcp connection. This involves setting up a process -filter and a process sentinel, and making the connection." + "Set up a transfer from the remote client to the local over a TCP connection. +This involves setting up a process filter and a process sentinel, +and making the connection." (let* ((buffer (generate-new-buffer (file-name-nondirectory file))) proc) (with-current-buffer buffer diff --git a/lisp/erc/erc-log.el b/lisp/erc/erc-log.el index d6763c01f36..b9bf40d6fab 100644 --- a/lisp/erc/erc-log.el +++ b/lisp/erc/erc-log.el @@ -283,7 +283,7 @@ The current buffer is given by BUFFER." erc-enable-logging nil)))) (defun erc-log-all-but-server-buffers (buffer) - "Returns t if logging should be enabled in BUFFER. + "Return t if logging should be enabled in BUFFER. Returns nil if `erc-server-buffer-p' returns t." (save-excursion (save-window-excursion diff --git a/lisp/erc/erc-networks.el b/lisp/erc/erc-networks.el index 352f714491f..dbd0e1da893 100644 --- a/lisp/erc/erc-networks.el +++ b/lisp/erc/erc-networks.el @@ -730,9 +730,9 @@ MATCHER is used to find a corresponding network to a server while ;;;###autoload (defun erc-determine-network () - "Return the name of the network or \"Unknown\" as a symbol. Use the -server parameter NETWORK if provided, otherwise parse the server name and -search for a match in `erc-networks-alist'." + "Return the name of the network or \"Unknown\" as a symbol. +Use the server parameter NETWORK if provided, otherwise parse the +server name and search for a match in `erc-networks-alist'." ;; The server made it easy for us and told us the name of the NETWORK (let ((network-name (cdr (assoc "NETWORK" erc-server-parameters)))) (if network-name @@ -760,7 +760,7 @@ Return the name of this server's network as a symbol." "Obsolete since erc-networks 1.5") (defun erc-network-name () - "Returns the name of the current network as a string." + "Return the name of the current network as a string." (erc-with-server-buffer (symbol-name erc-network))) (defun erc-set-network-name (proc parsed) diff --git a/lisp/erc/erc-pcomplete.el b/lisp/erc/erc-pcomplete.el index 55405498f1e..fe01e1d76e6 100644 --- a/lisp/erc/erc-pcomplete.el +++ b/lisp/erc/erc-pcomplete.el @@ -188,14 +188,14 @@ for use on `completion-at-point-function'." ;;; Functions that provide possible completions. (defun pcomplete-erc-commands () - "Returns a list of strings of the defined user commands." + "Return a list of strings of the defined user commands." (let ((case-fold-search nil)) (mapcar (lambda (x) (concat "/" (downcase (substring (symbol-name x) 8)))) (apropos-internal "erc-cmd-[A-Z]+")))) (defun pcomplete-erc-ops () - "Returns a list of nicks with ops." + "Return a list of nicks with ops." (let (ops) (maphash (lambda (nick cdata) (if (and (cdr cdata) @@ -205,7 +205,7 @@ for use on `completion-at-point-function'." ops)) (defun pcomplete-erc-not-ops () - "Returns a list of nicks without ops." + "Return a list of nicks without ops." (let (not-ops) (maphash (lambda (nick cdata) (if (and (cdr cdata) @@ -216,7 +216,7 @@ for use on `completion-at-point-function'." (defun pcomplete-erc-nicks (&optional postfix ignore-self) - "Returns a list of nicks in the current channel. + "Return a list of nicks in the current channel. Optional argument POSTFIX is something to append to the nickname. If optional argument IGNORE-SELF is non-nil, don't return the current nick." (let ((users (if erc-pcomplete-order-nickname-completions @@ -235,7 +235,7 @@ If optional argument IGNORE-SELF is non-nil, don't return the current nick." (nreverse nicks))) (defun pcomplete-erc-all-nicks (&optional postfix) - "Returns a list of all nicks on the current server." + "Return a list of all nicks on the current server." (let (nicks) (erc-with-server-buffer (maphash (lambda (_nick user) @@ -246,20 +246,20 @@ If optional argument IGNORE-SELF is non-nil, don't return the current nick." nicks)) (defun pcomplete-erc-channels () - "Returns a list of channels associated with the current server." + "Return a list of channels associated with the current server." (mapcar (lambda (buf) (with-current-buffer buf (erc-default-target))) (erc-channel-list erc-server-process))) ;;; Functions for parsing (defun pcomplete-erc-command-name () - "Returns the command name of the first argument." + "Return the command name of the first argument." (if (eq (elt (pcomplete-arg 'first) 0) ?/) (upcase (substring (pcomplete-arg 'first) 1)) "SAY")) (defun pcomplete-erc-parse-arguments () - "Returns a list of parsed whitespace-separated arguments. + "Return a list of parsed whitespace-separated arguments. These are the words from the beginning of the line after the prompt up to where point is right now." (let* ((start erc-input-marker) diff --git a/lisp/eshell/em-term.el b/lisp/eshell/em-term.el index 36a26e9346b..06d59cfc5b5 100644 --- a/lisp/eshell/em-term.el +++ b/lisp/eshell/em-term.el @@ -150,7 +150,7 @@ behavior for short-lived processes, see bug#18108." eshell-interpreter-alist))) (defun eshell-visual-command-p (command args) - "Returns non-nil when given a visual command. + "Return non-nil when given a visual command. If either COMMAND or a subcommand in ARGS (e.g. git log) is a visual command, returns non-nil." (let ((command (file-name-nondirectory command))) diff --git a/lisp/gnus/gnus-cache.el b/lisp/gnus/gnus-cache.el index f43c4344dc2..db73bf234a0 100644 --- a/lisp/gnus/gnus-cache.el +++ b/lisp/gnus/gnus-cache.el @@ -732,7 +732,7 @@ If LOW, update the lower bound instead." (rename-file gnus-cache-directory dir)) (defun gnus-cache-fully-p (&optional group) - "Returns non-nil if the cache should be fully used. + "Return non-nil if the cache should be fully used. If GROUP is non-nil, also cater to `gnus-cacheable-groups' and `gnus-uncacheable-groups'." (and gnus-use-cache diff --git a/lisp/gnus/nnmail.el b/lisp/gnus/nnmail.el index 33912f8cfa2..fc9713e9561 100644 --- a/lisp/gnus/nnmail.el +++ b/lisp/gnus/nnmail.el @@ -646,7 +646,7 @@ These will be logged to the \"*nnmail split*\" buffer." (or file ""))) (defun nnmail-get-active () - "Returns an assoc of group names and active ranges. + "Return an assoc of group names and active ranges. nn*-request-list should have been called before calling this function." ;; Go through all groups from the active list. (with-current-buffer nntp-server-buffer @@ -1909,7 +1909,7 @@ If TIME is nil, then return the cutoff time for oldness instead." (gnus-group-mark-article-read target (cdr group-art)))))))) (defun nnmail-fancy-expiry-target (group) - "Returns a target expiry group determined by `nnmail-fancy-expiry-targets'." + "Return a target expiry group determined by `nnmail-fancy-expiry-targets'." (let* (header (case-fold-search nil) (from (or (message-fetch-field "from") "")) diff --git a/lisp/mail/mail-utils.el b/lisp/mail/mail-utils.el index fd00dd19bc2..24015858b02 100644 --- a/lisp/mail/mail-utils.el +++ b/lisp/mail/mail-utils.el @@ -56,7 +56,7 @@ also the To field, unless this would leave an empty To field." (looking-at "BABYL OPTIONS:")))) (defun mail-string-delete (string start end) - "Returns a string containing all of STRING except the part + "Return a string containing all of STRING except the part from START (inclusive) to END (exclusive)." (if (null end) (substring string 0 start) (concat (substring string 0 start) diff --git a/lisp/mail/supercite.el b/lisp/mail/supercite.el index 556e4b3923f..f292920d30e 100644 --- a/lisp/mail/supercite.el +++ b/lisp/mail/supercite.el @@ -1461,7 +1461,7 @@ First runs `sc-pre-recite-hook'." ;; building headers (defun sc-hdr (prefix field &optional sep return-nil-p) - "Returns a concatenation of PREFIX and FIELD. + "Return a concatenation of PREFIX and FIELD. If FIELD is not a string or is the empty string, the empty string will be returned. Optional third argument SEP is concatenated on the end if it is a string. Returns empty string, unless optional RETURN-NIL-P is @@ -1589,7 +1589,7 @@ Treats these fields in a similar manner to `sc-header-on-said'." "Current electric reference style.") (defun sc-valid-index-p (index) - "Returns INDEX if it is a valid index into `sc-rewrite-header-list'. + "Return INDEX if it is a valid index into `sc-rewrite-header-list'. Otherwise returns nil." ;; a number, and greater than or equal to zero ;; less than or equal to the last index diff --git a/lisp/net/ange-ftp.el b/lisp/net/ange-ftp.el index b0a1e1799f5..a5fc9631e8a 100644 --- a/lisp/net/ange-ftp.el +++ b/lisp/net/ange-ftp.el @@ -1708,7 +1708,7 @@ good, skip, fatal, or unknown." (not (string-match-p ange-ftp-local-host-regexp host)))) (defun ange-ftp-use-smart-gateway-p (host) - "Returns whether to access this HOST via a smart gateway." + "Return whether to access this HOST via a smart gateway." (and ange-ftp-smart-gateway (not (string-match-p ange-ftp-local-host-regexp host)))) diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el index c3297ac9da6..f3f6fecb956 100644 --- a/lisp/net/dbus.el +++ b/lisp/net/dbus.el @@ -493,7 +493,7 @@ This is an internal function, it shall not be used outside dbus.el." ;;; Hash table of registered functions. (defun dbus-list-hash-table () - "Returns all registered member registrations to D-Bus. + "Return all registered member registrations to D-Bus. The return value is a list, with elements of kind (KEY . VALUE). See `dbus-registered-objects-table' for a description of the hash table." @@ -888,7 +888,7 @@ association to the service from D-Bus." ;;; D-Bus type conversion. (defun dbus-string-to-byte-array (string) - "Transforms STRING to list (:array :byte c1 :byte c2 ...). + "Transform STRING to list (:array :byte c1 :byte c2 ...). STRING shall be UTF8 coded." (if (zerop (length string)) '(:array :signature "y") @@ -897,7 +897,7 @@ STRING shall be UTF8 coded." (setq result (append result (list :byte elt))))))) (defun dbus-byte-array-to-string (byte-array &optional multibyte) - "Transforms BYTE-ARRAY into UTF8 coded string. + "Transform BYTE-ARRAY into UTF8 coded string. BYTE-ARRAY must be a list of structure (c1 c2 ...), or a byte array as produced by `dbus-string-to-byte-array'. The resulting string is unibyte encoded, unless MULTIBYTE is non-nil." @@ -947,7 +947,7 @@ STRING must have been encoded with `dbus-escape-as-identifier'." ;;; D-Bus events. (defun dbus-check-event (event) - "Checks whether EVENT is a well formed D-Bus event. + "Check whether EVENT is a well formed D-Bus event. EVENT is a list which starts with symbol `dbus-event': (dbus-event BUS TYPE SERIAL SERVICE PATH INTERFACE MEMBER HANDLER &rest ARGS) @@ -1319,7 +1319,7 @@ SERVICE is a service of D-Bus BUS at object path PATH." (push (dbus-introspect-get-attribute elt "name") result)))) (defun dbus-introspect-get-property (bus service path interface property) - "This function returns PROPERTY of INTERFACE as XML object. + "Return PROPERTY of INTERFACE as XML object. It must be located at SERVICE in D-Bus BUS at object path PATH. PROPERTY must be a string, element of the list returned by `dbus-introspect-get-property-names'. The resulting PROPERTY diff --git a/lisp/net/nsm.el b/lisp/net/nsm.el index 4ca770fd7e1..c47ef55a6f4 100644 --- a/lisp/net/nsm.el +++ b/lisp/net/nsm.el @@ -179,7 +179,7 @@ See also: `nsm-check-tls-connection', `nsm-save-host-names', (const :tag "High" high))))) (defun nsm-save-fingerprint-maybe (host port status &rest _) - "Saves the certificate's fingerprint. + "Save the certificate's fingerprint. In order to detect man-in-the-middle attacks, when `network-security-level' is `high', this function will save the @@ -199,7 +199,7 @@ RESULTS is an alist where the keys are the checks run and the values the results of the checks.") (defun nsm-network-same-subnet (local-ip mask ip) - "Returns t if IP is in the same subnet as LOCAL-IP/MASK. + "Return t if IP is in the same subnet as LOCAL-IP/MASK. LOCAL-IP, MASK, and IP are specified as vectors of integers, and are expected to have the same length. Works for both IPv4 and IPv6 addresses." @@ -217,7 +217,7 @@ IPv6 addresses." matches)) (defun nsm-should-check (host) - "Determines whether NSM should check for TLS problems for HOST. + "Determine whether NSM should check for TLS problems for HOST. If `nsm-trust-local-network' is or returns non-nil, and if the host address is a localhost address, or in the same subnet as one diff --git a/lisp/net/rcirc.el b/lisp/net/rcirc.el index 5722582ab6c..4a94afe0917 100644 --- a/lisp/net/rcirc.el +++ b/lisp/net/rcirc.el @@ -3063,7 +3063,7 @@ Passwords are stored in `rcirc-authinfo' (which see)." ;; When using M-x flyspell-mode, only check words after the prompt (put 'rcirc-mode 'flyspell-mode-predicate 'rcirc-looking-at-input) (defun rcirc-looking-at-input () - "Returns true if point is past the input marker." + "Return true if point is past the input marker." (>= (point) rcirc-prompt-end-marker)) diff --git a/lisp/net/tramp-adb.el b/lisp/net/tramp-adb.el index 982522bdaf4..e1706bebe6e 100644 --- a/lisp/net/tramp-adb.el +++ b/lisp/net/tramp-adb.el @@ -177,14 +177,14 @@ It is used for TCP/IP devices." tramp-adb-method))) ;;;###tramp-autoload -(defun tramp-adb-file-name-handler (operation &rest args) +(defun tramp-adb-file-name-handler (operation &rest arguments) "Invoke the ADB handler for OPERATION. -First arg specifies the OPERATION, second arg is a list of arguments to -pass to the OPERATION." +First arg specifies the OPERATION, second arg is a list of +ARGUMENTS to pass to the OPERATION." (let ((fn (assoc operation tramp-adb-file-name-handler-alist))) (if fn - (save-match-data (apply (cdr fn) args)) - (tramp-run-real-handler operation args)))) + (save-match-data (apply (cdr fn) arguments)) + (tramp-run-real-handler operation arguments)))) ;;;###tramp-autoload (tramp--with-startup @@ -462,7 +462,7 @@ Convert (\"-al\") to (\"-a\" \"-l\"). Remove arguments like \"--dired\"." (defun tramp-adb-sh-fix-ls-output (&optional sort-by-time) "Insert dummy 0 in empty size columns. -Androids \"ls\" command doesn't insert size column for directories: +Android's \"ls\" command doesn't insert size column for directories: Emacs dired can't find files." (save-excursion ;; Insert missing size. @@ -1089,7 +1089,7 @@ E.g. a host name \"192.168.1.1#5555\" returns \"192.168.1.1:5555\" vec 'file-error "Could not find device %s" host))))))) (defun tramp-adb-execute-adb-command (vec &rest args) - "Returns nil on success error-output on failure." + "Return nil on success error-output on failure." (when (and (> (length (tramp-file-name-host vec)) 0) ;; The -s switch is only available for ADB device commands. (not (member (car args) '("connect" "disconnect")))) @@ -1103,7 +1103,7 @@ E.g. a host name \"192.168.1.1#5555\" returns \"192.168.1.1:5555\" (tramp-message vec 6 "%s" (buffer-string))))) (defun tramp-adb-find-test-command (vec) - "Checks, whether the ash has a builtin \"test\" command. + "Check whether the ash has a builtin \"test\" command. This happens for Android >= 4.0." (with-tramp-connection-property vec "test" (tramp-adb-send-command-and-check vec "type test"))) diff --git a/lisp/net/tramp-cache.el b/lisp/net/tramp-cache.el index 1380d0368c7..0f7e14b704a 100644 --- a/lisp/net/tramp-cache.el +++ b/lisp/net/tramp-cache.el @@ -97,7 +97,7 @@ details see the info pages." "Whether persistent cache data have been changed.") (defun tramp-get-hash-table (key) - "Returns the hash table for KEY. + "Return the hash table for KEY. If it doesn't exist yet, it is created and initialized with matching entries of `tramp-connection-properties'." (or (gethash key tramp-cache-data) diff --git a/lisp/net/tramp-compat.el b/lisp/net/tramp-compat.el index e83c1a1500b..232230f8697 100644 --- a/lisp/net/tramp-compat.el +++ b/lisp/net/tramp-compat.el @@ -75,7 +75,7 @@ Add the extension of F, if existing." #'tramp-handle-temporary-file-directory)) (defun tramp-compat-process-running-p (process-name) - "Returns t if system process PROCESS-NAME is running for `user-login-name'." + "Return t if system process PROCESS-NAME is running for `user-login-name'." (when (stringp process-name) (cond ;; GNU Emacs 22 on w32. diff --git a/lisp/net/tramp-smb.el b/lisp/net/tramp-smb.el index 2a9cf6a6d75..27c321bb9cb 100644 --- a/lisp/net/tramp-smb.el +++ b/lisp/net/tramp-smb.el @@ -1577,14 +1577,14 @@ errors for shares like \"C$/\", which are common in Microsoft Windows." ;; Internal file name functions. (defun tramp-smb-get-share (vec) - "Returns the share name of LOCALNAME." + "Return the share name of LOCALNAME." (save-match-data (let ((localname (tramp-file-name-unquote-localname vec))) (when (string-match "^/?\\([^/]+\\)/" localname) (match-string 1 localname))))) (defun tramp-smb-get-localname (vec) - "Returns the file name of LOCALNAME. + "Return the file name of LOCALNAME. If VEC has no cifs capabilities, exchange \"/\" by \"\\\\\"." (save-match-data (let ((localname (tramp-file-name-unquote-localname vec))) @@ -1717,8 +1717,8 @@ Result is a list of (LOCALNAME MODE SIZE MONTH DAY TIME YEAR)." ;; So we try to analyze backwards. (defun tramp-smb-read-file-entry (share) "Parse entry in SMB output buffer. -If SHARE is result, entries are of type dir. Otherwise, shares are listed. -Result is the list (LOCALNAME MODE SIZE MTIME)." +If SHARE is result, entries are of type dir. Otherwise, shares +are listed. Result is the list (LOCALNAME MODE SIZE MTIME)." ;; We are called from `tramp-smb-get-file-entries', which sets the ;; current buffer. (let ((line (buffer-substring (point) (point-at-eol))) @@ -1813,7 +1813,7 @@ Result is the list (LOCALNAME MODE SIZE MTIME)." (list localname mode size mtime)))) (defun tramp-smb-get-cifs-capabilities (vec) - "Check, whether the SMB server supports POSIX commands." + "Check whether the SMB server supports POSIX commands." ;; When we are not logged in yet, we return nil. The ;; connection-local property "posix" is not set explicitly; it is ;; just checked in order to let a user configure it to nil on hosts @@ -1835,7 +1835,7 @@ Result is the list (LOCALNAME MODE SIZE MTIME)." (buffer-substring (point) (point-at-eol)) nil 'omit))))))))) (defun tramp-smb-get-stat-capability (vec) - "Check, whether the SMB server supports the STAT command." + "Check whether the SMB server supports the STAT command." ;; When we are not logged in yet, we return nil. (if (and (tramp-smb-get-share vec) (process-live-p (tramp-get-connection-process vec))) diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el index 95ca6e3e2aa..37f34cf002b 100644 --- a/lisp/net/tramp.el +++ b/lisp/net/tramp.el @@ -2008,7 +2008,7 @@ letter into the file name. This function removes it." ;;; Config Manipulation Functions: (defun tramp-set-completion-function (method function-list) - "Sets the list of completion functions for METHOD. + "Set the list of completion functions for METHOD. FUNCTION-LIST is a list of entries of the form (FUNCTION FILE). The FUNCTION is intended to parse FILE according its syntax. It might be a predefined FUNCTION, or a user defined FUNCTION. @@ -2052,7 +2052,7 @@ Example: (cons method r))))) (defun tramp-get-completion-function (method) - "Returns a list of completion functions for METHOD. + "Return a list of completion functions for METHOD. For definition of that list see `tramp-set-completion-function'." (append `(;; Default settings are taken into account. @@ -2629,7 +2629,7 @@ not in completion mode." ;; "/x:y@""/[x/y@" "/x:y@z" "/[x/y@z" "/x:y@z:" "/[x/y@z]" ;;["x" "y" nil nil] ["x" "y" "z" nil] ["x" "y" "z" ""] (defun tramp-completion-dissect-file-name (name) - "Returns a list of `tramp-file-name' structures. + "Return a list of `tramp-file-name' structures. They are collected by `tramp-completion-dissect-file-name1'." (let* ((x-nil "\\|\\(\\)") (tramp-completion-ipv6-regexp @@ -2702,7 +2702,7 @@ They are collected by `tramp-completion-dissect-file-name1'." tramp-completion-file-name-structure6))))) (defun tramp-completion-dissect-file-name1 (structure name) - "Returns a `tramp-file-name' structure matching STRUCTURE. + "Return a `tramp-file-name' structure matching STRUCTURE. The structure consists of remote method, remote user, remote host and localname (filename on remote host)." (save-match-data @@ -2718,7 +2718,7 @@ remote host and localname (filename on remote host)." ;; This function returns all possible method completions, adding the ;; trailing method delimiter. (defun tramp-get-completion-methods (partial-method) - "Returns all method completions for PARTIAL-METHOD." + "Return all method completions for PARTIAL-METHOD." (mapcar (lambda (method) (and method @@ -2729,7 +2729,7 @@ remote host and localname (filename on remote host)." ;; Compares partial user and host names with possible completions. (defun tramp-get-completion-user-host (method partial-user partial-host user host) - "Returns the most expanded string for user and host name completion. + "Return the most expanded string for user and host name completion. PARTIAL-USER must match USER, PARTIAL-HOST must match HOST." (cond @@ -4228,13 +4228,13 @@ the remote host use line-endings as defined in the variable (delete-region (point) (point-max))))))) (defun tramp-get-inode (vec) - "Returns the virtual inode number. + "Return the virtual inode number. If it doesn't exist, generate a new one." (with-tramp-file-property vec (tramp-file-name-localname vec) "inode" (setq tramp-inodes (1+ tramp-inodes)))) (defun tramp-get-device (vec) - "Returns the virtual device number. + "Return the virtual device number. If it doesn't exist, generate a new one." (with-tramp-connection-property (tramp-get-connection-process vec) "device" (cons -1 (setq tramp-devices (1+ tramp-devices))))) @@ -4261,7 +4261,7 @@ If both files are local, the function returns t." (string-equal (file-remote-p file1) (file-remote-p file2))))) (defun tramp-mode-string-to-int (mode-string) - "Converts a ten-letter `drwxrwxrwx'-style mode string into mode bits." + "Convert a ten-letter `drwxrwxrwx'-style mode string into mode bits." (let* (case-fold-search (mode-chars (string-to-vector mode-string)) (owner-read (aref mode-chars 1)) @@ -4631,7 +4631,7 @@ ALIST is of the form ((FROM . TO) ...)." (defun tramp-call-process (vec program &optional infile destination display &rest args) - "Calls `call-process' on the local host. + "Call `call-process' on the local host. It always returns a return code. The Lisp error raised when PROGRAM is nil is trapped also, returning 1. Furthermore, traces are written with verbosity of 6." @@ -4665,7 +4665,7 @@ are written with verbosity of 6." (defun tramp-call-process-region (vec start end program &optional delete buffer display &rest args) - "Calls `call-process-region' on the local host. + "Call `call-process-region' on the local host. It always returns a return code. The Lisp error raised when PROGRAM is nil is trapped also, returning 1. Furthermore, traces are written with verbosity of 6." @@ -4696,7 +4696,7 @@ are written with verbosity of 6." (defun tramp-process-lines (vec program &rest args) - "Calls `process-lines' on the local host. + "Call `process-lines' on the local host. If an error occurs, it returns nil. Traces are written with verbosity of 6." (let ((default-directory (tramp-compat-temporary-file-directory)) @@ -4852,7 +4852,9 @@ Only works for Bourne-like shells." ;;; the process property `remote-pid'. (defun tramp-interrupt-process (&optional process _current-group) - "Interrupt remote process PROC." + "Interrupt remote PROCESS. +PROCESS can be a process, a buffer with an associated process, the +name of a process or buffer, or nil to default to the current buffer." ;; CURRENT-GROUP is not implemented yet. (let ((proc (cond ((processp process) process) diff --git a/lisp/net/zeroconf.el b/lisp/net/zeroconf.el index 36643a828eb..048f2e761b5 100644 --- a/lisp/net/zeroconf.el +++ b/lisp/net/zeroconf.el @@ -253,7 +253,7 @@ the service. Usually, every string is a key=value pair. The supported keys depend on the service type.") (defun zeroconf-list-service-names () - "Returns all discovered Avahi service names as list." + "Return all discovered Avahi service names as list." (let (result) (maphash (lambda (_key value) (add-to-list 'result (zeroconf-service-name value))) @@ -261,7 +261,7 @@ supported keys depend on the service type.") result)) (defun zeroconf-list-service-types () - "Returns all discovered Avahi service types as list." + "Return all discovered Avahi service types as list." (let (result) (maphash (lambda (_key value) (add-to-list 'result (zeroconf-service-type value))) @@ -269,7 +269,7 @@ supported keys depend on the service type.") result)) (defun zeroconf-list-services (type) - "Returns all discovered Avahi services for a given service type TYPE. + "Return all discovered Avahi services for a given service type TYPE. The service type is one of the returned values of `zeroconf-list-service-types'. The return value is a list \(SERVICE1 SERVICE2 ...). See `zeroconf-services-hash' for the @@ -341,19 +341,19 @@ type used when registering FUNCTION." (remhash type table)))) (defun zeroconf-get-host () - "Returns the local host name as string." + "Return the local host name as string." (dbus-call-method :system zeroconf-service-avahi zeroconf-path-avahi zeroconf-interface-avahi-server "GetHostName")) (defun zeroconf-get-domain () - "Returns the domain name as string." + "Return the domain name as string." (dbus-call-method :system zeroconf-service-avahi zeroconf-path-avahi zeroconf-interface-avahi-server "GetDomainName")) (defun zeroconf-get-host-domain () - "Returns the local host name FQDN as string." + "Return the local host name FQDN as string." (dbus-call-method :system zeroconf-service-avahi zeroconf-path-avahi zeroconf-interface-avahi-server "GetHostNameFqdn")) diff --git a/lisp/nxml/rng-xsd.el b/lisp/nxml/rng-xsd.el index 5aa850f5895..c2c90cc8a18 100644 --- a/lisp/nxml/rng-xsd.el +++ b/lisp/nxml/rng-xsd.el @@ -46,7 +46,7 @@ ;;;###autoload (defun rng-xsd-compile (name params) - "Provides W3C XML Schema as a RELAX NG datatypes library. + "Provide W3C XML Schema as a RELAX NG datatypes library. NAME is a symbol giving the local name of the datatype. PARAMS is a list of pairs (PARAM-NAME . PARAM-VALUE) where PARAM-NAME is a symbol giving the name of the parameter and PARAM-VALUE is a string giving @@ -366,7 +366,7 @@ trailing digits. For example, -0021.0430 would be represented by [-1 string)) (defun rng-xsd-make-date-time-regexp (template) - "Returns a regular expression matching a ISO 8601 date/time. + "Return a regular expression matching a ISO 8601 date/time. The template is a string with Y standing for years field, M standing for months, D standing for day of month, T standing for a literal T, t standing for time and - standing for a literal hyphen. A time zone is @@ -436,7 +436,7 @@ sign, time zone hours, time zone minutes." v)) (defun rng-xsd-convert-date-time (string regexp) - "Converts an XML Schema date/time to a list. + "Convert an XML Schema date/time to a list. Returns nil if invalid. REGEXP is a regexp for parsing the date time as returned by `rng-xsd-make-date-time-regexp'. The list has 4 members \(HAS-TIME-ZONE DAY SECOND SECOND-FRACTION), where HAS-TIME-ZONE is t diff --git a/lisp/obsolete/erc-hecomplete.el b/lisp/obsolete/erc-hecomplete.el index 43df67d5e04..9f4144919ee 100644 --- a/lisp/obsolete/erc-hecomplete.el +++ b/lisp/obsolete/erc-hecomplete.el @@ -51,7 +51,7 @@ This function is obsolete, use `erc-pcomplete' instead." (hippie-expand nil))) (defgroup erc-hecomplete nil - "Nick completion. It is recommended to use erc-pcomplete instead." + "Nick completion. It is recommended to use `erc-pcomplete' instead." :group 'erc) (defcustom erc-nick-completion 'all @@ -99,7 +99,7 @@ add this string when a unique expansion was found." :type 'string) (defun erc-command-list () - "Returns a list of strings of the defined user commands." + "Return a list of strings of the defined user commands." (let ((case-fold-search nil)) (mapcar (lambda (x) (concat "/" (downcase (substring (symbol-name x) 8)))) @@ -208,7 +208,7 @@ Window configurations are stored in (equal point (point)))) (defun erc-complete-at-prompt () - "Returns t if point is directly after `erc-prompt' when doing completion." + "Return t if point is directly after `erc-prompt' when doing completion." (erc-at-beginning-of-line-p (he-dabbrev-beg))) (provide 'erc-hecomplete) diff --git a/lisp/org/ChangeLog.1 b/lisp/org/ChangeLog.1 index 2bb15863e7f..8f7334a330a 100644 --- a/lisp/org/ChangeLog.1 +++ b/lisp/org/ChangeLog.1 @@ -11557,7 +11557,7 @@ 2012-04-01 Jambunathan K * org-footnote.el (org-footnote-normalize): Force a paragraph - break after the last footnote definition. This is an an implicit + break after the last footnote definition. This is an implicit assumption made by the org-lparse.el library. With this change, footnote definitions can reliably be exported with ODT backend. See https://lists.gnu.org/r/emacs-orgmode/2012-02/msg01013.html. @@ -11912,7 +11912,7 @@ * org-footnote.el (org-footnote-normalize): Ensure footnote definition will be inserted at the end of the section - corresponding to to its first reference. + corresponding to its first reference. 2012-04-01 Nicolas Goaziou @@ -17453,7 +17453,7 @@ 2011-07-28 Nicolas Goaziou * org-list.el (org-list-struct, org-in-item-p): Don't assume end of - blocks or drawers necessarily start somewhere. It it isn't the + blocks or drawers necessarily start somewhere. If it isn't the case, treat them as normal text. 2011-07-28 Eric Schulte diff --git a/lisp/org/ob-core.el b/lisp/org/ob-core.el index 8e9e3edb1c8..9e78876787a 100644 --- a/lisp/org/ob-core.el +++ b/lisp/org/ob-core.el @@ -532,7 +532,7 @@ to raise errors for all languages.") "Hook for functions to be called after `org-babel-execute-src-block'") (defun org-babel-named-src-block-regexp-for-name (&optional name) - "This generates a regexp used to match a src block named NAME. + "Generate a regexp used to match a src block named NAME. If NAME is nil, match any name. Matched name is then put in match group 9. Other match groups are defined in `org-babel-src-block-regexp'." @@ -543,7 +543,7 @@ match group 9. Other match groups are defined in (substring org-babel-src-block-regexp 1))) (defun org-babel-named-data-regexp-for-name (name) - "This generates a regexp used to match data named NAME." + "Generate a regexp used to match data named NAME." (concat org-babel-name-regexp (regexp-quote name) "[ \t]*$")) (defun org-babel--normalize-body (datum) @@ -1774,7 +1774,7 @@ to `org-babel-named-src-block-regexp'." (ignore-errors (org-next-block 1 nil regexp)))))) (defun org-babel-src-block-names (&optional file) - "Returns the names of source blocks in FILE or the current buffer." + "Return the names of source blocks in FILE or the current buffer." (with-current-buffer (if file (find-file-noselect file) (current-buffer)) (org-with-point-at 1 (let ((regexp "^[ \t]*#\\+begin_src ") @@ -1819,7 +1819,7 @@ buffer or nil if no such result exists." (throw :found (line-beginning-position))))))))) (defun org-babel-result-names (&optional file) - "Returns the names of results in FILE or the current buffer." + "Return the names of results in FILE or the current buffer." (save-excursion (when file (find-file file)) (goto-char (point-min)) (let ((case-fold-search t) names) diff --git a/lisp/org/ob-scheme.el b/lisp/org/ob-scheme.el index af5c7f26d6f..635b3aa6003 100644 --- a/lisp/org/ob-scheme.el +++ b/lisp/org/ob-scheme.el @@ -102,7 +102,7 @@ (puthash session-name buffer org-babel-scheme-repl-map)) (defun org-babel-scheme-get-buffer-impl (buffer) - "Returns the scheme implementation geiser associates with the buffer." + "Return the scheme implementation geiser associates with the buffer." (with-current-buffer (set-buffer buffer) geiser-impl--implementation)) diff --git a/lisp/org/ob-shell.el b/lisp/org/ob-shell.el index 8e080c6977f..548edce5793 100644 --- a/lisp/org/ob-shell.el +++ b/lisp/org/ob-shell.el @@ -111,12 +111,12 @@ This function is called by `org-babel-execute-src-block'." ;;; Helper functions (defun org-babel--variable-assignments:sh-generic (varname values &optional sep hline) - "Returns a list of statements declaring the values as a generic variable." + "Return a list of statements declaring the values as a generic variable." (format "%s=%s" varname (org-babel-sh-var-to-sh values sep hline))) (defun org-babel--variable-assignments:bash_array (varname values &optional sep hline) - "Returns a list of statements declaring the values as a bash array." + "Return a list of statements declaring the values as a bash array." (format "unset %s\ndeclare -a %s=( %s )" varname varname (mapconcat @@ -126,7 +126,7 @@ This function is called by `org-babel-execute-src-block'." (defun org-babel--variable-assignments:bash_assoc (varname values &optional sep hline) - "Returns a list of statements declaring the values as bash associative array." + "Return a list of statements declaring the values as bash associative array." (format "unset %s\ndeclare -A %s\n%s" varname varname (mapconcat @@ -139,7 +139,7 @@ This function is called by `org-babel-execute-src-block'." "\n"))) (defun org-babel--variable-assignments:bash (varname values &optional sep hline) - "Represents the parameters as useful Bash shell variables." + "Represent the parameters as useful Bash shell variables." (pcase values (`((,_ ,_ . ,_) . ,_) ;two-dimensional array (org-babel--variable-assignments:bash_assoc varname values sep hline)) diff --git a/lisp/org/org-clock.el b/lisp/org/org-clock.el index 4667890b421..9046661b266 100644 --- a/lisp/org/org-clock.el +++ b/lisp/org/org-clock.el @@ -2055,7 +2055,7 @@ in the buffer and update it." (org-update-dblock)) (defun org-day-of-week (day month year) - "Returns the day of the week as an integer." + "Return the day of the week as an integer." (nth 6 (decode-time (date-to-time diff --git a/lisp/org/ox.el b/lisp/org/ox.el index aa04676db8d..0ae1e45f036 100644 --- a/lisp/org/ox.el +++ b/lisp/org/ox.el @@ -4711,7 +4711,7 @@ code." ;;;; For Tables ;; -;; `org-export-table-has-special-column-p' and and +;; `org-export-table-has-special-column-p' and ;; `org-export-table-row-is-special-p' are predicates used to look for ;; meta-information about the table structure. ;; diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el index 5d4cf96d4c4..e9be1990ddc 100644 --- a/lisp/progmodes/cperl-mode.el +++ b/lisp/progmodes/cperl-mode.el @@ -1324,7 +1324,7 @@ the last)." (defvar cperl-sub-regexp (regexp-opt cperl-sub-keywords)) (defun cperl-char-ends-sub-keyword-p (char) - "Return T if CHAR is the last character of a perl sub keyword." + "Return t if CHAR is the last character of a perl sub keyword." (cl-loop for keyword in cperl-sub-keywords when (eq char (aref keyword (1- (length keyword)))) return t)) diff --git a/lisp/progmodes/gud.el b/lisp/progmodes/gud.el index 396141b3884..9a5a1ad217b 100644 --- a/lisp/progmodes/gud.el +++ b/lisp/progmodes/gud.el @@ -3009,7 +3009,7 @@ Obeying it means displaying in another window the specified file and line." ;; Rich Schaefer Schlumberger, Austin, Tx. (defun gud-find-c-expr () - "Returns the expr that surrounds point." + "Return the expr that surrounds point." (interactive) (save-excursion (let ((p (point)) @@ -3034,7 +3034,7 @@ Obeying it means displaying in another window the specified file and line." (buffer-substring (car expr) (cdr expr))))) (defun gud-innermost-expr () - "Returns the smallest expr that point is in; move point to beginning of it. + "Return the smallest expr that point is in; move point to beginning of it. The expr is represented as a cons cell, where the car specifies the point in the current buffer that marks the beginning of the expr and the cdr specifies the character after the end of the expr." @@ -3066,7 +3066,7 @@ the character after the end of the expr." (error t))) (defun gud-prev-expr () - "Returns the previous expr, point is set to beginning of that expr. + "Return the previous expr, point is set to beginning of that expr. The expr is represented as a cons cell, where the car specifies the point in the current buffer that marks the beginning of the expr and the cdr specifies the character after the end of the expr." @@ -3079,7 +3079,7 @@ the character after the end of the expr." (cons begin end))) (defun gud-next-expr () - "Returns the following expr, point is set to beginning of that expr. + "Return the following expr, point is set to beginning of that expr. The expr is represented as a cons cell, where the car specifies the point in the current buffer that marks the beginning of the expr and the cdr specifies the character after the end of the expr." diff --git a/lisp/progmodes/inf-lisp.el b/lisp/progmodes/inf-lisp.el index dafb89a5b65..7d5ec06bf51 100644 --- a/lisp/progmodes/inf-lisp.el +++ b/lisp/progmodes/inf-lisp.el @@ -287,7 +287,7 @@ to continue it." (buffer-substring (point) end)))) (defun lisp-input-filter (str) - "t if STR does not match `inferior-lisp-filter-regexp'." + "Return t if STR does not match `inferior-lisp-filter-regexp'." (not (string-match inferior-lisp-filter-regexp str))) ;;;###autoload @@ -564,7 +564,7 @@ Used by these commands to determine defaults." ;;; Adapted from function-called-at-point in help.el. (defun lisp-fn-called-at-pt () - "Returns the name of the function called in the current call. + "Return the name of the function called in the current call. The value is nil if it can't find one." (condition-case nil (save-excursion diff --git a/lisp/progmodes/xref.el b/lisp/progmodes/xref.el index eef2ca643f6..702de894528 100644 --- a/lisp/progmodes/xref.el +++ b/lisp/progmodes/xref.el @@ -268,8 +268,8 @@ find a search tool; by default, this uses \"find | grep\" in the (cl-defgeneric xref-backend-identifier-at-point (_backend) "Return the relevant identifier at point. -The return value must be a string or nil. nil means no -identifier at point found. +The return value must be a string, or nil meaning no identifier +at point found. If it's hard to determine the identifier precisely (e.g., because it's a method call on unknown type), the implementation can @@ -280,7 +280,7 @@ recognize and then delegate the work to an external process." (and thing (substring-no-properties thing)))) (cl-defgeneric xref-backend-identifier-completion-table (backend) - "Returns the completion table for identifiers.") + "Return the completion table for identifiers.") ;;; misc utilities diff --git a/lisp/registry.el b/lisp/registry.el index 8e2005b0a5a..f65e60caa35 100644 --- a/lisp/registry.el +++ b/lisp/registry.el @@ -155,7 +155,7 @@ (setq tracker (make-hash-table :size 100 :rehash-size 2.0))))) (cl-defmethod registry-lookup ((db registry-db) keys) - "Search for KEYS in the registry-db THIS. + "Search for KEYS in the registry-db DB. Returns an alist of the key followed by the entry in a list, not a cons cell." (let ((data (oref db data))) (delq nil @@ -166,7 +166,7 @@ Returns an alist of the key followed by the entry in a list, not a cons cell." keys)))) (cl-defmethod registry-lookup-breaks-before-lexbind ((db registry-db) keys) - "Search for KEYS in the registry-db THIS. + "Search for KEYS in the registry-db DB. Returns an alist of the key followed by the entry in a list, not a cons cell." (let ((data (oref db data))) (delq nil @@ -176,7 +176,7 @@ Returns an alist of the key followed by the entry in a list, not a cons cell." (cl-defmethod registry-lookup-secondary ((db registry-db) tracksym &optional create) - "Search for TRACKSYM in the registry-db THIS. + "Search for TRACKSYM in the registry-db DB. When CREATE is not nil, create the secondary index hash table if needed." (let ((h (gethash tracksym (oref db tracker)))) (if h @@ -189,7 +189,7 @@ When CREATE is not nil, create the secondary index hash table if needed." (cl-defmethod registry-lookup-secondary-value ((db registry-db) tracksym val &optional set) - "Search for TRACKSYM with value VAL in the registry-db THIS. + "Search for TRACKSYM with value VAL in the registry-db DB. When SET is not nil, set it for VAL (use t for an empty list)." ;; either we're asked for creation or there should be an existing index (when (or set (registry-lookup-secondary db tracksym)) @@ -220,7 +220,7 @@ When SET is not nil, set it for VAL (use t for an empty list)." (registry--match mode entry (cdr-safe check-list)))))) (cl-defmethod registry-search ((db registry-db) &rest spec) - "Search for SPEC across the registry-db THIS. + "Search for SPEC across the registry-db DB. For example calling with `:member \\='(a 1 2)' will match entry \((a 3 1)). Calling with `:all t' (any non-nil value) will match all. Calling with `:regex \\='(a \"h.llo\")' will match entry \(a \"hullo\" \"bye\"). @@ -241,7 +241,7 @@ The test order is to check :all first, then :member, then :regex." collect k)))) (cl-defmethod registry-delete ((db registry-db) keys assert &rest spec) - "Delete KEYS from the registry-db THIS. + "Delete KEYS from the registry-db DB. If KEYS is nil, use SPEC to do a search. Updates the secondary ('tracked') indices as well. With assert non-nil, errors out if the key does not exist already." @@ -273,17 +273,17 @@ With assert non-nil, errors out if the key does not exist already." keys)) (cl-defmethod registry-size ((db registry-db)) - "Returns the size of the registry-db object THIS. + "Return the size of the registry-db object DB. This is the key count of the `data' slot." (hash-table-count (oref db data))) (cl-defmethod registry-full ((db registry-db)) - "Checks if registry-db THIS is full." + "Check if registry-db DB is full." (>= (registry-size db) (oref db max-size))) (cl-defmethod registry-insert ((db registry-db) key entry) - "Insert ENTRY under KEY into the registry-db THIS. + "Insert ENTRY under KEY into the registry-db DB. Updates the secondary ('tracked') indices as well. Errors out if the key exists already." (cl-assert (not (gethash key (oref db data))) nil @@ -304,7 +304,7 @@ Errors out if the key exists already." entry) (cl-defmethod registry-reindex ((db registry-db)) - "Rebuild the secondary indices of registry-db THIS." + "Rebuild the secondary indices of registry-db DB." (let ((count 0) (expected (* (length (oref db tracked)) (registry-size db)))) (dolist (tr (oref db tracked)) @@ -323,7 +323,7 @@ Errors out if the key exists already." (oref db data)))))) (cl-defmethod registry-prune ((db registry-db) &optional sortfunc) - "Prunes the registry-db object DB. + "Prune the registry-db object DB. Attempts to prune the number of entries down to \(* :max-size :prune-factor) less than the max-size limit, so @@ -351,7 +351,7 @@ Returns the number of deleted entries." (cl-defmethod registry-collect-prune-candidates ((db registry-db) limit sortfunc) - "Collects pruning candidates from the registry-db object DB. + "Collect pruning candidates from the registry-db object DB. Proposes only entries without the :precious keys, and attempts to return LIMIT such candidates. If SORTFUNC is provided, sort diff --git a/lisp/so-long.el b/lisp/so-long.el index 59c719a4ee5..e2467e4f0f3 100644 --- a/lisp/so-long.el +++ b/lisp/so-long.el @@ -654,7 +654,7 @@ an example." ;; `provided-mode-derived-p' was added in 26.1 (unless (fboundp 'provided-mode-derived-p) (defun provided-mode-derived-p (mode &rest modes) - "Non-nil if MODE is derived from one of MODES. + "Return non-nil if MODE is derived from one of MODES. Uses the `derived-mode-parent' property of the symbol to trace backwards. If you just want to check `major-mode', use `derived-mode-p'." (while (and (not (memq mode modes)) @@ -982,7 +982,7 @@ serves the same purpose.") (put 'so-long-mode-line-info 'risky-local-variable t) (defun so-long-mode-line-info () - "Returns the mode line construct for variable `so-long-mode-line-info'." + "Return the mode line construct for variable `so-long-mode-line-info'." (let ((map (make-sparse-keymap))) (define-key map (kbd " ") `(menu-item "" nil @@ -1189,7 +1189,7 @@ values), despite potential performance issues, type \\[so-long-revert]. Use \\[so-long-commentary] for more information. -Use \\[so-long-customize] to configure the behaviour." +Use \\[so-long-customize] to configure the behavior." ;; Housekeeping. `so-long-mode' might be invoked directly rather than via ;; `so-long', so replicate the necessary behaviours. We could use this same ;; test in `so-long-after-change-major-mode' to run `so-long-hook', but that's @@ -1371,7 +1371,7 @@ This is a `so-long-file-local-mode-function' option." (defun so-long--check-header-modes () ;; See also "Files with a file-local 'mode'" in the Commentary. - "Handles the header-comments processing in `set-auto-mode'. + "Handle the header-comments processing in `set-auto-mode'. `set-auto-mode' has some special-case code to handle the 'mode' pseudo-variable when set in the header comment. This runs outside of `hack-local-variables' diff --git a/lisp/subr.el b/lisp/subr.el index ada078aed9b..3ba4d2bd4e5 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -639,7 +639,7 @@ copy." (nbutlast (copy-sequence list) n))) (defun nbutlast (list &optional n) - "Modifies LIST to remove the last N elements. + "Modify LIST to remove the last N elements. If N is omitted or nil, remove the last element." (let ((m (length list))) (or n (setq n 1)) @@ -2341,7 +2341,7 @@ Signal an error if the program returns with a non-zero exit status." (nreverse lines))))) (defun process-live-p (process) - "Returns non-nil if PROCESS is alive. + "Return non-nil if PROCESS is alive. A process is considered alive if its status is `run', `open', `listen', `connect' or `stop'. Value is nil if PROCESS is not a process." diff --git a/lisp/tab-bar.el b/lisp/tab-bar.el index 52d06872312..800b65091a0 100644 --- a/lisp/tab-bar.el +++ b/lisp/tab-bar.el @@ -727,7 +727,7 @@ In this list of window configurations you can delete or select them. Type ? after invocation to get help on commands available. Type q to remove the list of window configurations from the display. -The first column shows `D' for for a window configuration you have +The first column shows `D' for a window configuration you have marked for deletion." (interactive) (let ((dir default-directory) diff --git a/lisp/textmodes/table.el b/lisp/textmodes/table.el index 94dcaea0ba6..839df035d27 100644 --- a/lisp/textmodes/table.el +++ b/lisp/textmodes/table.el @@ -4950,7 +4950,7 @@ When optional LOCATION is provided the test is performed at that location." (equal cell-beg (progn (goto-char end) (table--probe-cell)))))))) (defun table--at-cell-p (position &optional object at-column) - "Returns non-nil if POSITION has table-cell property in OBJECT. + "Return non-nil if POSITION has table-cell property in OBJECT. OBJECT is optional and defaults to the current buffer. If POSITION is at the end of OBJECT, the value is nil." (if (and at-column (stringp object)) @@ -5042,7 +5042,7 @@ Focus only on the corner pattern. Further cell validity check is required." (get-text-property (point) 'table-cell))) (defun table--probe-cell (&optional abort-on-error) - "Probes a table cell around the point. + "Probe a table cell around the point. Searches for the left upper corner and the right bottom corner of a table cell which contains the current point location. @@ -5198,11 +5198,11 @@ instead of the current buffer and returns the OBJECT." (get-text-property (1- (cdr cell)) property))) (defun table--get-cell-justify-property (cell) - "Get cell's justify property." + "Get CELL's justify property." (table--get-property cell 'table-justify)) (defun table--get-cell-valign-property (cell) - "Get cell's vertical alignment property." + "Get CELL's vertical alignment property." (table--get-property cell 'table-valign)) (defun table--put-property (cell property value) @@ -5213,11 +5213,11 @@ instead of the current buffer and returns the OBJECT." (put-text-property (1- end) end property value))) (defun table--put-cell-justify-property (cell justify) - "Put cell's justify property." + "Put CELL's JUSTIFY property." (table--put-property cell 'table-justify justify)) (defun table--put-cell-valign-property (cell valign) - "Put cell's vertical alignment property." + "Put CELL's vertical alignment property." (table--put-property cell 'table-valign valign)) (defun table--point-entered/left-cell-function (_window _oldpos dir) diff --git a/src/sound.c b/src/sound.c index 44d4cbc6d56..60bf530564f 100644 --- a/src/sound.c +++ b/src/sound.c @@ -1115,7 +1115,7 @@ alsa_write (struct sound_device *sd, const char *buffer, ptrdiff_t nbytes) { struct alsa_params *p = (struct alsa_params *) sd->data; - /* The the third parameter to snd_pcm_writei is frames, not bytes. */ + /* The third parameter to snd_pcm_writei is frames, not bytes. */ int fact = snd_pcm_format_size (sd->format, 1) * sd->channels; ptrdiff_t nwritten = 0; int err; diff --git a/src/xdisp.c b/src/xdisp.c index 8cbda08efc5..987c760c743 100644 --- a/src/xdisp.c +++ b/src/xdisp.c @@ -21697,7 +21697,7 @@ extend_face_to_end_of_line (struct it *it) memset (&it->position, 0, sizeof it->position); /* Only generate a stretch glyph if there is distance - between current_x and and the indicator position. */ + between current_x and the indicator position. */ if (stretch_width > 0) { int stretch_ascent = (((it->ascent + it->descent)