[elpa] master 354ac23 06/12: Checkdoc compliance.

[Jackson Ray Hamilton]

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

    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))