[elpa] master 8e5674f 21/26: Cleanup documentation.

[Jackson Ray Hamilton]

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

    Cleanup documentation.
---
 benchmark/context-coloring-benchmark.el |   19 ++++++--
 context-coloring.el                     |   18 +++---
 test/context-coloring-test.el           |   83 +++++++++++++++++++++----------
 3 files changed, 80 insertions(+), 40 deletions(-)

diff --git a/benchmark/context-coloring-benchmark.el 
b/benchmark/context-coloring-benchmark.el
index 887cdc8..3da8d79 100644
--- a/benchmark/context-coloring-benchmark.el
+++ b/benchmark/context-coloring-benchmark.el
@@ -17,8 +17,19 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+
+;; Benchmarks for context-coloring.
+
+;; `ert' instruments and benchmarks the package's functions, and the results 
are
+;; logged to `benchmark/logs'.
+
+;; To run, execute `make bench' from the project root.
+
 ;;; Code:
 
+(require 'js2-mode)
+
 (defconst context-coloring-benchmark-path
   (file-name-directory (or load-file-name buffer-file-name))
   "This file's directory.")
@@ -28,7 +39,7 @@
   (expand-file-name path context-coloring-benchmark-path))
 
 (defun context-coloring-benchmark-log-results (result-file fixture)
-  "Log benchmarking results for FIXTURE to RESULT-FILE."
+  "Log benchmarking results to RESULT-FILE for fixture FIXTURE."
   (elp-results)
   (let ((results-buffer (current-buffer)))
     (with-temp-buffer
@@ -60,8 +71,9 @@ exhausted, call STOP instead."
           (context-coloring-benchmark-next (cdr list) continue stop)))))))
 
 (defun context-coloring-benchmark-async (title setup teardown fixtures 
callback)
-  "Measure the performance of all FIXTURES, calling CALLBACK when
-all are done."
+  "Execute a benchmark titled TITLE with SETUP and TEARDOWN
+callbacks.  Measure the performance of all FIXTURES, calling
+CALLBACK when all are done."
   (funcall setup)
   (let ((result-file (context-coloring-benchmark-resolve-path
                       (format "./logs/results-%s-%s.log"
@@ -122,7 +134,6 @@ all are done."
 
 (defun context-coloring-benchmark-js2-mode-setup ()
   "Preparation logic for `js2-mode'."
-  (require 'js2-mode)
   (setq js2-mode-show-parse-errors nil)
   (setq js2-mode-show-strict-warnings nil)
   (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))
diff --git a/context-coloring.el b/context-coloring.el
index ae7684d..47cb00b 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -250,10 +250,10 @@ element."
         (setq i (+ i 3))))
     (context-coloring-maybe-colorize-comments-and-strings)))
 
-(defun context-coloring-parse-array (input)
-  "Parse a flat JSON array of numbers."
+(defun context-coloring-parse-array (array)
+  "Parse ARRAY as a flat JSON array of numbers."
   (vconcat
-   (mapcar 'string-to-number (split-string (substring input 1 -1) ","))))
+   (mapcar 'string-to-number (split-string (substring array 1 -1) ","))))
 
 (defvar-local context-coloring-scopifier-process nil
   "The single scopifier process that can be running.")
@@ -265,7 +265,7 @@ element."
     (setq context-coloring-scopifier-process nil)))
 
 (defun context-coloring-scopify-shell-command (command &optional callback)
-  "Invoke a scopifier with the current buffer's contents,
+  "Invoke a scopifier via COMMAND with the current buffer's contents,
 read the scopifier's response asynchronously and apply a parsed
 list of tokens to `context-coloring-apply-tokens'.
 
@@ -455,7 +455,7 @@ used.")
   "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
@@ -468,8 +468,8 @@ used.")
   `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'.
@@ -504,8 +504,8 @@ 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)
-  "Warn the user that the colors for a theme are already
-originally set."
+  "Warn the user that the colors for THEME are already originally
+set."
   (warn "Context coloring colors for theme `%s' are already defined" theme))
 
 (defun context-coloring-theme-highest-level (theme)
diff --git a/test/context-coloring-test.el b/test/context-coloring-test.el
index da32a3e..88a7158 100644
--- a/test/context-coloring-test.el
+++ b/test/context-coloring-test.el
@@ -17,6 +17,15 @@
 ;; You should have received a copy of the GNU General Public License
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+;;; Commentary:
+
+;; Tests for context-coloring.
+
+;; Tests for both synchronous (elisp) and asynchronous (shell command) coloring
+;; are available.  Basic plugin functionality is also tested.
+
+;; To run, execute `make test' from the project root.
+
 ;;; Code:
 
 (require 'ert-async)
@@ -29,24 +38,24 @@
   "This file's directory.")
 
 (defun context-coloring-test-read-file (path)
-  "Read a file's contents into a string."
+  "Read a file's contents from PATH into a string."
   (with-temp-buffer
     (insert-file-contents (expand-file-name path context-coloring-test-path))
     (buffer-string)))
 
 (defun context-coloring-test-setup ()
-  "Preparation code to run before all tests."
+  "Prepare before all tests."
   (setq context-coloring-comments-and-strings nil))
 
 (defun context-coloring-test-cleanup ()
-  "Cleanup code to run after all tests."
+  "Cleanup after all tests."
   (setq context-coloring-comments-and-strings t)
   (setq context-coloring-after-colorize-hook nil)
   (setq context-coloring-js-block-scopes nil))
 
 (defmacro context-coloring-test-with-fixture (fixture &rest body)
-  "Evaluate BODY in a temporary buffer with the relative
-FIXTURE."
+  "With the relative FIXTURE, evaluate BODY in a temporary
+buffer."
   `(with-temp-buffer
      (unwind-protect
          (progn
@@ -72,10 +81,10 @@ is done."
 
 (defun context-coloring-test-with-fixture-async
     (fixture callback &optional setup)
-  "Evaluate CALLBACK in a temporary buffer with the relative
-FIXTURE.  A teardown callback is passed to CALLBACK for it to
-invoke when it is done.  An optional SETUP callback can be passed
-to run arbitrary code before the mode is invoked."
+  "With the relative FIXTURE, evaluate CALLBACK in a temporary
+buffer.  A teardown callback is passed to CALLBACK for it to
+invoke when it is done.  An optional SETUP callback can run
+arbitrary code before the mode is invoked."
   (context-coloring-test-with-temp-buffer-async
    (lambda (done-with-temp-buffer)
      (context-coloring-test-setup)
@@ -116,8 +125,8 @@ instantiated in SETUP."
     ,@body))
 
 (defmacro context-coloring-test-deftest-js-mode (name)
-  "Define an asynchronous test for `js-mode' in the typical
-format."
+  "Define an asynchronous test for `js-mode' with the name NAME
+in the typical format."
   (let ((test-name (intern (format "context-coloring-test-js-mode-%s" name)))
         (fixture (format "./fixtures/%s.js" name))
         (function-name (intern-soft
@@ -132,7 +141,8 @@ format."
                            (funcall done))))))
 
 (defmacro context-coloring-test-deftest-js2-mode (name)
-  "Define a test for `js2-mode' in the typical format."
+  "Define a test for `js2-mode' with the name NAME in the typical
+format."
   (let ((test-name (intern (format "context-coloring-test-js2-mode-%s" name)))
         (fixture (format "./fixtures/%s.js" name))
         (function-name (intern-soft
@@ -148,7 +158,7 @@ format."
 (defmacro context-coloring-test-assert-region (&rest body)
   "Assert something about the face of points in a region.
 Provides the free variables `i', `length', `point', `face' and
-`actual-level'."
+`actual-level' to the code in BODY."
   `(let ((i 0)
          (length (- end start)))
      (while (< i length)
@@ -205,13 +215,13 @@ EXPECTED-FACE."
    start end 'font-lock-comment-face))
 
 (defun context-coloring-test-assert-region-string (start end)
-    "Assert that all points in the range [START, END) have
+  "Assert that all points in the range [START, END) have
 `font-lock-string-face'."
   (context-coloring-test-assert-region-face
    start end 'font-lock-string-face))
 
 (defun context-coloring-test-assert-message (expected buffer)
-  "Assert that BUFFER has message EXPECTED."
+  "Assert that message EXPECTED exists in BUFFER."
   (when (null (get-buffer buffer))
     (ert-fail
      (format
@@ -250,7 +260,7 @@ EXPECTED-FACE."
 
 (defun context-coloring-test-assert-face (level foreground &optional negate)
   "Assert that a face for LEVEL exists and that its `:foreground'
-is FOREGROUND."
+is FOREGROUND, or the inverse if NEGATE is non-nil."
   (let* ((face (context-coloring-level-face level))
          actual-foreground)
     (when (not (or negate
@@ -270,7 +280,8 @@ is FOREGROUND."
 
 (defun context-coloring-test-assert-not-face (&rest arguments)
   "Assert that LEVEL does not have a face with `:foreground'
-FOREGROUND."
+FOREGROUND.  Apply ARGUMENTS to
+`context-coloring-test-assert-face', see that function."
   (apply 'context-coloring-test-assert-face
          (append arguments '(t))))
 
@@ -299,8 +310,8 @@ FOREGROUND."
 (defun context-coloring-test-assert-theme-originally-set-p
     (settings &optional negate)
   "Assert that `context-coloring-theme-originally-set-p' returns
-`t' for a theme with SETTINGS (or the inverse if NEGATE is
-non-nil)."
+t for a theme with SETTINGS, or the inverse if NEGATE is
+non-nil."
   (let ((theme (context-coloring-test-get-next-theme)))
     (put theme 'theme-settings settings)
     (when (funcall (if negate 'identity 'not)
@@ -314,7 +325,9 @@ non-nil)."
 
 (defun context-coloring-test-assert-not-theme-originally-set-p (&rest 
arguments)
   "Assert that `context-coloring-theme-originally-set-p' does not
-return `t' for a theme with SETTINGS."
+return t for a theme with SETTINGS.  Apply ARGUMENTS to
+`context-coloring-test-assert-theme-originally-set-p', see that
+function."
   (apply 'context-coloring-test-assert-theme-originally-set-p
          (append arguments '(t))))
 
@@ -341,7 +354,8 @@ EXPECTED-LEVEL."
 
 (defun context-coloring-test-assert-theme-highest-level
     (theme expected-level &optional negate)
-  "Assert that THEME has the highest level EXPECTED-LEVEL."
+  "Assert that THEME has the highest level EXPECTED-LEVEL, or the
+inverse if NEGATE is non-nil."
   (let ((highest-level (context-coloring-theme-highest-level theme)))
     (when (funcall (if negate 'identity 'not) (eq highest-level 
expected-level))
       (ert-fail (format (concat "Expected theme with settings `%s' "
@@ -352,7 +366,10 @@ EXPECTED-LEVEL."
                         (if negate "did" (format "was %s" highest-level)))))))
 
 (defun context-coloring-test-assert-theme-not-highest-level (&rest arguments)
-  "Assert that THEME's highest level is not EXPECTED-LEVEL."
+  "Assert that THEME's highest level is not EXPECTED-LEVEL.
+Apply ARGUMENTS to
+`context-coloring-test-assert-theme-highest-level', see that
+function."
   (apply 'context-coloring-test-assert-theme-highest-level
          (append arguments '(t))))
 
@@ -377,9 +394,10 @@ EXPECTED-LEVEL."
   )
 
 (defmacro context-coloring-test-deftest-define-theme (name &rest body)
-  "Define a test with an automatically-generated theme symbol
-available as a free variable `theme'.  Side-effects from enabling
-themes are reversed after the test completes."
+  "Define a test with name NAME and an automatically-generated
+theme symbol available as a free variable `theme'.  Side-effects
+from enabling themes are reversed after BODY is executed and the
+test completes."
   (declare (indent defun))
   (let ((deftest-name (intern
                        (format "context-coloring-test-define-theme-%s" name))))
@@ -536,7 +554,8 @@ theme THEME is signaled."
   (context-coloring-test-assert-face 1 "#bbbbbb"))
 
 (defun context-coloring-test-assert-maximum-face (maximum &optional negate)
-  "Assert that `context-coloring-maximum-face' is MAXIMUM."
+  "Assert that `context-coloring-maximum-face' is MAXIMUM, or the
+inverse if NEGATE is non-nil."
   (when (funcall (if negate 'identity 'not)
                  (eq context-coloring-maximum-face maximum))
     (ert-fail (format (concat "Expected `context-coloring-maximum-face' "
@@ -548,7 +567,9 @@ theme THEME is signaled."
                         (format "was `%s'" context-coloring-maximum-face))))))
 
 (defun context-coloring-test-assert-not-maximum-face (&rest arguments)
-  "Assert that `context-coloring-maximum-face' is not MAXIMUM."
+  "Assert that `context-coloring-maximum-face' is not MAXIMUM.
+Apply ARGUMENTS to `context-coloring-test-assert-maximum-face',
+see that function."
   (apply 'context-coloring-test-assert-maximum-face
          (append arguments '(t))))
 
@@ -591,6 +612,7 @@ theme THEME is signaled."
   (context-coloring-test-assert-not-maximum-face 1))
 
 (defun context-coloring-test-js-function-scopes ()
+  "Test fixtures/functions-scopes.js."
   (context-coloring-test-assert-region-level 1 9 0)
   (context-coloring-test-assert-region-level 9 23 1)
   (context-coloring-test-assert-region-level 23 25 0)
@@ -608,6 +630,7 @@ theme THEME is signaled."
 (context-coloring-test-deftest-js2-mode function-scopes)
 
 (defun context-coloring-test-js-global ()
+  "Test fixtures/global.js."
   (context-coloring-test-assert-region-level 20 28 1)
   (context-coloring-test-assert-region-level 28 35 0)
   (context-coloring-test-assert-region-level 35 41 1))
@@ -616,6 +639,7 @@ theme THEME is signaled."
 (context-coloring-test-deftest-js2-mode global)
 
 (defun context-coloring-test-js-block-scopes ()
+  "Test fixtures/block-scopes.js."
   (context-coloring-test-assert-region-level 20 64 1)
    (setq context-coloring-js-block-scopes t)
    (context-coloring-colorize)
@@ -627,6 +651,7 @@ theme THEME is signaled."
 (context-coloring-test-deftest-js2-mode block-scopes)
 
 (defun context-coloring-test-js-catch ()
+  "Test fixtures/js-catch.js."
   (context-coloring-test-assert-region-level 20 27 1)
   (context-coloring-test-assert-region-level 27 51 2)
   (context-coloring-test-assert-region-level 51 52 1)
@@ -640,12 +665,14 @@ theme THEME is signaled."
 (context-coloring-test-deftest-js2-mode catch)
 
 (defun context-coloring-test-js-key-names ()
+  "Test fixtures/key-names.js."
   (context-coloring-test-assert-region-level 20 63 1))
 
 (context-coloring-test-deftest-js-mode key-names)
 (context-coloring-test-deftest-js2-mode key-names)
 
 (defun context-coloring-test-js-property-lookup ()
+  "Test fixtures/property-lookup.js."
   (context-coloring-test-assert-region-level 20 26 0)
   (context-coloring-test-assert-region-level 26 38 1)
   (context-coloring-test-assert-region-level 38 44 0)
@@ -657,12 +684,14 @@ theme THEME is signaled."
 (context-coloring-test-deftest-js2-mode property-lookup)
 
 (defun context-coloring-test-js-key-values ()
+  "Test fixtures/key-values.js."
   (context-coloring-test-assert-region-level 78 79 1))
 
 (context-coloring-test-deftest-js-mode key-values)
 (context-coloring-test-deftest-js2-mode key-values)
 
 (defun context-coloring-test-js-comments-and-strings ()
+  "Test fixtures/comments-and-strings.js."
   (context-coloring-test-assert-region-comment-delimiter 1 4)
   (context-coloring-test-assert-region-comment 4 8)
   (context-coloring-test-assert-region-comment-delimiter 9 12)