[elpa] master c947690 238/271: Documentation. Cleanup. Copyright notices.

[Jackson Ray Hamilton]

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

    Documentation. Cleanup. Copyright notices.
---
 benchmark/context-coloring-benchmark.el |   47 ++++++++++++++++++++++++++++--
 context-coloring.el                     |   33 +++++++++++++--------
 languages/javascript/scopifier.js       |   15 ++++++++++
 test/context-coloring-test.el           |   19 ++++++++++++-
 4 files changed, 96 insertions(+), 18 deletions(-)

diff --git a/benchmark/context-coloring-benchmark.el 
b/benchmark/context-coloring-benchmark.el
index 6d66f18..cc5b221 100644
--- a/benchmark/context-coloring-benchmark.el
+++ b/benchmark/context-coloring-benchmark.el
@@ -1,12 +1,32 @@
-;; -*- lexical-binding: t; -*-
+;;; benchmark/context-coloring-benchmark.el --- Benchmarks for context 
coloring. -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2014 Jackson Ray Hamilton
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Code:
 
 (defconst context-coloring-benchmark-path
-  (file-name-directory (or load-file-name buffer-file-name)))
+  (file-name-directory (or load-file-name buffer-file-name))
+  "This file's directory.")
 
 (defun context-coloring-benchmark-resolve-path (path)
+  "Resolve PATH from this file's directory."
   (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."
   (elp-results)
   (let ((results-buffer (current-buffer)))
     (with-temp-buffer
@@ -19,9 +39,13 @@
   (append-to-file nil nil result-file))
 
 (defun context-coloring-benchmark-next-tick (function)
+  "Defer execution of FUNCTION to clear the stack and to ensure
+asynchrony."
   (run-at-time 0.001 nil function))
 
 (defun context-coloring-benchmark-next (list continue stop)
+  "Run the next test in LIST by calling CONTINUE.  When LIST is
+exhausted, call STOP instead."
   (if (null list)
       (context-coloring-benchmark-next-tick stop)
     (context-coloring-benchmark-next-tick
@@ -33,9 +57,12 @@
           (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."
   (funcall setup)
   (let ((result-file (context-coloring-benchmark-resolve-path
-                      (concat "./logs/results-" title "-" (format-time-string 
"%s") ".log"))))
+                      (format "./logs/results-%s-%s.log"
+                              title (format-time-string "%s")))))
     (context-coloring-benchmark-next
      fixtures
      (lambda (path next)
@@ -69,16 +96,20 @@
   '("./fixtures/jquery-2.1.1.js"
     "./fixtures/lodash-2.4.1.js"
     "./fixtures/async-0.9.0.js"
-    "./fixtures/mkdirp-0.5.0.js"))
+    "./fixtures/mkdirp-0.5.0.js")
+  "Arbitrary JavaScript files for performance scrutiny.")
 
 (defun context-coloring-benchmark-js-mode-setup ()
+  "Preparation logic for `js-mode'."
   (add-hook 'js-mode-hook 'context-coloring-mode)
   (elp-instrument-package "context-coloring-"))
 
 (defun context-coloring-benchmark-js-mode-teardown ()
+  "Cleanup logic for `js-mode'."
   (remove-hook 'js-mode-hook 'context-coloring-mode))
 
 (defun context-coloring-benchmark-js-mode-run (callback)
+  "Benchmark `js-mode', then call CALLBACK."
   (context-coloring-benchmark-async
    "js-mode"
    'context-coloring-benchmark-js-mode-setup
@@ -87,6 +118,7 @@
    callback))
 
 (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)
@@ -95,6 +127,7 @@
   (elp-instrument-package "context-coloring-"))
 
 (defun context-coloring-benchmark-js2-mode-teardown ()
+  "Cleanup logic for `js2-mode'."
   (remove-hook 'js2-mode-hook 'context-coloring-mode)
   (setq auto-mode-alist (delete '("\\.js\\'" . js2-mode)
                                 auto-mode-alist))
@@ -102,6 +135,7 @@
   (setq js2-mode-show-parse-errors t))
 
 (defun context-coloring-benchmark-js2-mode-run (callback)
+  "Benchmark `js2-mode', then call CALLBACK."
   (context-coloring-benchmark-async
    "js2-mode"
    'context-coloring-benchmark-js2-mode-setup
@@ -110,6 +144,7 @@
    callback))
 
 (defun context-coloring-benchmark-run ()
+  "Benchmark all modes, then exit."
   (context-coloring-benchmark-next
    '(context-coloring-benchmark-js-mode-run
      context-coloring-benchmark-js2-mode-run)
@@ -117,3 +152,7 @@
      (funcall function next))
    (lambda ()
      (kill-emacs))))
+
+(provide 'context-coloring-benchmark)
+
+;;; context-coloring-benchmark.el ends here
diff --git a/context-coloring.el b/context-coloring.el
index 1405341..2cda3fb 100644
--- a/context-coloring.el
+++ b/context-coloring.el
@@ -46,7 +46,8 @@
 (defcustom context-coloring-delay 0.25
   "Delay between a buffer update and colorization.
 
-Increase this if your machine is high-performing. Decrease it if it ain't.
+Increase this if your machine is high-performing.  Decrease it if
+it ain't.
 
 Supported modes: `js-mode', `js3-mode'"
   :group 'context-coloring)
@@ -58,8 +59,8 @@ Supported modes: `js-mode', `js3-mode'"
 (defcustom context-coloring-js-block-scopes nil
   "If non-nil, also color block scopes in the scope hierarchy in JavaScript.
 
-The block-scope-inducing `let' and `const' are introduced in
-ES6. If you are writing ES6 code, enable this; otherwise, don't.
+The block-scope-inducing `let' and `const' are introduced in ES6.
+If you are writing ES6 code, enable this; otherwise, don't.
 
 Supported modes: `js2-mode'"
   :group 'context-coloring)
@@ -126,7 +127,9 @@ used.")
 (defsubst context-coloring-face-symbol (level)
   "Returns a symbol for a face with LEVEL."
   ;; `concat' is faster than `format' here.
-  (intern-soft (concat "context-coloring-level-" (number-to-string level) 
"-face")))
+  (intern-soft (concat "context-coloring-level-"
+                       (number-to-string level)
+                       "-face")))
 
 (defun context-coloring-set-colors (&rest colors)
   "Set context coloring's levels' coloring to COLORS, where the
@@ -178,7 +181,8 @@ END (exclusive) with the face corresponding to LEVEL."
                enclosing-scope)
            (while (and current-scope
                        (js2-node-parent current-scope)
-                       (setq enclosing-scope (js2-node-get-enclosing-scope 
current-scope)))
+                       (setq enclosing-scope
+                             (js2-node-get-enclosing-scope current-scope)))
              (when (or context-coloring-js-block-scopes
                        (let ((type (js2-scope-type current-scope)))
                          (or (= type js2-SCRIPT)
@@ -245,9 +249,9 @@ generated by js2-mode."
 
 (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. The vector is flat, with a new token occurring after every
-3rd element."
+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
     (let ((i 0)
           (len (length tokens)))
@@ -390,10 +394,10 @@ Invokes CALLBACK when complete; see 
`context-coloring-dispatch'."
   (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 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."
   (when (and (eq context-coloring-buffer (window-buffer (selected-window)))
              context-coloring-changed)
     (setq context-coloring-changed nil)
@@ -437,7 +441,10 @@ colorizing would be redundant."
     (when (not (equal major-mode 'js2-mode))
       ;; Only recolor idly.
       (setq context-coloring-colorize-idle-timer
-            (run-with-idle-timer context-coloring-delay t 
'context-coloring-maybe-colorize)))))
+            (run-with-idle-timer
+             context-coloring-delay
+             t
+             'context-coloring-maybe-colorize)))))
 
 (provide 'context-coloring)
 
diff --git a/languages/javascript/scopifier.js 
b/languages/javascript/scopifier.js
index 0171ab2..becbcc7 100644
--- a/languages/javascript/scopifier.js
+++ b/languages/javascript/scopifier.js
@@ -1,3 +1,18 @@
+// Copyright (C) 2014 Jackson Ray Hamilton
+
+// This program is free software; you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
 'use strict';
 
 var escope = require('./libraries/escope'),
diff --git a/test/context-coloring-test.el b/test/context-coloring-test.el
index 6612a62..93fea64 100644
--- a/test/context-coloring-test.el
+++ b/test/context-coloring-test.el
@@ -1,4 +1,21 @@
-;; -*- lexical-binding: t; -*-
+;;; test/context-coloring-test.el --- Tests for context coloring. -*- 
lexical-binding: t; -*-
+
+;; Copyright (C) 2014 Jackson Ray Hamilton
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;;; Code:
 
 ;;; Test running utilities