[nongnu] scratch/evil 891af30ef2 2/8: Better follow conventions for use of ' in docstrings

[Stefan Monnier]

branch: scratch/evil
commit 891af30ef2668d7e5bcdb4f9b46eb1ba7d4581a3
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    Better follow conventions for use of ' in docstrings
    
    Also try and make the docstring fit within 80 columns.
    This fixes some incorrect uses and eliminates some warnings.
---
 evil-commands.el |  9 ++++-----
 evil-common.el   | 30 +++++++++++++++---------------
 evil-core.el     | 42 +++++++++++++++++++++---------------------
 evil-ex.el       | 22 +++++++++++-----------
 evil-macros.el   |  2 +-
 evil-repeat.el   |  6 ++++--
 evil-search.el   | 22 +++++++++++-----------
 evil-vars.el     |  6 +++---
 8 files changed, 70 insertions(+), 69 deletions(-)

diff --git a/evil-commands.el b/evil-commands.el
index 68e9663e4b..abac1aea57 100644
--- a/evil-commands.el
+++ b/evil-commands.el
@@ -307,8 +307,7 @@ If called after a change operator, i.e. cw or cW,
 then both behave like ce or cE.
 
 If point is at the end of the buffer and cannot be moved signal
-'end-of-buffer is raised.
-"
+`end-of-buffer' is raised."
   :type exclusive
   (let ((thing (if bigword 'evil-WORD 'evil-word))
         (orig (point))
@@ -591,7 +590,7 @@ and jump to the corresponding one."
   (evil-next-flyspell-error (- (or count 1))))
 
 (evil-define-motion evil-previous-open-paren (count)
-  "Go to [count] previous unmatched '('."
+  "Go to [count] previous unmatched \"(\"."
   :type exclusive
   (evil-up-paren ?\( ?\) (- (or count 1))))
 
@@ -3079,7 +3078,7 @@ Calls `evil-complete-previous-line-func'."
 
 (defun evil-repeat-search (flag)
   "Called to record a search command.
-FLAG is either 'pre or 'post if the function is called before resp.
+FLAG is either `pre' or `post' if the function is called before resp.
 after executing the command."
   (cond
    ((and (evil-operator-state-p) (eq flag 'pre))
@@ -3890,7 +3889,7 @@ Change to `%s'? "
 
 (defun evil-repeat-ex-search (flag)
   "Called to record a search command.
-FLAG is either 'pre or 'post if the function is called before
+FLAG is either `pre' or `post' if the function is called before
 resp.  after executing the command."
   (cond
    ((and (evil-operator-state-p) (eq flag 'pre))
diff --git a/evil-common.el b/evil-common.el
index 49a5456d9c..3e4ce01519 100644
--- a/evil-common.el
+++ b/evil-common.el
@@ -123,7 +123,7 @@ otherwise add at the end of the list."
   "Delete by side-effect all items satisfying PREDICATE in LIST.
 Stop when reaching POINTER.  If the first item satisfies PREDICATE,
 there is no way to remove it by side-effect; therefore, write
-\(setq foo (evil-filter-list 'predicate foo)) to be sure of
+\(setq foo (evil-filter-list #\\='predicate foo)) to be sure of
 changing the value of `foo'."
   (let ((tail list) elt head)
     (while (and tail (not (eq tail pointer)))
@@ -1086,9 +1086,9 @@ immediately quits.
 
 (defun evil-signal-at-bob-or-eob (&optional count)
   "Signal error if `point' is at boundaries.
-If `point' is at bob and COUNT is negative this function signal
-`beginning-of-buffer'. If `point' is at eob and COUNT is positive
-this function singal `end-of-buffer'. This function should be used
+If `point' is at bob and COUNT is negative this function signals
+`beginning-of-buffer'.  If `point' is at eob and COUNT is positive
+this function signals `end-of-buffer'.  This function should be used
 in motions. COUNT defaults to 1."
   (setq count (or count 1))
   (cond
@@ -2745,7 +2745,7 @@ list of command properties as passed to 
`evil-define-command'."
 
 (defun evil-set-type (object type)
   "Set the type of OBJECT to TYPE.
-For example, (evil-set-type 'next-line 'line)
+For example, (evil-set-type \\='next-line \\='line)
 will make `line' the type of the `next-line' command."
   (cond
    ((overlayp object)
@@ -3087,10 +3087,10 @@ linewise, otherwise it is character wise."
 OP and CL are pairs of buffer positions for the opening and
 closing delimiter of a range. SELECTION-TYPE is the desired type
 of selection.  It is a symbol that determines which parts of the
-block are selected.  If it is 'inclusive or t the returned range
-is \(cons (car OP) (cdr CL)). If it is 'exclusive or nil the
+block are selected.  If it is `inclusive' or t the returned range
+is \(cons (car OP) (cdr CL)). If it is `exclusive' or nil the
 returned range is (cons (cdr OP) (car CL)).  If it is
-'exclusive-line the returned range will skip whitespace at the
+`exclusive-line' the returned range will skip whitespace at the
 end of the line of OP and at the beginning of the line of CL."
   (cond
    ((memq selection-type '(inclusive t)) (cons (car op) (cdr cl)))
@@ -3124,9 +3124,9 @@ delimited object must be given by THING-up function (see
 `evil-up-block').
 
 SELECTION-TYPE is symbol that determines which parts of the block
-are selected.  If it is 'inclusive or t OPEN and CLOSE are
-included in the range. If it is 'exclusive or nil the delimiters
-are not contained. If it is 'exclusive-line the delimiters are
+are selected.  If it is `inclusive' or t OPEN and CLOSE are
+included in the range. If it is `exclusive' or nil the delimiters
+are not contained. If it is `exclusive-line' the delimiters are
 not included as well as adjacent whitespace until the beginning
 of the next line or the end of the previous line. If the
 resulting selection consists of complete lines only and visual
@@ -3307,7 +3307,7 @@ is ignored."
 
 (defun evil-select-quote-thing (thing beg end _type count &optional inclusive)
   "Selection THING as if it described a quoted object.
-THING is typically either 'evil-quote or 'evil-chars. This
+THING is typically either `evil-quote' or `evil-chars'. This
 function is called from `evil-select-quote'."
   (save-excursion
     (let* ((count (or count 1))
@@ -3745,8 +3745,8 @@ Depending on the value of MAGIC the following characters 
are
 considered magic.
   t             [][{}*+?.&~$^
   nil           [][{}*+?$^
-  'very-magic   not 0-9A-Za-z_
-  'very-nomagic empty."
+  `very-magic'   not 0-9A-Za-z_
+  `very-nomagic' empty."
   (cond
    ((eq magic t) "[][}{*+?.&~$^]")
    ((eq magic 'very-magic) "[^0-9A-Za-z_]")
@@ -3852,7 +3852,7 @@ replacement text first."
 (defun evil-justify-lines (beg end justify position)
   "Justify all lines in a range.
 BEG and END specify the range of those lines to be
-justified. JUSTIFY is either 'left, 'right or 'center according
+justified. JUSTIFY is either `left', `right' or `center' according
 to the justification type. POSITION is the maximal text width for
 right and center justification or the column at which the lines
 should be left-aligned for left justification."
diff --git a/evil-core.el b/evil-core.el
index fae8bcdff0..546288e14c 100644
--- a/evil-core.el
+++ b/evil-core.el
@@ -559,7 +559,7 @@ Enable with positive ARG and disable with negative ARG.
 
 When enabled, `evil-esc-mode' modifies the entry of \\e in
 `input-decode-map'. If such an event arrives, it is translated to
-a plain 'escape event if no further event occurs within
+a plain `escape' event if no further event occurs within
 `evil-esc-delay' seconds. Otherwise no translation happens and
 the ESC prefix map (i.e. the map originally bound to \\e in
 `input-decode-map`) is returned."
@@ -602,17 +602,17 @@ the ESC prefix map (i.e. the map originally bound to \\e 
in
             (set-terminal-parameter term 'evil-esc-map nil)))))))
 
 (defun evil-esc (map)
-  "Translate \\e to 'escape if no further event arrives.
-This function is used to translate a \\e event either to 'escape
+  "Translate \\e to `escape' if no further event arrives.
+This function is used to translate a \\e event either to `escape'
 or to the standard ESC prefix translation map. If \\e arrives,
 this function waits for `evil-esc-delay' seconds for another
 event. If no other event arrives, the event is translated to
-'escape, otherwise it is translated to the standard ESC prefix
+`escape', otherwise it is translated to the standard ESC prefix
 map stored in `input-decode-map'. If `evil-inhibit-esc' is
 non-nil or if evil is in emacs state, the event is always
 translated to the ESC prefix.
 
-The translation to 'escape happens only if the current command
+The translation to `escape' happens only if the current command
 has indeed been triggered by \\e. In other words, this will only
 happen when the keymap is accessed from `read-key-sequence'. In
 particular, if it is access from `define-key' the returned
@@ -952,21 +952,21 @@ these. Omitting a state by using `nil' corresponds to a 
standard
 Emacs binding using `define-key'. The remaining arguments are
 like those of `define-key'. For example:
 
-    (evil-define-key 'normal foo-map \"a\" 'bar)
+    (evil-define-key \\='normal foo-map \"a\" \\='bar)
 
 This creates a binding from `a' to `bar' in normal state, which
 is active whenever `foo-map' is active. Using nil for the state,
 the following lead to identical bindings:
 
-    (evil-define-key nil foo-map \"a\" 'bar)
-    (define-key foo-map \"a\" 'bar)
+    (evil-define-key nil foo-map \"a\" \\='bar)
+    (define-key foo-map \"a\" \\='bar)
 
 It is possible to specify multiple states and/or bindings at
 once:
 
-    (evil-define-key '(normal visual) foo-map
-      \"a\" 'bar
-      \"b\" 'foo)
+    (evil-define-key \\='(normal visual) foo-map
+      \"a\" \\='bar
+      \"b\" \\='foo)
 
 If `foo-map' has not been initialized yet, this macro adds an
 entry to `after-load-functions', delaying execution as necessary.
@@ -975,8 +975,8 @@ KEYMAP may also be a quoted symbol. If the symbol is 
`global', the
 global evil keymap corresponding to the state(s) is used, meaning
 the following lead to identical bindings:
 
-    (evil-define-key 'normal 'global \"a\" 'bar)
-    (evil-global-set-key 'normal \"a\" 'bar)
+    (evil-define-key \\='normal \\='global \"a\" \\='bar)
+    (evil-global-set-key \\='normal \"a\" \\='bar)
 
 The symbol `local' may also be used, which corresponds to using
 `evil-local-set-key'. If a quoted symbol is used that is not
@@ -1008,30 +1008,30 @@ state by using nil corresponds to a standard Emacs 
binding using
 `define-key' The remaining arguments are like those of
 `define-key'. For example:
 
-    (evil-define-key* 'normal foo-map \"a\" 'bar)
+    (evil-define-key* \\='normal foo-map \"a\" \\='bar)
 
 This creates a binding from \"a\" to bar in Normal state, which
 is active whenever foo-map is active. Using nil for the state,
 the following are equivalent:
 
-    (evil-define-key* nil foo-map \"a\" 'bar)
+    (evil-define-key* nil foo-map \"a\" \\='bar)
 
-    (define-key foo-map \"a\" 'bar)
+    (define-key foo-map \"a\" \\='bar)
 
  It is possible to specify multiple states and/or bindings at
  once:
 
-    (evil-define-key* '(normal visual) foo-map
-      \"a\" 'bar
-      \"b\" 'foo)
+    (evil-define-key* \\='(normal visual) foo-map
+      \"a\" \\='bar
+      \"b\" \\='foo)
 
 KEYMAP may also be a quoted symbol. If the symbol is global, the
 global evil keymap corresponding to the state(s) is used, meaning
 the following are equivalent:
 
-    (evil-define-key* 'normal 'global \"a\" 'bar)
+    (evil-define-key* \\='normal \\='global \"a\" \\='bar)
 
-    (evil-global-set-key 'normal \"a\" 'bar)
+    (evil-global-set-key \\='normal \"a\" \\='bar)
 
 The symbol local may also be used, which corresponds to using
 `evil-local-set-key'.
diff --git a/evil-ex.el b/evil-ex.el
index d1e3f42663..05f66b993a 100644
--- a/evil-ex.el
+++ b/evil-ex.el
@@ -175,20 +175,20 @@ Thus, a simple grammar may look like:
 All input-consuming rules have a value. A regular expression evaluates
 to the text matched, while a list evaluates to a list of values.
 The value of a list may be overridden with a semantic action, which is
-specified with a #'-quoted expression at the end:
+specified with a #\\='-quoted expression at the end:
 
-    (X Y #'foo)
+    (X Y #\\='foo)
 
 The value of this rule is the result of calling foo with the values
 of X and Y as arguments. Alternatively, the function call may be
 specified explicitly:
 
-    (X Y #'(foo $1 $2))
+    (X Y #\\='(foo $1 $2))
 
 Here, $1 refers to X and $2 refers to Y. $0 refers to the whole list.
 Dollar expressions can also be used directly:
 
-    (X Y #'$1)
+    (X Y #\\='$1)
 
 This matches X followed by Y, but ignores the value of Y;
 the value of the list is the same as the value of X.
@@ -694,14 +694,14 @@ keywords and function:
   Function to be called when the type of the current argument
   changes or when the content of this argument changes. This
   function should take one obligatory argument FLAG followed by
-  an optional argument ARG. FLAG is one of three symbol 'start,
-  'stop or 'update. When the argument type is recognized for the
-  first time and this handler is started the FLAG is 'start. If
+  an optional argument ARG. FLAG is one of three symbol `start',
+  `stop' or `update'. When the argument type is recognized for the
+  first time and this handler is started the FLAG is `start'. If
   the argument type changes to something else or ex state
-  finished the handler FLAG is 'stop. If the content of the
-  argument has changed FLAG is 'update. If FLAG is either 'start
-  or 'update then ARG is the current value of this argument. If
-  FLAG is 'stop then arg is nil."
+  finished the handler FLAG is `stop'. If the content of the
+  argument has changed FLAG is `update'. If FLAG is either `start'
+  or `update' then ARG is the current value of this argument. If
+  FLAG is `stop' then arg is nil."
   (declare (indent defun)
            (doc-string 2)
            (debug (&define name
diff --git a/evil-macros.el b/evil-macros.el
index 1ba6e51c18..a164fe6981 100644
--- a/evil-macros.el
+++ b/evil-macros.el
@@ -166,7 +166,7 @@ Optional keyword arguments are:
 
 (defmacro evil-narrow-to-line (&rest body)
   "Narrow BODY to the current line.
-BODY will signal the errors 'beginning-of-line or 'end-of-line
+BODY will signal the errors `beginning-of-line' or `end-of-line'
 upon reaching the beginning or end of the current line."
   (declare (indent defun) (debug t))
   `(cl-destructuring-bind (beg end &rest) (evil-line-expand (point) (point))
diff --git a/evil-repeat.el b/evil-repeat.el
index 89cf044cce..d5c69f0956 100644
--- a/evil-repeat.el
+++ b/evil-repeat.el
@@ -233,7 +233,8 @@ If COMMAND doesn't have this property, return DEFAULT."
       (if repeat-type (cdr repeat-type) type))))
 
 (defun evil-repeat-force-abort-p (repeat-type)
-  "Return non-nil iff the current command should abort the recording of repeat 
information."
+  "Should the current command should abort the recording of repeat information?
+Return non-nil iff that is the case."
   (or (evil-repeat-different-buffer-p)           ; ... buffer changed
       (eq repeat-type 'abort)                    ; ... explicitely forced
       (eq evil-recording-repeat 'abort)          ; ... already aborted
@@ -340,7 +341,8 @@ invoked the current command"
     (evil-clear-command-keys))))
 
 (defun evil-repeat-motion (flag)
-  "Repeation for motions. Motions are recorded by keystroke but only in insert 
state."
+  "Repetition for motions.
+Motions are recorded by keystroke but only in insert state."
   (when (memq evil-state '(insert replace))
     (evil-repeat-keystrokes flag)))
 
diff --git a/evil-search.el b/evil-search.el
index e26325c666..e333221e1f 100644
--- a/evil-search.el
+++ b/evil-search.el
@@ -305,7 +305,7 @@ otherwise for the word at point."
 (defun evil--find-thing (forward thing)
   "Return a cons of THING near point as a string and its position.
 THING should be a symbol understood by `thing-at-point',
-e.g. 'symbol or 'word.  If FORWARD is nil, search backward,
+e.g. `symbol' or `word'.  If FORWARD is nil, search backward,
 otherwise forward.  Returns nil if nothing is found."
   (let ((move (if forward #'forward-char #'backward-char))
         (end (if forward #'eobp #'bobp))
@@ -325,7 +325,7 @@ otherwise forward.  Returns nil if nothing is found."
 (defun evil-find-thing (forward thing)
   "Return a THING near point as a string.
 THING should be a symbol understood by `thing-at-point',
-e.g. 'symbol or 'word.  If FORWARD is nil, search backward,
+e.g. `symbol' or `word'.  If FORWARD is nil, search backward,
 otherwise forward.  Returns nil if nothing is found."
   (car (evil--find-thing forward thing)))
 
@@ -420,7 +420,7 @@ This function respects the values of `evil-ex-search-case'."
 (defun evil-ex-make-pattern (regexp case whole-line)
   "Create a new search pattern.
 REGEXP is the regular expression to be searched for. CASE should
-be either 'sensitive, 'insensitive for case-sensitive and
+be either `sensitive', `insensitive' for case-sensitive and
 case-insensitive search, respectively, or anything else.  In the
 latter case the pattern is smart-case, i.e. it is automatically
 sensitive of the pattern contains one upper case letter,
@@ -822,14 +822,14 @@ the direcion is determined by `evil-ex-search-direction'."
 (defun evil-ex-find-next (&optional pattern direction nowrap)
   "Search for the next occurrence of the PATTERN in DIRECTION.
 PATTERN must be created using `evil-ex-make-pattern', DIRECTION
-is either 'forward or 'backward. If NOWRAP is non nil, the search
+is either `forward' or `backward'. If NOWRAP is non nil, the search
 does not wrap at buffer boundaries. Furthermore this function
 only searches invisible text if `search-invisible' is t. If
 PATTERN is not specified the current global pattern
 `evil-ex-search-pattern' and if DIRECTION is not specified the
 current global direction `evil-ex-search-direction' is used.
 This function returns t if the search was successful, nil if it
-was unsuccessful and 'wrapped if the search was successful but
+was unsuccessful and `wrapped' if the search was successful but
 has been wrapped at the buffer boundaries."
   (setq pattern (or pattern evil-ex-search-pattern)
         direction (or direction evil-ex-search-direction))
@@ -945,7 +945,7 @@ Return a triple (regexp offset next-search)."
   "Search for a full search pattern PATTERN-STRING in DIRECTION.
 This function splits PATTERN-STRING into
 pattern/offset/;next-pattern parts and performs the search in
-DIRECTION which must be either 'forward or 'backward. The first
+DIRECTION which must be either `forward' or `backward'. The first
 search is repeated COUNT times. If the pattern part of
 PATTERN-STRING is empty, the last global pattern stored in
 `evil-ex-search-pattern' is used instead if in addition the
@@ -955,10 +955,10 @@ offset. The current match data will correspond to the last
 successful match.  This function returns a triple (RESULT PATTERN
 OFFSET) where RESULT is
 
-  t              the search has been successful without wrap
-  'wrap          the search has been successful with wrap
-  'empty-pattern the last pattern has been empty
-  nil            the search has not been successful
+  t               the search has been successful without wrap
+  `wrap'          the search has been successful with wrap
+  `empty-pattern' the last pattern has been empty
+  nil             the search has not been successful
 
 and PATTERN and OFFSET are the last pattern and offset this
 function searched for. Note that this function does not handle
@@ -1276,7 +1276,7 @@ compiled replacement expression (see 
`evil-compile-replacement').
 The information returned is the actual substitution information
 w.r.t. to special situations like empty patterns or repetition of
 previous substitution commands. If IMPLICIT-R is non-nil, then
-the flag 'r' is assumed, i.e. in the case of an empty pattern the
+the flag `r' is assumed, i.e. in the case of an empty pattern the
 last search pattern is used. This will be used when called from
 a :substitute command with arguments."
   (let (pattern replacement flags)
diff --git a/evil-vars.el b/evil-vars.el
index df1b413a1b..ff09af0eed 100644
--- a/evil-vars.el
+++ b/evil-vars.el
@@ -407,7 +407,7 @@ also be inhibited by setting `evil-inhibit-esc'."
 Used by `evil-esc-mode'.")
 
 (defvar evil-inhibit-esc nil
-  "If non-nil, the \\e event will never be translated to 'escape.")
+  "If non-nil, the \\e event will never be translated to `escape'.")
 
 (defcustom evil-intercept-esc 'always
   "Whether Evil should intercept the escape key.
@@ -1867,7 +1867,7 @@ the format:
 MODES acts as a predicate, containing the symbols of all major or
 minor modes for which the handler should match.  For example:
 
-  '((outline-minor-mode org-mode) ...)
+  \\='((outline-minor-mode org-mode) ...)
 
 would match for either outline-minor-mode or org-mode, even though the
 former is a minor mode and the latter is a major.
@@ -1977,7 +1977,7 @@ See `evil-ex-init-shell-argument-completion'.")
   "The history for the search command.")
 
 (defvar evil-ex-search-direction nil
-  "The direction of the current search, either 'forward or 'backward.")
+  "The direction of the current search, either `forward' or `backward'.")
 
 (defvar evil-ex-search-count nil
   "The count of the current search.")