branch: master
commit 354ac2392271be38733e925b3e2c76fd362e0a6b
Author: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
Commit: Jackson Ray Hamilton <jack...@jacksonrayhamilton.com>
Checkdoc compliance.
---
benchmark/context-coloring-benchmark.el | 3 +-
context-coloring.el | 83 +++++++++++++------------------
test/context-coloring-test.el | 7 +--
3 files changed, 38 insertions(+), 55 deletions(-)
diff --git a/benchmark/context-coloring-benchmark.el
b/benchmark/context-coloring-benchmark.el
index 2256c31..c627249 100644
--- a/benchmark/context-coloring-benchmark.el
+++ b/benchmark/context-coloring-benchmark.el
@@ -39,8 +39,7 @@
(expand-file-name path context-coloring-benchmark-path))
(defun context-coloring-benchmark-log-results (result-file fixture statistics)
- "Log benchmarking results to RESULT-FILE for fixture FIXTURE
-with STATISTICS."
+ "Log results to RESULT-FILE for FIXTURE with STATISTICS."
(let ((results (prog1
(progn
(elp-results)
diff --git a/context-coloring.el b/context-coloring.el
index 624f486..6685ff2 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -58,7 +58,7 @@
doc
:group 'context-coloring)))
-;; Provide some default colors based off Emacs' defaults.
+;; Provide some default colors based off Emacs's defaults.
(context-coloring-defface 0 "#000000" "#ffffff" nil)
(context-coloring-defface 1 "#008b8b" "#00ffff" "yellow")
(context-coloring-defface 2 "#0000ff" "#87cefa" "green")
@@ -68,7 +68,8 @@
(context-coloring-defface 6 "#228b22" "#7fffd4" "red")
(context-coloring-defface 7 "#3f3f3f" "#cdcdcd" nil)
-(defconst context-coloring-default-maximum-face 7)
+(defconst context-coloring-default-maximum-face 7
+ "Maximum face when there are no custom faces.")
;; Create placeholder faces for users and theme authors.
(dotimes (level 18)
@@ -81,14 +82,13 @@
"Dynamic index of the highest face available for coloring.")
(defsubst context-coloring-level-face (level)
- "Return the symbol for a face with LEVEL."
+ "Return symbol for face with LEVEL."
;; `concat' is faster than `format' here.
(intern-soft
(concat "context-coloring-level-" (number-to-string level) "-face")))
(defsubst context-coloring-bounded-level-face (level)
- "Return the symbol for a face with LEVEL, bounded by
-`context-coloring-maximum-face'."
+ "Return symbol for face with LEVEL, bounded by the maximum."
(context-coloring-level-face (min level context-coloring-maximum-face)))
(defconst context-coloring-level-face-regexp
@@ -234,8 +234,7 @@ it ain't."
;;; Colorization utilities
(defsubst context-coloring-colorize-region (start end level)
- "Color characters from the 1-indexed START point (inclusive) to
-the END point (exclusive) with the face corresponding to LEVEL."
+ "Color from START (inclusive) to END (exclusive) with LEVEL."
(add-text-properties
start
end
@@ -256,20 +255,16 @@ the END point (exclusive) with the face corresponding to
LEVEL."
:group 'context-coloring)
(defun context-coloring-font-lock-syntactic-comment-function (state)
- "Tell `font-lock' to color a comment but not a string according
-to STATE."
+ "Color a comment according to STATE."
(if (nth 3 state) nil font-lock-comment-face))
(defun context-coloring-font-lock-syntactic-string-function (state)
- "Tell `font-lock' to color a string but not a comment according
-to STATE."
+ "Color a string according to STATE."
(if (nth 3 state) font-lock-string-face nil))
(defsubst context-coloring-colorize-comments-and-strings (&optional min max)
- "Color the current buffer's comments or strings if
-`context-coloring-syntactic-comments' or
-`context-coloring-syntactic-strings' are non-nil. MIN defaults
-to the beginning of the buffer and MAX defaults to the end."
+ "Maybe color comments and strings in buffer from MIN to MAX.
+MIN defaults to beginning of buffer. MAX defaults to end."
(when (or context-coloring-syntactic-comments
context-coloring-syntactic-strings)
(let ((min (or min (point-min)))
@@ -330,8 +325,7 @@ this for ES6 code; disable it elsewhere."
(puthash scope level
context-coloring-js2-scope-level-hash-table)))))
(defsubst context-coloring-js2-local-name-node-p (node)
- "Determine if NODE is a `js2-name-node' representing a local
-variable."
+ "Determine if NODE represents a local variable."
(and (js2-name-node-p node)
(let ((parent (js2-node-parent node)))
(not (or (and (js2-object-prop-node-p parent)
@@ -358,8 +352,7 @@ variable."
level)))
(defun context-coloring-js2-colorize ()
- "Color the current buffer using the abstract syntax tree
-generated by `js2-mode'."
+ "Color the buffer using the `js2-mode' abstract syntax tree."
;; Reset the hash table; the old one could be obsolete.
(setq context-coloring-js2-scope-level-hash-table (make-hash-table :test
#'eq))
(setq context-coloring-point-max (point-max))
@@ -398,15 +391,13 @@ generated by `js2-mode'."
(while (forward-comment 1)))
(defsubst context-coloring-elisp-forward-sws ()
- "Move forward through whitespace and comments, colorizing
-comments along the way."
+ "Move through whitespace and comments, coloring comments."
(let ((start (point)))
(context-coloring-forward-sws)
(context-coloring-colorize-comments-and-strings start (point))))
(defsubst context-coloring-elisp-forward-sexp ()
- "Like `forward-sexp', but colorize comments and strings along
-the way."
+ "Like `forward-sexp', coloring skipped comments and strings."
(let ((start (point)))
(forward-sexp)
(context-coloring-elisp-colorize-comments-and-strings-in-region
@@ -433,8 +424,7 @@ the way."
(context-coloring-exact-or-regexp
'("t" "nil" "." "?")))
"\\|")
- "Match words that might be considered symbols but can't be
-bound as variables.")
+ "Match symbols that can't be bound as variables.")
(defconst context-coloring-WORD-CODE 2)
(defconst context-coloring-SYMBOL-CODE 3)
@@ -473,8 +463,7 @@ second.")
"Current number of sexps leading up to the next pause.")
(defsubst context-coloring-elisp-increment-sexp-count ()
- "Maybe check if the current parse should be interrupted as a
-result of pending user input."
+ "Maybe check if the user interrupted the current parse."
(setq context-coloring-elisp-sexp-count
(1+ context-coloring-elisp-sexp-count))
(when (and (zerop (% context-coloring-elisp-sexp-count
@@ -505,8 +494,7 @@ result of pending user input."
(member variable (plist-get scope :variables)))
(defsubst context-coloring-elisp-get-variable-level (variable)
- "Search up the scope chain for the first instance of VARIABLE
-and return its level, or 0 (global) if it isn't found."
+ "Return the level of VARIABLE, or 0 if it isn't found."
(let* ((scope-stack context-coloring-elisp-scope-stack)
scope
level)
@@ -545,8 +533,8 @@ and return its level, or 0 (global) if it isn't found."
variable))
(defsubst context-coloring-elisp-parse-bindable (callback)
- "Parse the symbol at point, and if the symbol can be bound,
-invoke CALLBACK with it."
+ "Parse the symbol at point.
+If the symbol can be bound, invoke CALLBACK with it."
(let* ((arg-string (buffer-substring-no-properties
(point)
(progn (context-coloring-elisp-forward-sexp)
@@ -557,10 +545,10 @@ invoke CALLBACK with it."
(funcall callback arg-string))))
(defun context-coloring-elisp-parse-let-varlist (type)
- "Parse the list of variable initializers at point. If TYPE is
-`let', all the variables are bound after all their initializers
-are parsed; if TYPE is `let*', each variable is bound immediately
-after its own initializer is parsed."
+ "Parse the list of variable initializers at point.
+If TYPE is `let', all the variables are bound after all their
+initializers are parsed; if TYPE is `let*', each variable is
+bound immediately after its own initializer is parsed."
(let ((varlist '())
syntax-code)
;; Enter.
@@ -628,8 +616,8 @@ after its own initializer is parsed."
(context-coloring-elisp-forward-sws))
(defun context-coloring-elisp-colorize-scope (callback)
- "Color the whole scope at point with its one color. Handle a
-header in CALLBACK."
+ "Color the whole scope at point with its one color.
+Handle a header in CALLBACK."
(let ((start (point))
(end (progn (forward-sexp)
(point))))
@@ -658,8 +646,8 @@ header in CALLBACK."
(funcall callback)))
(defun context-coloring-elisp-colorize-defun-like (callback)
- "Color the defun-like function at point, parsing the header
-with CALLBACK."
+ "Color the defun-like function at point.
+Parse the header with CALLBACK."
(context-coloring-elisp-colorize-scope
(lambda ()
(when (context-coloring-elisp-identifier-p
(context-coloring-get-syntax-code))
@@ -695,8 +683,8 @@ with CALLBACK."
(context-coloring-elisp-forward-sws))))))
(defun context-coloring-elisp-colorize-lambda-like (callback)
- "Color the lambda-like function at point, parsing the header
-with CALLBACK."
+ "Color the lambda-like function at point.
+Parsing the header with CALLBACK."
(context-coloring-elisp-colorize-scope
(lambda ()
(context-coloring-elisp-parse-header callback))))
@@ -924,8 +912,8 @@ with CALLBACK."
(forward-char))
(defun context-coloring-elisp-colorize-expression-prefix ()
- "Color the expression prefix and the following expression at
-point. It could be a quoted or backquoted expression."
+ "Color the expression prefix and expression at point.
+It could be a quoted or backquoted expression."
(context-coloring-elisp-increment-sexp-count)
(cond
((/= (char-after) context-coloring-BACKTICK-CHAR)
@@ -1021,8 +1009,7 @@ point. It could be a quoted or backquoted expression."
(scan-error (progn))))))
(defun context-coloring-elisp-colorize ()
- "Color the current buffer, parsing elisp to determine its
-scopes and variables."
+ "Color the current Emacs Lisp buffer."
(interactive)
(context-coloring-elisp-colorize-guard
(lambda ()
@@ -1072,8 +1059,7 @@ scopes and variables."
;;; Dispatch
(defvar context-coloring-dispatch-hash-table (make-hash-table :test #'eq)
- "Map dispatch strategy names to their corresponding property
-lists, which contain details about the strategies.")
+ "Map dispatch strategy names to their property lists.")
(defvar context-coloring-mode-hash-table (make-hash-table :test #'eq)
"Map major mode names to dispatch property lists.")
@@ -1136,8 +1122,7 @@ override `context-coloring-default-delay'.
properties)) context-coloring-dispatch-predicates))))
(defun context-coloring-dispatch ()
- "Determine the optimal track for scopification / coloring of
-the current buffer, then execute it."
+ "Determine how to color the current buffer, and color it."
(let* ((dispatch (context-coloring-get-current-dispatch))
(colorizer (plist-get dispatch :colorizer)))
(catch 'interrupted
diff --git a/test/context-coloring-test.el b/test/context-coloring-test.el
index 942d988..afacbec 100644
--- a/test/context-coloring-test.el
+++ b/test/context-coloring-test.el
@@ -44,8 +44,7 @@
(buffer-string)))
(defmacro context-coloring-test-with-fixture (fixture &rest body)
- "With the relative FIXTURE, evaluate BODY in a temporary
-buffer."
+ "With relative FIXTURE, evaluate BODY in a temporary buffer."
`(with-temp-buffer
(progn
(insert (context-coloring-test-read-file ,fixture))
@@ -199,8 +198,7 @@ signaled."
`(define-derived-mode ,name fundamental-mode "Testing")))
(defvar context-coloring-test-caused-p nil
- "Dumb flag tracking for lambdas inside old advice definitions
-which don't seem to have lexical binding.")
+ "If non-nil, coloring was caused.")
(defmacro context-coloring-test-assert-causes-coloring (&rest body)
"Assert that BODY causes coloring."
@@ -219,6 +217,7 @@ which don't seem to have lexical binding.")
(ert-fail "Expected to have colorized, but it didn't."))))
(defun context-coloring-test-cleanup-assert-causes-coloring ()
+ "Undo `context-coloring-test-assert-causes-coloring'."
(ad-unadvise #'context-coloring-colorize)
(setq context-coloring-test-caused-p nil))
