[elpa] master bae456d 19/26: Use imperative for documentation.

[Jackson Ray Hamilton]

branch: master
commit bae456d654034ee98e6a8a7e023adfb4fd4cb5ea
Author: Jackson Ray Hamilton <address@hidden>
Commit: Jackson Ray Hamilton <address@hidden>

    Use imperative for documentation.
---
 context-coloring.el |  102 +++++++++++++++++++++++---------------------------
 1 files changed, 47 insertions(+), 55 deletions(-)

diff --git a/context-coloring.el b/context-coloring.el
index 6c71180..ae7684d 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -125,8 +125,8 @@ backgrounds."
 ;;; Colorization utilities
 
 (defsubst context-coloring-colorize-region (start end level)
-  "Colorizes characters from the 1-indexed START (inclusive) to
-END (exclusive) with the face corresponding to LEVEL."
+  "Color characters from the 1-indexed START point (inclusive) to
+the END point (exclusive) with the face corresponding to LEVEL."
   (add-text-properties
    start
    end
@@ -137,7 +137,7 @@ END (exclusive) with the face corresponding to LEVEL."
   :group 'context-coloring)
 
 (defsubst context-coloring-maybe-colorize-comments-and-strings ()
-  "Colorizes the current buffer's comments and strings if
+  "Color the current buffer's comments and strings if
 `context-coloring-comments-and-strings' is non-nil."
   (when context-coloring-comments-and-strings
     (save-excursion
@@ -147,20 +147,20 @@ END (exclusive) with the face corresponding to LEVEL."
 ;;; js2-mode colorization
 
 (defvar-local context-coloring-js2-scope-level-hash-table nil
-  "Associates `js2-scope' structures and with their scope
+  "Associate `js2-scope' structures and with their scope
   levels.")
 
 (defcustom context-coloring-js-block-scopes nil
   "If non-nil, also color block scopes in the scope hierarchy in JavaScript.
 
-The block-scoped `let' and `const' are introduced in ES6.  If you
-are writing ES6 code, enable this; otherwise, don't.
+The block-scoped `let' and `const' are introduced in ES6.  Enable
+this for ES6 code; disable it elsewhere.
 
 Supported modes: `js2-mode'"
   :group 'context-coloring)
 
 (defsubst context-coloring-js2-scope-level (scope)
-  "Gets the level of SCOPE."
+  "Return the level of SCOPE."
   (cond ((gethash scope context-coloring-js2-scope-level-hash-table))
         (t
          (let ((level 0)
@@ -180,7 +180,7 @@ Supported modes: `js2-mode'"
            (puthash scope level 
context-coloring-js2-scope-level-hash-table)))))
 
 (defsubst context-coloring-js2-local-name-node-p (node)
-  "Determines if NODE is a js2-name-node representing a local
+  "Determine if NODE is a `js2-name-node' representing a local
 variable."
   (and (js2-name-node-p node)
        (let ((parent (js2-node-parent node)))
@@ -192,7 +192,7 @@ variable."
                        (eq node (js2-prop-get-node-right parent))))))))
 
 (defsubst context-coloring-js2-colorize-node (node level)
-  "Colors NODE with the color for LEVEL."
+  "Color NODE with the color for LEVEL."
   (let ((start (js2-node-abs-pos node)))
     (context-coloring-colorize-region
      start
@@ -200,8 +200,8 @@ variable."
      level)))
 
 (defun context-coloring-js2-colorize ()
-  "Colorizes the current buffer using the abstract syntax tree
-generated by js2-mode."
+  "Color the current buffer using the abstract syntax tree
+generated by `js2-mode'."
   ;; Reset the hash table; the old one could be obsolete.
   (setq context-coloring-js2-scope-level-hash-table (make-hash-table :test 
'eq))
   (with-silent-modifications
@@ -235,8 +235,8 @@ generated by js2-mode."
 ;;; Shell command scopification / colorization
 
 (defun context-coloring-apply-tokens (tokens)
-  "Processes a vector of TOKENS to apply context-based coloring
-to the current buffer.  Tokens are 3 integers: start, end, level.
+  "Process a vector of TOKENS to apply context-based coloring to
+the current buffer.  Tokens are 3 integers: start, end, level.
 The vector is flat, with a new token occurring after every 3rd
 element."
   (with-silent-modifications
@@ -251,27 +251,25 @@ element."
     (context-coloring-maybe-colorize-comments-and-strings)))
 
 (defun context-coloring-parse-array (input)
-  "Specialized JSON parser for a flat array of numbers."
+  "Parse a flat JSON array of numbers."
   (vconcat
    (mapcar 'string-to-number (split-string (substring input 1 -1) ","))))
 
 (defvar-local context-coloring-scopifier-process nil
-  "Reference to the single scopifier process that can be
-  running.")
+  "The single scopifier process that can be running.")
 
 (defun context-coloring-kill-scopifier ()
-  "Kills the currently-running scopifier process for this
-buffer."
+  "Kill the currently-running scopifier process."
   (when (not (null context-coloring-scopifier-process))
     (delete-process context-coloring-scopifier-process)
     (setq context-coloring-scopifier-process nil)))
 
 (defun context-coloring-scopify-shell-command (command &optional callback)
-  "Invokes a scopifier with the current buffer's contents,
-reading the scopifier's response asynchronously and applying a
-parsed list of tokens to `context-coloring-apply-tokens'.
+  "Invoke a scopifier with the current buffer's contents,
+read the scopifier's response asynchronously and apply a parsed
+list of tokens to `context-coloring-apply-tokens'.
 
-Invokes CALLBACK when complete."
+Invoke CALLBACK when complete."
 
   ;; Prior running tokenization is implicitly obsolete if this function is
   ;; called.
@@ -314,11 +312,11 @@ Invokes CALLBACK when complete."
 ;;; Dispatch
 
 (defvar context-coloring-dispatch-hash-table (make-hash-table :test 'eq)
-  "Mapping of dispatch strategy names to their corresponding
-  property lists, which contain details about the strategies.")
+  "Map dispatch strategy names to their corresponding property
+  lists, which contain details about the strategies.")
 
 (defvar context-coloring-mode-hash-table (make-hash-table :test 'eq)
-  "Mapping of major mode names to dispatch property lists.")
+  "Map major mode names to dispatch property lists.")
 
 (defun context-coloring-select-dispatch (mode dispatch)
   "Use DISPATCH for MODE."
@@ -384,10 +382,10 @@ level data returned via stdout."
  :colorizer 'context-coloring-js2-colorize)
 
 (defun context-coloring-dispatch (&optional callback)
-  "Determines the optimal track for scopification / colorization
-of the current buffer, then executes it.
+  "Determine the optimal track for scopification / coloring of
+the current buffer, then execute it.
 
-Invokes CALLBACK when complete.  It is invoked synchronously for
+Invoke CALLBACK when complete.  It is invoked synchronously for
 elisp tracks, and asynchronously for shell command tracks."
   (let ((dispatch (gethash major-mode context-coloring-mode-hash-table)))
     (when (null dispatch)
@@ -420,9 +418,9 @@ messages with the colorization duration."
   :group 'context-coloring)
 
 (defun context-coloring-colorize (&optional callback)
-  "Colors the current buffer by function context.
+  "Color the current buffer by function context.
 
-Invokes CALLBACK when complete; see `context-coloring-dispatch'."
+Invoke CALLBACK when complete; see `context-coloring-dispatch'."
   (interactive)
   (let ((start-time (float-time)))
     (context-coloring-dispatch
@@ -432,22 +430,19 @@ Invokes CALLBACK when complete; see 
`context-coloring-dispatch'."
        (when callback (funcall callback))))))
 
 (defvar-local context-coloring-changed nil
-  "Indication that the buffer has changed recently, which would
-imply that it should be colorized again by
+  "Indication that the buffer has changed recently, which implies
+that it should be colored again by
 `context-coloring-colorize-idle-timer' if that timer is being
 used.")
 
 (defun context-coloring-change-function (_start _end _length)
-  "Registers a change so that a buffer can be colorized soon."
+  "Register a change so that a buffer can be colorized soon."
   ;; Tokenization is obsolete if there was a change.
   (context-coloring-kill-scopifier)
   (setq context-coloring-changed t))
 
 (defun context-coloring-maybe-colorize ()
-  "Colorize unders certain conditions.  This will run as an idle
-timer, so firstly the buffer must not be some other buffer.
-Additionally, the buffer must have changed, otherwise colorizing
-would be redundant."
+  "Colorize the current buffer if it has changed."
   (when (and (eq context-coloring-buffer (window-buffer (selected-window)))
              context-coloring-changed)
     (setq context-coloring-changed nil)
@@ -457,24 +452,24 @@ would be redundant."
 ;;; Themes
 
 (defvar context-coloring-theme-hash-table (make-hash-table :test 'eq)
-  "Mapping of theme names to theme properties.")
+  "Map theme names to theme properties.")
 
 (defun context-coloring-theme-p (theme)
-  "Return t if THEME is defined, nil otherwise."
+  "Return `t' if THEME is defined, `nil' otherwise."
   (and (gethash theme context-coloring-theme-hash-table)))
 
 (defconst context-coloring-level-face-regexp
   "context-coloring-level-\\([[:digit:]]+\\)-face"
-  "Regular expression for extracting a level from a face.")
+  "Extract a level from a face.")
 
 (defvar context-coloring-originally-set-theme-hash-table
   (make-hash-table :test 'eq)
-  "Cache of custom themes who originally set their own
+  "Cache custom themes who originally set their own
   `context-coloring-level-N-face' faces.")
 
 (defun context-coloring-theme-originally-set-p (theme)
-  "Return t if there is a `context-coloring-level-N-face'
-originally set for THEME, nil otherwise."
+  "Return `t' if there is a `context-coloring-level-N-face'
+originally set for THEME, `nil' otherwise."
   (let (originally-set)
     (cond
      ;; `setq' might return a non-nil value for the sake of this `cond'.
@@ -509,14 +504,14 @@ ORIGINALLY-SET is non-nil, it did, otherwise it didn't."
    context-coloring-originally-set-theme-hash-table))
 
 (defun context-coloring-warn-theme-originally-set (theme)
-  "Warns the user that the colors for a theme are already
+  "Warn the user that the colors for a theme are already
 originally set."
   (warn "Context coloring colors for theme `%s' are already defined" theme))
 
 (defun context-coloring-theme-highest-level (theme)
   "Return the highest level N of a face like
-`context-coloring-level-N-face' set for THEME, or -1 if there is
-none."
+`context-coloring-level-N-face' set for THEME, or `-1' if there
+is none."
   (let* ((settings (get theme 'theme-settings))
          (tail settings)
          face-string
@@ -538,7 +533,7 @@ none."
     found))
 
 (defun context-coloring-apply-theme (theme)
-  "Applies THEME's properties to its respective custom theme,
+  "Apply THEME's properties to its respective custom theme,
 which must already exist and which *should* already be enabled."
   (let* ((properties (gethash theme context-coloring-theme-hash-table))
          (colors (plist-get properties :colors))
@@ -606,9 +601,8 @@ precedence, i.e. the car of `custom-enabled-themes'."
             (context-coloring-apply-theme name)))))))
 
 (defun context-coloring-enable-theme (theme)
-  "Applies THEME if its colors are not already set, else just
-sets `context-coloring-maximum-face' to the correct value for
-THEME."
+  "Apply THEME if its colors are not already set, else just set
+`context-coloring-maximum-face' to the correct value for THEME."
   (let* ((properties (gethash theme context-coloring-theme-hash-table))
          (recede (plist-get properties :recede))
          (override (plist-get properties :override)))
@@ -638,8 +632,7 @@ THEME."
         (context-coloring-apply-theme theme))))))
 
 (defadvice enable-theme (after context-coloring-enable-theme (theme) activate)
-  "Enable colors for context themes just-in-time.  We can't set
-faces for custom themes that might not exist yet."
+  "Enable colors for context themes just-in-time."
   (when (and (not (eq theme 'user)) ; Called internally by `enable-theme'.
              (custom-theme-p theme) ; Guard against non-existent themes.
              (context-coloring-theme-p theme))
@@ -650,8 +643,7 @@ faces for custom themes that might not exist yet."
     (context-coloring-enable-theme theme)))
 
 (defadvice disable-theme (after context-coloring-disable-theme (theme) 
activate)
-  "Colors are disabled normally, but
-`context-coloring-maximum-face' isn't.  Update it here."
+  "Update `context-coloring-maximum-face'."
   (when (custom-theme-p theme) ; Guard against non-existent themes.
     (let ((enabled-theme (car custom-enabled-themes)))
       (if (context-coloring-theme-p enabled-theme)
@@ -800,7 +792,7 @@ faces for custom themes that might not exist yet."
 ;;; Minor mode
 
 (defvar-local context-coloring-colorize-idle-timer nil
-  "Reference to the currently-running idle timer.")
+  "The currently-running idle timer.")
 
 (defcustom context-coloring-delay 0.25
   "Delay between a buffer update and colorization.