Lots 'o doc strings

35 files changed, 517 insertions, 43 deletions

diff --git a/src/clojure/contrib/condt.clj b/src/clojure/contrib/condt.clj
index fbd76cc0..b5ac4da4 100644
--- a/src/clojure/contrib/condt.clj
+++ b/src/clojure/contrib/condt.clj
@@ -23,8 +23,8 @@
 
 
 (ns 
-    #{:author "Stuart Sierra"
-      :doc "Generic case-like macro using template expressions"}
+    #^{:author "Stuart Sierra"
+       :doc "Generic case-like macro using template expressions"}
     clojure.contrib.condt
     (:require clojure.contrib.template))
 
diff --git a/src/clojure/contrib/duck_streams.clj b/src/clojure/contrib/duck_streams.clj
index 8f57e67d..60241910 100644
--- a/src/clojure/contrib/duck_streams.clj
+++ b/src/clojure/contrib/duck_streams.clj
@@ -90,7 +90,8 @@
   local file names.  Uses *default-encoding* as the text encoding.
 
   Should be used inside with-open to ensure the Reader is properly
-  closed."}
+  closed."
+             :arglists '([x])}
   reader class)
 
 (defmethod reader Reader [x]
@@ -132,7 +133,8 @@
   local file names.
 
   Should be used inside with-open to ensure the Writer is properly
-  closed."}
+  closed."
+             :arglists '([x])}
   writer class)
 
 (defmethod writer PrintWriter [x] x)
diff --git a/src/clojure/contrib/graph.clj b/src/clojure/contrib/graph.clj
index f3ca4f3d..0be6420c 100644
--- a/src/clojure/contrib/graph.clj
+++ b/src/clojure/contrib/graph.clj
@@ -14,7 +14,10 @@
 ;;  Created 23 June 2009
 
 
-(ns clojure.contrib.graph
+(ns 
+  #^{:author "Jeffrey Straszheim",
+     :doc "Basic graph theory algorithms"}
+  clojure.contrib.graph
   (use [clojure.set :only (union)]))
 
 
diff --git a/src/clojure/contrib/greatest_least.clj b/src/clojure/contrib/greatest_least.clj
index 10c7eae6..79e41813 100644
--- a/src/clojure/contrib/greatest_least.clj
+++ b/src/clojure/contrib/greatest_least.clj
@@ -1,4 +1,7 @@
-(ns clojure.contrib.greatest-least)
+(ns 
+  #^{:author "Vincent Foley",
+     :doc "Various functions for finding greatest and least values in a collection"}
+  clojure.contrib.greatest-least)
 
 (defn- boundary
   [cmp-fn f & args]
diff --git a/src/clojure/contrib/import_static.clj b/src/clojure/contrib/import_static.clj
index e7a35ea4..94d827a5 100644
--- a/src/clojure/contrib/import_static.clj
+++ b/src/clojure/contrib/import_static.clj
@@ -13,7 +13,10 @@
 
 
 
-(ns clojure.contrib.import-static
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Import static Java methods/fields into Clojure"}
+  clojure.contrib.import-static
             (:use clojure.set))
 
 (defmacro import-static
diff --git a/src/clojure/contrib/jar.clj b/src/clojure/contrib/jar.clj
index 7eab2f5e..de979bba 100644
--- a/src/clojure/contrib/jar.clj
+++ b/src/clojure/contrib/jar.clj
@@ -12,7 +12,10 @@
 ;; remove this notice, or any other, from this software.
 
 
-(ns clojure.contrib.jar
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Utilities for working with Java JAR files"}
+  clojure.contrib.jar
   (:import (java.io File)
            (java.util.jar JarFile)))
 
diff --git a/src/clojure/contrib/java_utils.clj b/src/clojure/contrib/java_utils.clj
index 0ac39ece..0f7221e4 100644
--- a/src/clojure/contrib/java_utils.clj
+++ b/src/clojure/contrib/java_utils.clj
@@ -31,7 +31,29 @@
 ;   Shawn Hoover
 ;   Perry Trolard
 
-(ns clojure.contrib.java-utils
+(ns 
+  #^{:author "Stuart Halloway, Stephen C. Gilardi, Shawn Hoover, Perry Trolard",
+     :doc "A set of utilties for dealing with Java stuff like files and properties.
+
+   Design goals:
+
+   (1) Ease-of-use. These APIs should be convenient. Performance is secondary.
+
+   (2) Duck typing. I hate having to think about the difference between
+       a string that names a file, and a File. Ditto for a ton of other 
+       wrapper classes in the Java world (URL, InternetAddress). With these
+       APIs you should be able to think about domain equivalence, not type
+       equivalence.
+
+   (3) No bossiness. I am not marking any of these functions as private
+       the docstrings will tell you the intended usage but do what works for you. 					
+
+   Feedback welcome!
+
+   If something in this module violates the principle of least surprise, please 
+   let me (Stu) and the Clojure community know via the mailing list.
+"}
+  clojure.contrib.java-utils
   (:import [java.io File]
 	   [java.util Properties]))
 
@@ -135,4 +157,4 @@
 
 
   
-     
\ No newline at end of file
+     
diff --git a/src/clojure/contrib/javadoc/browse.clj b/src/clojure/contrib/javadoc/browse.clj
index 6bf2bb58..2686f64e 100644
--- a/src/clojure/contrib/javadoc/browse.clj
+++ b/src/clojure/contrib/javadoc/browse.clj
@@ -9,7 +9,10 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.contrib.javadoc.browse
+(ns 
+  #^{:author "Start a web browser from Clojure",
+     :doc "Christophe Grand"}
+  clojure.contrib.javadoc.browse
   (:require [clojure.contrib.shell-out :as sh]) 
   (:import (java.net URI)))
 
diff --git a/src/clojure/contrib/javalog.clj b/src/clojure/contrib/javalog.clj
index 63ce7235..43b558c7 100644
--- a/src/clojure/contrib/javalog.clj
+++ b/src/clojure/contrib/javalog.clj
@@ -31,7 +31,10 @@
 ;; <http://commons.apache.org/logging/>, which has a nicer API.
 
 
-(ns clojure.contrib.javalog
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Convenient access to java.util.logging in Clojure"}
+  clojure.contrib.javalog
             (:import 
              (java.util.logging Logger Level ConsoleHandler
                                 FileHandler SimpleFormatter)))
diff --git a/src/clojure/contrib/json/read.clj b/src/clojure/contrib/json/read.clj
index 7276e089..084f2a12 100644
--- a/src/clojure/contrib/json/read.clj
+++ b/src/clojure/contrib/json/read.clj
@@ -30,7 +30,19 @@
 
 
 
-(ns clojure.contrib.json.read
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "JavaScript Object Notation (JSON) parser
+
+           For more information on JSON, see http://www.json.org/
+
+           This library parses data in JSON format.  This is a fairly strict
+           implementation of JSON as described at json.org, not a full-fledged
+           JavaScript parser.  JavaScript functions and object constructors
+           are not supported.  Object field names must be quoted strings; they
+           may not be bare symbols.",
+     :see-also ["http://www.json.org", "JSON Home Page"]}
+  clojure.contrib.json.read
   (:import (java.io PushbackReader StringReader EOFException))
   (:use [clojure.contrib.test-is :only (deftest- is)]))
 
diff --git a/src/clojure/contrib/json/write.clj b/src/clojure/contrib/json/write.clj
index 6983ad78..2d149021 100644
--- a/src/clojure/contrib/json/write.clj
+++ b/src/clojure/contrib/json/write.clj
@@ -17,14 +17,19 @@
 
 
 
-(ns clojure.contrib.json.write
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "JavaScript Object Notation (JSON) generator",
+     :see-also ["http://www.json.org", "JSON Home Page"]}
+  clojure.contrib.json.write
   (:use [clojure.contrib.test-is :only (deftest- is)]))
 
 (defmulti
   #^{:doc "Prints Clojure data types as JSON.  Nil becomes JSON null.
   Keywords become strings, without the leading colon.  Maps become
   JSON objects, all other collection types become JSON arrays.
-  Strings and numbers print as with pr."}
+  Strings and numbers print as with pr."
+     :arglists '([x])}
   print-json (fn [x]
                (cond (nil? x) nil
                      (map? x) :object
diff --git a/src/clojure/contrib/lazy_seqs.clj b/src/clojure/contrib/lazy_seqs.clj
index 17ffd5c3..91b2e831 100644
--- a/src/clojure/contrib/lazy_seqs.clj
+++ b/src/clojure/contrib/lazy_seqs.clj
@@ -30,7 +30,28 @@
 ;;  scgilardi (gmail)
 ;;  Created 07 June 2008
 
-(ns clojure.contrib.lazy-seqs
+(ns 
+  #^{:author "Stephen C. Gilardi",
+     :doc "==== Lazy sequences ====
+
+ primes - based on the \"naive\" implemention described in [1] plus a
+          small \"wheel\" which eliminates multiples of 2, 3, 5, and
+          7 from consideration by incrementing past them. Also inspired
+          by code from Christophe Grand in [2].
+
+ fibs   - all the Fibonacci numbers
+
+ powers-of-2 - all the powers of 2
+
+ ==== Lazy sequence functions ====
+
+ (rotations, partition-all, shuffle, rand-elt  moved to seq_utils.clj)
+ (permutations and combinations moved to combinatorics.clj)
+
+ [1] http://www.cs.hmc.edu/~oneill/papers/Sieve-JFP.pdf
+ [2] http://clj-me.blogspot.com/2008/06/primes.html
+"}
+  clojure.contrib.lazy-seqs
   (:use clojure.contrib.def))
 
 ; primes cannot be written efficiently as a function, because
diff --git a/src/clojure/contrib/lazy_xml.clj b/src/clojure/contrib/lazy_xml.clj
index 72b6c5a5..fe1ef8f3 100644
--- a/src/clojure/contrib/lazy_xml.clj
+++ b/src/clojure/contrib/lazy_xml.clj
@@ -8,7 +8,10 @@
 
 ; Functions to parse xml lazily and emit back to text.
 
-(ns clojure.contrib.lazy-xml
+(ns 
+    #^{:author "Chris Houser",
+       :doc "Functions to parse xml lazily and emit back to text."}
+    clojure.contrib.lazy-xml
     (:require [clojure.xml :as xml])
     (:import (org.xml.sax Attributes InputSource)
              (org.xml.sax.helpers DefaultHandler)
diff --git a/src/clojure/contrib/map_utils.clj b/src/clojure/contrib/map_utils.clj
index 3862fcee..4adf3068 100644
--- a/src/clojure/contrib/map_utils.clj
+++ b/src/clojure/contrib/map_utils.clj
@@ -13,7 +13,10 @@
 ;;  jason at w01fe dot com
 ;;  Created 25 Feb 2009
 
-(ns clojure.contrib.map-utils)
+(ns 
+  #^{:author "Jason Wolfe, Chris Houser",
+     :doc "Utilities for operating on Clojure maps."}
+  clojure.contrib.map-utils)
 
 
 (defmacro lazy-get 
@@ -36,7 +39,7 @@
 
 ; by Chouser:
 (defn deep-merge-with
-  "Like merge-with, but merges maps recursively, appling the given fn
+  "Like merge-with, but merges maps recursively, applying the given fn
   only when there's a non-map at a particular level.
 
   (deepmerge + {:a {:b {:c 1 :d {:x 1 :y 2}} :e 3} :f 4}
diff --git a/src/clojure/contrib/math.clj b/src/clojure/contrib/math.clj
index d7937745..cef32bf2 100644
--- a/src/clojure/contrib/math.clj
+++ b/src/clojure/contrib/math.clj
@@ -43,7 +43,51 @@
 ;;   returns [s r] where k = s^2+r and k < (s+1)^2.  In other words, it

 ;;   returns the floor of the square root and the "remainder".

 

-(ns clojure.contrib.math)

+(ns 

+  #^{:author "Mark Engelberg",

+     :doc "Math functions that deal intelligently with the various

+types in Clojure's numeric tower, as well as math functions

+commonly found in Scheme implementations.

+

+expt - (expt x y) is x to the yth power, returns an exact number

+  if the base is an exact number, and the power is an integer,

+  otherwise returns a double.

+abs - (abs n) is the absolute value of n

+gcd - (gcd m n) returns the greatest common divisor of m and n

+lcm - (lcm m n) returns the least common multiple of m and n

+

+The behavior of the next three functions on doubles is consistent

+with the behavior of the corresponding functions

+in Java's Math library, but on exact numbers, returns an integer.

+

+floor - (floor n) returns the greatest integer less than or equal to n.

+  If n is an exact number, floor returns an integer,

+  otherwise a double.

+ceil - (ceil n) returns the least integer greater than or equal to n.

+  If n is an exact number, ceil returns an integer,

+  otherwise a double.

+round - (round n) rounds to the nearest integer.

+  round always returns an integer.  round rounds up for values

+  exactly in between two integers.

+

+

+sqrt - Implements the sqrt behavior I'm accustomed to from PLT Scheme,

+  specifically, if the input is an exact number, and is a square

+  of an exact number, the output will be exact.  The downside

+  is that for the common case (inexact square root), some extra

+  computation is done to look for an exact square root first.

+  So if you need blazingly fast square root performance, and you

+  know you're just going to need a double result, you're better

+  off calling java's Math/sqrt, or alternatively, you could just

+  convert your input to a double before calling this sqrt function.

+  If Clojure ever gets complex numbers, then this function will

+  need to be updated (so negative inputs yield complex outputs).

+exact-integer-sqrt - Implements a math function from the R6RS Scheme

+  standard.  (exact-integer-sqrt k) where k is a non-negative integer,

+  returns [s r] where k = s^2+r and k < (s+1)^2.  In other words, it

+  returns the floor of the square root and the "remainder".

+"}

+  clojure.contrib.math)

 

 (derive ::integer ::exact)

 (derive java.lang.Integer ::integer)

diff --git a/src/clojure/contrib/miglayout.clj b/src/clojure/contrib/miglayout.clj
index e841a450..32fd7e17 100644
--- a/src/clojure/contrib/miglayout.clj
+++ b/src/clojure/contrib/miglayout.clj
@@ -19,7 +19,18 @@
 ;;  scgilardi (gmail)
 ;;  Created 5 October 2008
 
-(ns clojure.contrib.miglayout
+(ns 
+  #^{:author "Stephen C. Gilardi",
+     :doc "Clojure support for the MiGLayout layout manager
+http://www.miglayout.com/
+
+Example:
+
+  (use '[clojure.contrib.miglayout.test :as mlt :only ()])
+  (doseq [i (range 3)] (mlt/run-test i))
+
+"}
+  clojure.contrib.miglayout
   (:import (java.awt Container Component)
            (net.miginfocom.swing MigLayout))
   (:use clojure.contrib.miglayout.internal))
diff --git a/src/clojure/contrib/mmap.clj b/src/clojure/contrib/mmap.clj
index 70d96a52..341c27e3 100644
--- a/src/clojure/contrib/mmap.clj
+++ b/src/clojure/contrib/mmap.clj
@@ -9,7 +9,11 @@
 ; Functions for memory-mapping files, plus some functions that use a
 ; mmaped file for "normal" activies -- slurp, load-file, etc.
 
-(ns clojure.contrib.mmap
+(ns 
+  #^{:author "Chris Houser",
+     :doc "Functions for memory-mapping files, plus some functions that use a
+mmaped file for \"normal\" activies -- slurp, load-file, etc."}
+  clojure.contrib.mmap
     (:refer-clojure :exclude (slurp load-file))
     (:import (java.nio ByteBuffer CharBuffer)
              (java.io PushbackReader InputStream InputStreamReader
diff --git a/src/clojure/contrib/ns_utils.clj b/src/clojure/contrib/ns_utils.clj
index a5c904fc..7a866d5a 100644
--- a/src/clojure/contrib/ns_utils.clj
+++ b/src/clojure/contrib/ns_utils.clj
@@ -36,7 +36,10 @@
 ;;  scgilardi (gmail)
 ;;  23 April 2008
 
-(ns clojure.contrib.ns-utils
+(ns 
+  #^{:author "Stephen C. Gilardi",
+     :doc "Namespace utilities"}
+  clojure.contrib.ns-utils
   (:use clojure.contrib.except))
 
 ;; Namespace Utilities
diff --git a/src/clojure/contrib/prxml.clj b/src/clojure/contrib/prxml.clj
index b056e1f1..a2362223 100755
--- a/src/clojure/contrib/prxml.clj
+++ b/src/clojure/contrib/prxml.clj
@@ -22,7 +22,11 @@
 ;; See function "prxml" at the bottom of this file for documentation.
 
 
-(ns clojure.contrib.prxml
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Compact syntax for generating XML. See the documentation of \"prxml\" 
+for details."}
+  clojure.contrib.prxml
   (:use [clojure.contrib.lazy-xml :only (escape-xml)]))
 
 (def
diff --git a/src/clojure/contrib/repl_ln.clj b/src/clojure/contrib/repl_ln.clj
index bf9a66b2..cf67cec2 100644
--- a/src/clojure/contrib/repl_ln.clj
+++ b/src/clojure/contrib/repl_ln.clj
@@ -12,7 +12,11 @@
 ;;  scgilardi (gmail)
 ;;  Created 28 November 2008
 
-(ns clojure.contrib.repl-ln
+(ns 
+  #^{:author "Stephen C. Gilardi",
+     :doc "A repl with that provides support for lines and line numbers in the
+           input stream."}
+  clojure.contrib.repl-ln
   (:gen-class)
   (:import (clojure.lang Compiler LineNumberingPushbackReader RT Var)
            (java.io InputStreamReader OutputStreamWriter PrintWriter)
diff --git a/src/clojure/contrib/repl_utils.clj b/src/clojure/contrib/repl_utils.clj
index 14e14c70..76730aae 100644
--- a/src/clojure/contrib/repl_utils.clj
+++ b/src/clojure/contrib/repl_utils.clj
@@ -8,7 +8,10 @@
 
 ; Utilities meant to be used interactively at the REPL
 
-(ns clojure.contrib.repl-utils
+(ns 
+  #^{:author "Chris Houser",
+     :doc "Utilities meant to be used interactively at the REPL"}
+  clojure.contrib.repl-utils
   (:import (java.io File LineNumberReader InputStreamReader PushbackReader)
            (java.lang.reflect Modifier Method Constructor)
            (clojure.lang RT))
diff --git a/src/clojure/contrib/seq_utils.clj b/src/clojure/contrib/seq_utils.clj
index 01f260a9..b1eb83e5 100644
--- a/src/clojure/contrib/seq_utils.clj
+++ b/src/clojure/contrib/seq_utils.clj
@@ -21,7 +21,10 @@
 ;;   functions; see discussion at http://groups.google.com/group/clojure/browse_thread/thread/8b2c8dc96b39ddd7/a8866d34b601ff43
 
 
-(ns clojure.contrib.seq-utils)
+(ns 
+  #^{:author "Stuart Sierra (and others)",
+     :doc "Sequence utilities for Clojure"}
+  clojure.contrib.seq-utils)
 
 
 ;; 'flatten' written by Rich Hickey,
@@ -149,7 +152,7 @@
   (nth s (rand-int (count s))))
 
 
-;; seq-on writte by Konrad Hinsen
+;; seq-on written by Konrad Hinsen
 (defmulti seq-on
   "Returns a seq on the object s. Works like the built-in seq but as
    a multimethod that can have implementations for new classes and types."
diff --git a/src/clojure/contrib/server_socket.clj b/src/clojure/contrib/server_socket.clj
index 4c9f6d65..77f722e2 100644
--- a/src/clojure/contrib/server_socket.clj
+++ b/src/clojure/contrib/server_socket.clj
@@ -8,7 +8,10 @@
 
 ;;  Server socket library - includes REPL on socket
 
-(ns clojure.contrib.server-socket
+(ns 
+  #^{:author "Craig McDaniel",
+     :doc "Server socket library - includes REPL on socket"}
+  clojure.contrib.server-socket
   (:import (java.net InetAddress ServerSocket Socket SocketException)
            (java.io InputStreamReader OutputStream OutputStreamWriter PrintWriter)
            (clojure.lang LineNumberingPushbackReader))
diff --git a/src/clojure/contrib/set.clj b/src/clojure/contrib/set.clj
index 67a46e82..75c00018 100644
--- a/src/clojure/contrib/set.clj
+++ b/src/clojure/contrib/set.clj
@@ -13,7 +13,10 @@
 ;;  jason at w01fe dot com
 ;;  Created 2 Feb 2009
 
-(ns clojure.contrib.set)
+(ns 
+  #^{:author "Jason Wolfe",
+     :doc "Clojure functions for operating on sets (supplemental to clojure.set)"}
+  clojure.contrib.set)
 
 (defn subset? 
   "Is set1 a subset of set2?"
diff --git a/src/clojure/contrib/shell_out.clj b/src/clojure/contrib/shell_out.clj
index 1ee7b230..874a1999 100644
--- a/src/clojure/contrib/shell_out.clj
+++ b/src/clojure/contrib/shell_out.clj
@@ -11,7 +11,11 @@
 ; Conveniently launch a sub-process providing to its stdin and
 ; collecting its stdout
 
-(ns clojure.contrib.shell-out
+(ns 
+  #^{:author "Chris Houser",
+     :doc "Conveniently launch a sub-process providing to its stdin and
+collecting its stdout"}
+  clojure.contrib.shell-out
   (:import (java.io InputStreamReader OutputStreamWriter)))
 
 (def *sh-dir* nil)
diff --git a/src/clojure/contrib/singleton.clj b/src/clojure/contrib/singleton.clj
index 02b89f3b..b10223ff 100644
--- a/src/clojure/contrib/singleton.clj
+++ b/src/clojure/contrib/singleton.clj
@@ -20,7 +20,10 @@
 ;; April 9, 2009: initial version
 
 
-(ns clojure.contrib.singleton)
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Singleton functions"}
+  clojure.contrib.singleton)
 
 (defn global-singleton
   "Returns a global singleton function.  f is a function of no
diff --git a/src/clojure/contrib/sql.clj b/src/clojure/contrib/sql.clj
index 1ecdd605..677d598d 100644
--- a/src/clojure/contrib/sql.clj
+++ b/src/clojure/contrib/sql.clj
@@ -15,7 +15,14 @@
 ;;  scgilardi (gmail)
 ;;  Created 2 April 2008
 
-(ns clojure.contrib.sql
+(ns 
+  #^{:author "Stephen C. Gilardi",
+     :doc "A Clojure interface to sql databases via jdbc
+
+           See clojure.contrib.sql.test for an example"
+     :see-also [["http://code.google.com/p/clojure-contrib/source/browse/trunk/src/clojure/contrib/sql/test.clj" 
+                 "Example code"]]}
+  clojure.contrib.sql
   (:use (clojure.contrib
          [def :only (defalias)]
          [java-utils :only (as-str)])
diff --git a/src/clojure/contrib/stacktrace.clj b/src/clojure/contrib/stacktrace.clj
index c412b119..7330ef47 100644
--- a/src/clojure/contrib/stacktrace.clj
+++ b/src/clojure/contrib/stacktrace.clj
@@ -12,7 +12,10 @@
 ;; remove this notice, or any other, from this software.
 
 
-(ns clojure.contrib.stacktrace)
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Print Clojure-centric stack traces"}
+  clojure.contrib.stacktrace)
 
 (defn root-cause
   "Returns the last 'cause' Throwable in a chain of Throwables."
diff --git a/src/clojure/contrib/str_utils.clj b/src/clojure/contrib/str_utils.clj
index 23a9a3b7..02bf7445 100644
--- a/src/clojure/contrib/str_utils.clj
+++ b/src/clojure/contrib/str_utils.clj
@@ -12,8 +12,11 @@
 ;; remove this notice, or any other, from this software.
 
 
-(ns clojure.contrib.str-utils
-    (:import (java.util.regex Pattern)))
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "String utilities for Clojure"}
+  clojure.contrib.str-utils
+  (:import (java.util.regex Pattern)))
 
 (defn re-split
   "Splits the string on instances of 'pattern'.  Returns a sequence of
diff --git a/src/clojure/contrib/template.clj b/src/clojure/contrib/template.clj
index 62c697b6..f5049289 100644
--- a/src/clojure/contrib/template.clj
+++ b/src/clojure/contrib/template.clj
@@ -71,8 +71,53 @@
 
 
 
-(ns clojure.contrib.template
-    (:use clojure.contrib.walk))
+(ns 
+  #^{:author "Stuart Sierra",
+     :doc "Anonymous functions that pre-evaluate sub-expressions
+
+           This file defines macros for using template expressions.  These are
+           useful for writing macros.
+
+           A template is an expression containing \"holes\" represented by the
+           symbols _1, _2, _3, and so on.  (\"_\" is a synonym for \"_1\".)
+
+           The \"template\" macro is similar to #().  It returns an anonymous
+           function containing the body of the template.  Unlike #() or \"fn\",
+           however, any expressions that do not have any holes will be
+           evaluated only once, at the time the function is created, not every
+           time the function is called.
+
+           Examples:
+
+           Assume we have some big, slow calculation.
+             (defn think-hard []
+               (Thread/sleep 1000)
+               1000)
+
+           With #(), think-hard gets called every time.
+             (time (doall (map #(+ % (think-hard))
+                               (range 5))))
+             => \"Elapsed time: 5001.33455 msecs\"
+             => (1000 1001 1002 1003 1004)
+
+           With a template, think-hard only gets called once.
+             (time (doall (map (template (+ _ (think-hard)))
+                               (range 5))))
+             => \"Elapsed time: 1000.907326 msecs\"
+             => (1000 1001 1002 1003 1004)
+
+           There is also the do-template macro, which works differently.  It
+           calls the same template multiple times, filling in values, and puts
+           it all inside a \"do\" block.  It will split up the values based on
+           the number of holes in the template.
+
+             (do-template (foo _1 _2) :a :b :c :d)
+             expands to: (do (foo :a :b) (foo :c :d))
+
+             (do-template (foo _1 _2 _3) 10 11 12 13 14 15)
+             expands to: (foo 10 11 12) (foo 13 14 15)"}
+  clojure.contrib.template
+  (:use clojure.contrib.walk))
 
 (defn find-symbols
   "Recursively finds all symbols in form."
diff --git a/src/clojure/contrib/test_is.clj b/src/clojure/contrib/test_is.clj
index 31a65dda..5ccd60a6 100644
--- a/src/clojure/contrib/test_is.clj
+++ b/src/clojure/contrib/test_is.clj
@@ -242,7 +242,224 @@
 
 
 
-(ns clojure.contrib.test-is
+(ns 
+  #^{:author "Stuart Sierra, with contributions and suggestions by 
+Chas Emerick, Allen Rohner, and Stuart Halloway",
+     :doc "Inspired by many Common Lisp test frameworks and clojure/test,