branch: master
commit bae456d654034ee98e6a8a7e023adfb4fd4cb5ea
Author: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
Commit: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
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.
