[elpa] master 59b1c99 074/271: Documentation and cleanup.

[Jackson Ray Hamilton]

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

    Documentation and cleanup.
---
 bin/cli.js                  |    2 +-
 context-coloring.el         |  135 ++++++++++++++++++++++--------------------
 scopifier-microoptimized.js |    2 +-
 scopifier.js                |    2 +-
 4 files changed, 74 insertions(+), 67 deletions(-)

diff --git a/bin/cli.js b/bin/cli.js
index 9fdea5c..3adfe82 100644
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -1,6 +1,6 @@
 // Reads a JavaScript file from stdin.
 
-// Writes an array of `[level, start, end]' tokens to stdout.
+// Writes an array of `[start, end, level, style]' tokens to stdout.
 
 'use strict';
 
diff --git a/context-coloring.el b/context-coloring.el
index 8623bc5..c50205d 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -44,49 +44,49 @@
 (defface context-coloring-depth--1-face
   '((((background light)) (:foreground "#7f7f7f"))
     (((background dark)) (:foreground "#7f7f7f")))
-  "Nested blocks face, depth -1; comments."
+  "Context coloring face, depth -1; comments."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-0-face
   '((((background light)) (:foreground "#000000"))
     (((background dark)) (:foreground "#ffffff")))
-  "Nested blocks face, depth 0; global scope."
+  "Context coloring face, depth 0; global scope."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-1-face
   '((((background light)) (:foreground "#2D6994"))
     (((background dark)) (:foreground "#ffff80")))
-  "Nested blocks face, depth 1."
+  "Context coloring face, depth 1."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-2-face
   '((((background light)) (:foreground "#592D94"))
     (((background dark)) (:foreground "#cdfacd")))
-  "Nested blocks face, depth 2."
+  "Context coloring face, depth 2."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-3-face
   '((((background light)) (:foreground "#A13143"))
     (((background dark)) (:foreground "#d8d8ff")))
-  "Nested blocks face, depth 3."
+  "Context coloring face, depth 3."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-4-face
   '((((background light)) (:foreground "#AC7135"))
     (((background dark)) (:foreground "#e7c7ff")))
-  "Nested blocks face, depth 4."
+  "Context coloring face, depth 4."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-5-face
   '((((background light)) (:foreground "#ACA135"))
     (((background dark)) (:foreground "#ffcdcd")))
-  "Nested blocks face, depth 5."
+  "Context coloring face, depth 5."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-6-face
   '((((background light)) (:foreground "#539A2F"))
     (((background dark)) (:foreground "#ffe390")))
-  "Nested blocks face, depth 6."
+  "Context coloring face, depth 6."
   :group 'context-coloring-faces)
 
 (defconst context-coloring-face-count 7
@@ -95,49 +95,49 @@ Determines depth at which to cycle through faces again.")
 
 (defface context-coloring-depth--1-italic-face
   '((default (:inherit context-coloring-depth--1-face :slant italic)))
-  "Nested blocks face, depth -1; italic; comments."
+  "Context coloring face, depth -1; italic; comments."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-0-bold-face
   '((default (:inherit context-coloring-depth-0-face :weight bold)))
-  "Nested blocks face, depth 0; bold; global scope."
+  "Context coloring face, depth 0; bold; global scope."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-1-bold-face
   '((default (:inherit context-coloring-depth-1-face :weight bold)))
-  "Nested blocks face, depth 1; bold; global scope."
+  "Context coloring face, depth 1; bold."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-2-bold-face
   '((default (:inherit context-coloring-depth-2-face :weight bold)))
-  "Nested blocks face, depth 2; bold; global scope."
+  "Context coloring face, depth 2; bold."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-3-bold-face
   '((default (:inherit context-coloring-depth-3-face :weight bold)))
-  "Nested blocks face, depth 3; bold; global scope."
+  "Context coloring face, depth 3; bold."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-4-bold-face
   '((default (:inherit context-coloring-depth-4-face :weight bold)))
-  "Nested blocks face, depth 4; bold; global scope."
+  "Context coloring face, depth 4; bold."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-5-bold-face
   '((default (:inherit context-coloring-depth-5-face :weight bold)))
-  "Nested blocks face, depth 5; bold; global scope."
+  "Context coloring face, depth 5; bold."
   :group 'context-coloring-faces)
 
 (defface context-coloring-depth-6-bold-face
   '((default (:inherit context-coloring-depth-6-face :weight bold)))
-  "Nested blocks face, depth 6; bold; global scope."
+  "Context coloring face, depth 6; bold."
   :group 'context-coloring-faces)
 
 
-;;; Face utility functions
+;;; Face functions
 
 (defun context-coloring-level-face (depth style)
-  "Return face-name for DEPTH as a string 
\"context-coloring-depth-DEPTH-face\".
+  "Return face-name for DEPTH and STYLE as a string 
\"context-coloring-depth-DEPTH-face\".
 For example: \"context-coloring-depth-1-face\"."
   (intern-soft
    (concat "context-coloring-depth-"
@@ -157,7 +157,40 @@ For example: \"context-coloring-depth-1-face\"."
            "-face")))
 
 
-;;; Constants
+;;; Customizable variables
+
+(defcustom context-coloring-delay 0.25
+  "Delay between a buffer update and colorization.
+
+If your performance is poor, you might want to increase this.")
+
+
+;;; Local variables
+
+(defvar context-coloring-buffer nil
+  "Reference to this buffer (for timers).")
+(make-variable-buffer-local 'context-coloring-buffer)
+
+(defvar context-coloring-scopifier-process nil
+  "Only allow a single scopifier process to run at a time. This
+is a reference to that one process.")
+(make-variable-buffer-local 'context-coloring-scopifier-process)
+
+(defvar context-coloring-colorize-idle-timer nil
+  "Reference to currently-running idle timer.")
+(make-variable-buffer-local 'context-coloring-colorize-idle-timer)
+
+(defvar context-coloring-changed nil
+  "Indication that the buffer has changed recently, which would
+imply that it should be colorized again.")
+(make-variable-buffer-local 'context-coloring-changed)
+
+(defvar context-coloring-colorize-start-time nil
+  "Used for dirty benchmarking of async colorization time.")
+(make-variable-buffer-local 'context-coloring-colorize-start-time)
+
+
+;;; Scopification
 
 (defconst context-coloring-path
   (file-name-directory (or load-file-name buffer-file-name))
@@ -167,19 +200,10 @@ For example: \"context-coloring-depth-1-face\"."
   (expand-file-name "./bin/scopifier" context-coloring-path)
   "Path to the external scopifier executable.")
 
-(defconst context-coloring-delay 0.25
-  "Time between colorization.")
-
-
-;;; Tokenization functions
-
-;; Tokens are vectors with the following form:
-;; 0: Start
-;; 1: End
-;; 2: Level
-;; 3: Style
 (defun context-coloring-apply-tokens (tokens)
-  "Processes TOKENS to apply context-based coloring to the current buffer."
+  "Processes TOKENS to apply context-based coloring to the
+current buffer. Tokens are vectors consisting of 4 integers:
+start, end, level, and style."
   (with-silent-modifications
     ;; Reset in case there should be uncolored areas.
     (remove-text-properties (point-min) (point-max) `(face nil rear-nonsticky 
nil))
@@ -194,6 +218,8 @@ For example: \"context-coloring-depth-1-face\"."
         (setq i (+ i 1))))))
 
 (defun context-coloring-kill-scopifier ()
+  "Kills the currently-running scopifier process for this
+buffer."
   (when (not (null context-coloring-scopifier-process))
     (delete-process context-coloring-scopifier-process)
     (setq context-coloring-scopifier-process nil)))
@@ -201,7 +227,8 @@ For example: \"context-coloring-depth-1-face\"."
 (defun context-coloring-scopify ()
   "Invokes the external scopifier with the current buffer's
 contents, reading the scopifier's response asynchronously and
-calling FUNCTION with the parsed list of tokens."
+applying a parsed list of tokens to
+`context-coloring-apply-tokens'."
 
   ;; Prior running tokenization is implicitly obsolete if this function is
   ;; called.
@@ -215,8 +242,8 @@ calling FUNCTION with the parsed list of tokens."
         (buffer context-coloring-buffer)
         (start-time context-coloring-colorize-start-time))
 
-    ;;The process may produce output in multiple chunks. This filter 
accumulates
-    ;;the chunks into a message.
+    ;; The process may produce output in multiple chunks. This filter
+    ;; accumulates the chunks into a message.
     (set-process-filter context-coloring-scopifier-process
                         (lambda (process chunk)
                           (setq output (concat output chunk))))
@@ -230,7 +257,7 @@ calling FUNCTION with the parsed list of tokens."
                                 (with-current-buffer buffer
                                   (context-coloring-apply-tokens tokens))
                                 (setq context-coloring-scopifier-process nil)
-                                (message "Colorized (after %f seconds)." (- 
(float-time) start-time))
+                                ;; (message "Colorized (after %f seconds)." (- 
(float-time) start-time))
                                 )))))
 
   ;; Give the process its input.
@@ -238,21 +265,24 @@ calling FUNCTION with the parsed list of tokens."
   (process-send-eof context-coloring-scopifier-process))
 
 
-;;; Colorization functions
+;;; Colorization
 
 (defun context-coloring-colorize ()
+  "Colors the current buffer by function context."
   (interactive)
   (setq context-coloring-colorize-start-time (float-time))
-  (message "%s" "Colorizing.")
+  ;; (message "%s" "Colorizing.")
   (context-coloring-scopify))
 
 (defun context-coloring-change-function (start end length)
+  "Registers a change so that a context-colored 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 under certain conditions. This will run as an idle
+  "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."
@@ -262,31 +292,6 @@ colorizing would be redundant."
     (context-coloring-colorize)))
 
 
-;;; Local variables
-
-(defvar context-coloring-buffer nil
-  "Reference to this buffer for timers.")
-(make-variable-buffer-local 'context-coloring-buffer)
-
-(defvar context-coloring-scopifier-process nil
-  "Only allow a single scopifier process to run at a time. This
-is a reference to that one process.")
-(make-variable-buffer-local 'context-coloring-scopifier-process)
-
-(defvar context-coloring-colorize-idle-timer nil
-  "Reference to currently-running idle timer.")
-(make-variable-buffer-local 'context-coloring-colorize-idle-timer)
-
-(defvar context-coloring-changed nil
-  "Indication that the buffer has changed recently, which would
-imply that it should be colorized again.")
-(make-variable-buffer-local 'context-coloring-changed)
-
-(defvar context-coloring-colorize-start-time nil
-  "Used for dirty benchmarking of async colorization time.")
-(make-variable-buffer-local 'context-coloring-colorize-start-time)
-
-
 ;;; Minor mode
 
 ;;;###autoload
@@ -307,9 +312,11 @@ imply that it should be colorized again.")
     ;; Colorize once initially.
     (context-coloring-colorize)
 
-    ;; Only recolor on change. So watch for changes.
+    ;; Font lock is not compatible with this mode; the converse is also true.
     (font-lock-mode 0)
     (jit-lock-mode nil)
+
+    ;; Only recolor on change.
     (add-hook 'after-change-functions 'context-coloring-change-function nil t)
 
     ;; Only recolor idly.
diff --git a/scopifier-microoptimized.js b/scopifier-microoptimized.js
index 4834243..0cc4f77 100644
--- a/scopifier-microoptimized.js
+++ b/scopifier-microoptimized.js
@@ -7,7 +7,7 @@ var escope = require('escope'),
     bold = 1,
     italic = 2;
 
-// Given code, returns an array of `[level, start, end]' tokens for
+// Given code, returns an array of `[start, end, level, style]' tokens for
 // context-coloring.
 module.exports = function (code) {
     var analyzedScopes,
diff --git a/scopifier.js b/scopifier.js
index 952c15c..377870e 100644
--- a/scopifier.js
+++ b/scopifier.js
@@ -18,7 +18,7 @@ var escope = require('escope'),
     bold = 1,
     italic = 2;
 
-// Given code, returns an array of `[level, start, end]' tokens for
+// Given code, returns an array of `[start, end, level, style]' tokens for
 // context-coloring.
 module.exports = function (code) {
     var ast,