Mucked around with the headers to make them more clojure.contrib friendly

14 files changed, 123 insertions, 9 deletions

diff --git a/src/clojure/contrib/pprint.clj b/src/clojure/contrib/pprint.clj
index 2e2ba461..a9198b02 100644
--- a/src/clojure/contrib/pprint.clj
+++ b/src/clojure/contrib/pprint.clj
@@ -1,10 +1,24 @@
-;   Copyright (c) Tom Faulhaber, March 2009. All rights reserved.
-;   The use and distribution terms for this software are covered by the
-;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
-;   which can be found in the file epl-v10.html at the root of this distribution.
-;   By using this software in any fashion, you are agreeing to be bound by
-;   the terms of this license.
-;   You must not remove this notice, or any other, from this software.
+;;; pprint.clj -- Pretty printer and Common Lisp compatible format function (cl-format) for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
+;;   Copyright (c) Tom Faulhaber, April 2009. All rights reserved.
+;;   The use and distribution terms for this software are covered by the
+;;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
+;;   which can be found in the file epl-v10.html at the root of this distribution.
+;;   By using this software in any fashion, you are agreeing to be bound by
+;;   the terms of this license.
+;;   You must not remove this notice, or any other, from this software.
+
+;; This module comprises two elements:
+;; 1) A pretty printer for Clojure data structures, implemented in the function "pprint"
+;; 2) A Common Lisp compatible format function, implemented as "cl-format" because
+;;    Clojure is using the name "format" for its own format.
+;;
+;; The most complete documentation can be found at http://github.com/tomfaulhaber/cl-format
+;; where I the markdown README is currently displayed. I will be moving it into 
+;; clojure.contrib (either to the wiki or some other document structure) RSN.
 
 (ns clojure.contrib.pprint
   (:use clojure.contrib.pprint.utilities)
diff --git a/src/clojure/contrib/pprint/ColumnWriter.clj b/src/clojure/contrib/pprint/ColumnWriter.clj
index 05fd2fe6..381c81fe 100644
--- a/src/clojure/contrib/pprint/ColumnWriter.clj
+++ b/src/clojure/contrib/pprint/ColumnWriter.clj
@@ -1,3 +1,8 @@
+;;; ColumnWriter.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,8 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements a column-aware wrapper around an instance of java.io.Writer
+
 (ns clojure.contrib.pprint.ColumnWriter
   (:gen-class
    :extends java.io.Writer
diff --git a/src/clojure/contrib/pprint/PrettyWriter.clj b/src/clojure/contrib/pprint/PrettyWriter.clj
index 710994a6..e192898e 100644
--- a/src/clojure/contrib/pprint/PrettyWriter.clj
+++ b/src/clojure/contrib/pprint/PrettyWriter.clj
@@ -1,3 +1,8 @@
+;;; PrettyWriter.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Jan 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements a wrapper around a java.io.Writer which implements the
+;; core of the XP algorithm.
+
 (ns clojure.contrib.pprint.PrettyWriter
   (:use clojure.contrib.pprint.utilities)
   (:gen-class
diff --git a/src/clojure/contrib/pprint/cl_format.clj b/src/clojure/contrib/pprint/cl_format.clj
index 26eda76c..69c39a32 100644
--- a/src/clojure/contrib/pprint/cl_format.clj
+++ b/src/clojure/contrib/pprint/cl_format.clj
@@ -1,3 +1,8 @@
+;;; cl-format.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,10 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements the Common Lisp compatible format function as documented
+;; in "Common Lisp the Language, 2nd edition", Chapter 22 (available online at:
+;; http://www.cs.cmu.edu/afs/cs.cmu.edu/project/ai-repository/ai/html/cltl/clm/node200.html#SECTION002633000000000000000)
+
 (in-ns 'clojure.contrib.pprint)
 
 ;;; Forward references
diff --git a/src/clojure/contrib/pprint/dispatch.clj b/src/clojure/contrib/pprint/dispatch.clj
index 5605a286..bfd5bb1a 100644
--- a/src/clojure/contrib/pprint/dispatch.clj
+++ b/src/clojure/contrib/pprint/dispatch.clj
@@ -1,3 +1,8 @@
+;;; dispatch.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Feb 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements the default dispatch tables for pretty printing code and
+;; data.
+
 (in-ns 'clojure.contrib.pprint)
 
 ;;; TODO: optimize/compile format strings in dispatch funcs
diff --git a/src/clojure/contrib/pprint/examples/hexdump.clj b/src/clojure/contrib/pprint/examples/hexdump.clj
index 0555b639..e7b4d49c 100644
--- a/src/clojure/contrib/pprint/examples/hexdump.clj
+++ b/src/clojure/contrib/pprint/examples/hexdump.clj
@@ -1,3 +1,8 @@
+;;; hexdump.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,11 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This example is a classic hexdump program written using cl-format.
+
+;; For some local color, it was written in Dulles Airport while waiting for a flight
+;; home to San Francisco.
+
 (ns clojure.contrib.pprint.examples.hexdump
   (:use clojure.contrib.pprint)
   (:gen-class (:main true)))
diff --git a/src/clojure/contrib/pprint/examples/multiply.clj b/src/clojure/contrib/pprint/examples/multiply.clj
index f8bfa91a..c7e33035 100644
--- a/src/clojure/contrib/pprint/examples/multiply.clj
+++ b/src/clojure/contrib/pprint/examples/multiply.clj
@@ -1,3 +1,8 @@
+;;; multiply.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,8 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This example prints a multiplication table using cl-format.
+
 (ns clojure.contrib.pprint.examples.multiply
   (:use clojure.contrib.pprint))
 
diff --git a/src/clojure/contrib/pprint/examples/props.clj b/src/clojure/contrib/pprint/examples/props.clj
index 876cedf8..4edb9149 100644
--- a/src/clojure/contrib/pprint/examples/props.clj
+++ b/src/clojure/contrib/pprint/examples/props.clj
@@ -1,3 +1,8 @@
+;;; props.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This example displays a nicely formatted table of the java properties using
+;; cl-format
+
 (ns clojure.contrib.pprint.examples.props
   (:use clojure.contrib.pprint))
 
diff --git a/src/clojure/contrib/pprint/examples/show_doc.clj b/src/clojure/contrib/pprint/examples/show_doc.clj
index e5897ce6..77c73a24 100644
--- a/src/clojure/contrib/pprint/examples/show_doc.clj
+++ b/src/clojure/contrib/pprint/examples/show_doc.clj
@@ -1,3 +1,8 @@
+;;; show_doc.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This example uses cl-format as part of a routine to display all the doc
+;; strings and function arguments from one or more namespaces.
+
 (ns clojure.contrib.pprint.examples.show-doc
   (:use clojure.contrib.pprint))
 
diff --git a/src/clojure/contrib/pprint/pprint_base.clj b/src/clojure/contrib/pprint/pprint_base.clj
index 71a57c8a..a27b09de 100644
--- a/src/clojure/contrib/pprint/pprint_base.clj
+++ b/src/clojure/contrib/pprint/pprint_base.clj
@@ -1,3 +1,8 @@
+;;; pprint_base.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Jan 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,8 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements the generic pretty print functions and special variables
+
 (in-ns 'clojure.contrib.pprint)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -89,7 +96,7 @@ pretty printing the results of macro expansions"}
       ;;:radix            *print-radix*,
       :readably         'clojure.core/*print-readably*,
       :right-margin     'clojure.contrib.pprint/*print-right-margin*,
-      :suppress-namespaces ''clojure.contrib.pprint/*print-suppress-namespaces*})
+      :suppress-namespaces 'clojure.contrib.pprint/*print-suppress-namespaces*})
 
 
 (defmacro #^{:private true} binding-map [amap & body]
diff --git a/src/clojure/contrib/pprint/utilities.clj b/src/clojure/contrib/pprint/utilities.clj
index 6d5cee91..128c66e5 100644
--- a/src/clojure/contrib/pprint/utilities.clj
+++ b/src/clojure/contrib/pprint/utilities.clj
@@ -1,3 +1,8 @@
+;;; utilities.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Jan 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,10 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This module implements some utility function used in formatting and pretty
+;; printing. The functions here could go in a more general purpose library,
+;; perhaps.
+
 (ns clojure.contrib.pprint.utilities)
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -91,5 +100,5 @@ beginning of aseq"
 (defmacro prlabel [prefix arg & more-args]
   "Print args to *err* in name = value format"
   `(prerr ~@(cons (list 'quote prefix) (mapcat #(list (list 'quote %) "=" %) 
-                                                  (cons arg more-args)))))
+                                                  (cons arg (seq more-args))))))
 
diff --git a/src/clojure/contrib/test_contrib/pprint/cl_format.clj b/src/clojure/contrib/test_contrib/pprint/cl_format.clj
index 716f7803..3de10959 100644
--- a/src/clojure/contrib/test_contrib/pprint/cl_format.clj
+++ b/src/clojure/contrib/test_contrib/pprint/cl_format.clj
@@ -1,3 +1,8 @@
+;;; cl_format.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Dec 2008. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,8 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This test set tests the basic cl-format functionality
+
 (ns clojure.contrib.test-contrib.pprint.cl-format
   (:refer-clojure :exclude [format])
   (:use [clojure.contrib.test-is :only (deftest are run-tests)]
diff --git a/src/clojure/contrib/test_contrib/pprint/helper.clj b/src/clojure/contrib/test_contrib/pprint/helper.clj
index 46b3e304..c7112e68 100644
--- a/src/clojure/contrib/test_contrib/pprint/helper.clj
+++ b/src/clojure/contrib/test_contrib/pprint/helper.clj
@@ -1,3 +1,8 @@
+;;; helper.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, April 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
@@ -6,6 +11,8 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
+;; This is just a macro to make my tests a little cleaner
+
 (ns clojure.contrib.test-contrib.pprint.helper
   (:use [clojure.contrib.test-is :only (deftest are run-tests)]))
 
diff --git a/src/clojure/contrib/test_contrib/pprint/pretty.clj b/src/clojure/contrib/test_contrib/pprint/pretty.clj
index dfe39240..89df9b24 100644
--- a/src/clojure/contrib/test_contrib/pprint/pretty.clj
+++ b/src/clojure/contrib/test_contrib/pprint/pretty.clj
@@ -1,3 +1,8 @@
+;;; pretty.clj -- part of the pretty printer for Clojure
+
+;; by Tom Faulhaber
+;; April 3, 2009
+
 ;   Copyright (c) Tom Faulhaber, Feb 2009. All rights reserved.
 ;   The use and distribution terms for this software are covered by the
 ;   Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)