Add :doc and :author metadata to core namespaces; fixes #216, fixes #217

Signed-off-by: Chouser <chouser@n01se.net>

13 files changed, 71 insertions, 297 deletions

diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj
index e37fe768..b48b6c64 100644
--- a/src/clj/clojure/core.clj
+++ b/src/clj/clojure/core.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.core)
+(ns #^{:doc "The core Clojure language."
+       :author "Rich Hickey"}
+  clojure.core)
 
 (def unquote)
 (def unquote-splicing)
diff --git a/src/clj/clojure/inspector.clj b/src/clj/clojure/inspector.clj
index 4e1ac077..d7f8f30f 100644
--- a/src/clj/clojure/inspector.clj
+++ b/src/clj/clojure/inspector.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.inspector
+(ns #^{:doc "Graphical object inspector for Clojure data structures."
+       :author "Rich Hickey"}
+    clojure.inspector
     (:import
      (java.awt BorderLayout)
      (java.awt.event ActionEvent ActionListener)
diff --git a/src/clj/clojure/main.clj b/src/clj/clojure/main.clj
index 8c2e9449..5f480a60 100644
--- a/src/clj/clojure/main.clj
+++ b/src/clj/clojure/main.clj
@@ -8,7 +8,9 @@
 
 ;; Originally contributed by Stephen C. Gilardi
 
-(ns clojure.main
+(ns #^{:doc "Top-level main function for Clojure REPL and scripts."
+       :author "Stephen C. Gilardi and Rich Hickey"}
+  clojure.main
   (:refer-clojure :exclude [with-bindings])
   (:import (clojure.lang Compiler Compiler$CompilerException
                          LineNumberingPushbackReader RT)))
diff --git a/src/clj/clojure/parallel.clj b/src/clj/clojure/parallel.clj
index 93c119ff..9b2f3b87 100644
--- a/src/clj/clojure/parallel.clj
+++ b/src/clj/clojure/parallel.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.parallel)
+(ns #^{:doc "DEPRECATED Wrapper of the ForkJoin library (JSR-166)."
+       :author "Rich Hickey"}
+    clojure.parallel)
 (alias 'parallel 'clojure.parallel)
 
 (comment "
diff --git a/src/clj/clojure/set.clj b/src/clj/clojure/set.clj
index 87113508..e881ebe9 100644
--- a/src/clj/clojure/set.clj
+++ b/src/clj/clojure/set.clj
@@ -6,7 +6,9 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.set)
+(ns #^{:doc "Set operations such as union/intersection."
+       :author "Rich Hickey"}
+       clojure.set)
 
 (defn- bubble-max-key [k coll]
   "Move a maximal element of coll according to fn k (which returns a number) 
diff --git a/src/clj/clojure/stacktrace.clj b/src/clj/clojure/stacktrace.clj
index 52d03b9b..ebe00aac 100644
--- a/src/clj/clojure/stacktrace.clj
+++ b/src/clj/clojure/stacktrace.clj
@@ -11,9 +11,8 @@
 ;; by Stuart Sierra
 ;; January 6, 2009
 
-(ns 
-  #^{:author "Stuart Sierra",
-     :doc "Print Clojure-centric stack traces"}
+(ns #^{:doc "Print stack traces oriented towards Clojure, not Java."
+       :author "Stuart Sierra"}
   clojure.stacktrace)
 
 (defn root-cause
diff --git a/src/clj/clojure/template.clj b/src/clj/clojure/template.clj
index d62390a6..f84e602a 100644
--- a/src/clj/clojure/template.clj
+++ b/src/clj/clojure/template.clj
@@ -22,8 +22,8 @@
 ;; December 15, 2008: first version
 
 
-(ns #^{:author "Stuart Sierra"
-       :doc "Macros that expand to repeated copies of a template expression."}
+(ns #^{:doc "Macros that expand to repeated copies of a template expression."
+       :author "Stuart Sierra"}
   clojure.template
   (:require [clojure.walk :as walk]))
 
diff --git a/src/clj/clojure/test.clj b/src/clj/clojure/test.clj
index 37cdd7e8..60a887eb 100644
--- a/src/clj/clojure/test.clj
+++ b/src/clj/clojure/test.clj
@@ -14,239 +14,10 @@
 ;; Thanks to Chas Emerick, Allen Rohner, and Stuart Halloway for
 ;; contributions and suggestions.
 
-
-
-(comment
-  ;; Inspired by many Common Lisp test frameworks and clojure/test,
-  ;; this file is a Clojure test framework.
-  ;;
-  ;;
-  ;;
-  ;; ASSERTIONS
-  ;;
-  ;; The core of the library is the "is" macro, which lets you make
-  ;; assertions of any arbitrary expression:
-
-  (is (= 4 (+ 2 2)))
-  (is (instance? Integer 256))
-  (is (.startsWith "abcde" "ab"))
-
-  ;; You can type an "is" expression directly at the REPL, which will
-  ;; print a message if it fails.
-  ;;
-  ;;     user> (is (= 5 (+ 2 2)))
-  ;;
-  ;;     FAIL in  (:1)
-  ;;     expected: (= 5 (+ 2 2))
-  ;;       actual: (not (= 5 4))
-  ;;     false
-  ;;
-  ;; The "expected:" line shows you the original expression, and the
-  ;; "actual:" shows you what actually happened.  In this case, it
-  ;; shows that (+ 2 2) returned 4, which is not = to 5.  Finally, the
-  ;; "false" on the last line is the value returned from the
-  ;; expression.  The "is" macro always returns the result of the
-  ;; inner expression.
-  ;;
-  ;; There are two special assertions for testing exceptions.  The
-  ;;  "(is (thrown? c ...))" form tests if an exception of class c is
-  ;;  thrown:
-
-  (is (thrown? ArithmeticException (/ 1 0))) 
-
-  ;; "(is (thrown-with-msg? c re ...))" does the same thing and also
-  ;; tests that the message on the exception matches the regular
-  ;; expression re:
-
-  (is (thrown-with-msg? ArithmeticException #"Divide by zero"
-                        (/ 1 0)))
-
-  ;;
-  ;;
-  ;;
-  ;; DOCUMENTING TESTS
-  ;;
-  ;; "is" takes an optional second argument, a string describing the
-  ;; assertion.  This message will be included in the error report.
-
-  (is (= 5 (+ 2 2)) "Crazy arithmetic")
-
-  ;; In addition, you can document groups of assertions with the
-  ;; "testing" macro, which takes a string followed by any number of
-  ;; assertions.  The string will be included in failure reports.
-  ;; Calls to "testing" may be nested, and all of the strings will be
-  ;; joined together with spaces in the final report, in a style
-  ;; similar to RSpec <http://rspec.info/>
-
-  (testing "Arithmetic"
-    (testing "with positive integers"
-      (is (= 4 (+ 2 2)))
-      (is (= 7 (+ 3 4))))
-    (testing "with negative integers"
-      (is (= -4 (+ -2 -2)))
-      (is (= -1 (+ 3 -4)))))
-
-  ;; Note that, unlike RSpec, the "testing" macro may only be used
-  ;; INSIDE a "deftest" or "with-test" form (see below).
-  ;;
-  ;;
-  ;;
-  ;; DEFINING TESTS
-  ;;
-  ;; There are two ways to define tests.  The "with-test" macro takes
-  ;; a defn or def form as its first argument, followed by any number
-  ;; of assertions.  The tests will be stored as metadata on the
-  ;; definition.
-
-  (with-test
-      (defn my-function [x y]
-        (+ x y))
-    (is (= 4 (my-function 2 2)))
-    (is (= 7 (my-function 3 4))))
-
-  ;; As of Clojure SVN rev. 1221, this does not work with defmacro.
-  ;; See http://code.google.com/p/clojure/issues/detail?id=51
-  ;;
-  ;; The other way lets you define tests separately from the rest of
-  ;; your code, even in a different namespace:
-
-  (deftest addition
-    (is (= 4 (+ 2 2)))
-    (is (= 7 (+ 3 4))))
-
-  (deftest subtraction
-    (is (= 1 (- 4 3)))
-    (is (= 3 (- 7 4))))
-
-  ;; This creates functions named "addition" and "subtraction", which
-  ;; can be called like any other function.  Therefore, tests can be
-  ;; grouped and composed, in a style similar to the test framework in
-  ;; Peter Seibel's "Practical Common Lisp"
-  ;; <http://www.gigamonkeys.com/book/practical-building-a-unit-test-framework.html>
-
-  (deftest arithmetic
-    (addition)
-    (subtraction))
-
-  ;; The names of the nested tests will be joined in a list, like
-  ;; "(arithmetic addition)", in failure reports.  You can use nested
-  ;; tests to set up a context shared by several tests.
-  ;;
-  ;;
-  ;;
-  ;; RUNNING TESTS
-  ;;
-  ;; Run tests with the function "(run-tests namespaces...)":
-
-  (run-tests 'your.namespace 'some.other.namespace)
-
-  ;; If you don't specify any namespaces, the current namespace is
-  ;; used.  To run all tests in all namespaces, use "(run-all-tests)".
-  ;;
-  ;; By default, these functions will search for all tests defined in
-  ;; a namespace and run them in an undefined order.  However, if you
-  ;; are composing tests, as in the "arithmetic" example above, you
-  ;; probably do not want the "addition" and "subtraction" tests run
-  ;; separately.  In that case, you must define a special function
-  ;; named "test-ns-hook" that runs your tests in the correct order:
-
-  (defn test-ns-hook []
-    (arithmetic))
-
-  ;;
-  ;;
-  ;;
-  ;; OMITTING TESTS FROM PRODUCTION CODE
-  ;;
-  ;; You can bind the variable "*load-tests*" to false when loading or
-  ;; compiling code in production.  This will prevent any tests from
-  ;; being created by "with-test" or "deftest".
-  ;;
-  ;;
-  ;;
-  ;; FIXTURES (new)
-  ;;
-  ;; Fixtures allow you to run code before and after tests, to set up
-  ;; the context in which tests should be run.
-  ;;
-  ;; A fixture is just a function that calls another function passed as
-  ;; an argument.  It looks like this:
-  (defn my-fixture [f]
-    ;; Perform setup, establish bindings, whatever.
-    (f) ;; Then call the function we were passed.
-    ;; Tear-down / clean-up code here.
-    )
-
-  ;; Fixtures are attached to namespaces in one of two ways.  "each"
-  ;; fixtures are run repeatedly, once for each test function created
-  ;; with "deftest" or "with-test".  "each" fixtures are useful for
-  ;; establishing a consistent before/after state for each test, like
-  ;; clearing out database tables.
-  ;;
-  ;; "each" fixtures can be attached to the current namespace like this:
-  (use-fixtures :each fixture1 fixture2 ...)
-  ;; The fixture1, fixture2 are just functions like the example above.
-  ;; They can also be anonymous functions, like this:
-  (use-fixtures :each (fn [f] setup... (f) cleanup...))
-  ;;
-  ;; The other kind of fixture, a "once" fixture, is only run once,
-  ;; around ALL the tests in the namespace.  "once" fixtures are useful
-  ;; for tasks that only need to be performed once, like establishing
-  ;; database connections, or for time-consuming tasks.
-  ;;
-  ;; Attach "once" fixtures to the current namespace like this:
-  (use-fixtures :once fixture1 fixture2 ...)
-  ;;
-  ;;
-  ;;
-  ;; SAVING TEST OUTPUT TO A FILE
-  ;;
-  ;; All the test reporting functions write to the var *test-out*.  By
-  ;; default, this is the same as *out*, but you can rebind it to any
-  ;; PrintWriter.  For example, it could be a file opened with
-  ;; clojure.contrib.duck-streams/writer.
-  ;;
-  ;;
-  ;;
-  ;; EXTENDING TEST-IS (ADVANCED)
-  ;;
-  ;; You can extend the behavior of the "is" macro by defining new
-  ;; methods for the "assert-expr" multimethod.  These methods are
-  ;; called during expansion of the "is" macro, so they should return
-  ;; quoted forms to be evaluated.
-  ;;
-  ;; You can plug in your own test-reporting framework by rebinding
-  ;; the "report" function: (report event)
-  ;;
-  ;; The 'event' argument is a map.  It will always have a :type key,
-  ;; whose value will be a keyword signaling the type of event being
-  ;; reported.  Standard events with :type value of :pass, :fail, and
-  ;; :error are called when an assertion passes, fails, and throws an
-  ;; exception, respectively.  In that case, the event will also have
-  ;; the following keys:
-  ;;
-  ;;   :expected   The form that was expected to be true
-  ;;   :actual     A form representing what actually occurred
-  ;;   :message    The string message given as an argument to 'is'
-  ;;
-  ;; The "testing" strings will be a list in "*testing-contexts*", and
-  ;; the vars being tested will be a list in "*testing-vars*".
-  ;;
-  ;; Your "report" function should wrap any printing calls in the
-  ;; "with-test-out" macro, which rebinds *out* to the current value
-  ;; of *test-out*.
-  ;;
-  ;; For additional event types, see the examples in the code below.
-
-  ) ;; end comment
-
-
-
 (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,
-   this file is a Clojure test framework.
+  Chas Emerick, Allen Rohner, and Stuart Halloway",
+     :doc "A unit testing framework.
 
    ASSERTIONS
 
diff --git a/src/clj/clojure/test/junit.clj b/src/clj/clojure/test/junit.clj
index c42887eb..a9844afb 100644
--- a/src/clj/clojure/test/junit.clj
+++ b/src/clj/clojure/test/junit.clj
@@ -13,28 +13,28 @@
 
 ;; DOCUMENTATION
 ;;
-;; This is an extension to clojure.test that adds support for
-;; JUnit-compatible XML output.
-;;
-;; JUnit (http://junit.org/) is the most popular unit-testing library
-;; for Java.  As such, tool support for JUnit output formats is
-;; common.  By producing compatible output from tests, this tool
-;; support can be exploited.
-;;
-;; To use, wrap any calls to clojure.test/run-tests in the
-;; with-junit-output macro, like this:
-;;
-;;   (use 'clojure.test)
-;;   (use 'clojure.contrib.test.junit)
-;;
-;;   (with-junit-output
-;;     (run-tests 'my.cool.library))
-;;
-;; To write the output to a file, rebind clojure.test/*test-out* to
-;; your own PrintWriter (perhaps opened using
-;; clojure.contrib.duck-streams/writer).
 
-(ns clojure.test.junit
+(ns #^{:doc "clojure.test extension for JUnit-compatible XML output.
+
+  JUnit (http://junit.org/) is the most popular unit-testing library
+  for Java.  As such, tool support for JUnit output formats is
+  common.  By producing compatible output from tests, this tool
+  support can be exploited.
+
+  To use, wrap any calls to clojure.test/run-tests in the
+  with-junit-output macro, like this:
+
+    (use 'clojure.test)
+    (use 'clojure.contrib.test.junit)
+
+    (with-junit-output
+      (run-tests 'my.cool.library))
+
+  To write the output to a file, rebind clojure.test/*test-out* to
+  your own PrintWriter (perhaps opened using
+  clojure.contrib.duck-streams/writer)."
+  :author "Jason Sankey"}
+  clojure.test.junit
   (:require [clojure.stacktrace :as stack]
             [clojure.test :as t]))
 
diff --git a/src/clj/clojure/test/tap.clj b/src/clj/clojure/test/tap.clj
index 11550db0..3e41f878 100644
--- a/src/clj/clojure/test/tap.clj
+++ b/src/clj/clojure/test/tap.clj
@@ -17,28 +17,28 @@
 
 ;; DOCUMENTATION
 ;;
-;; This is an extension to clojure.test that adds support
-;; for the Test Anything Protocol (TAP).  
-;;
-;; TAP is a simple text-based syntax for reporting test results.  TAP
-;; was originally develped for Perl, and now has implementations in
-;; several languages.  For more information on TAP, see
-;; http://testanything.org/ and
-;; http://search.cpan.org/~petdance/TAP-1.0.0/TAP.pm
-;;
-;; To use this library, wrap any calls to
-;; clojure.test/run-tests in the with-tap-output macro,
-;; like this:
-;;
-;;   (use 'clojure.test)
-;;   (use 'clojure.test.tap)
-;;
-;;   (with-tap-output
-;;    (run-tests 'my.cool.library))
 
 
 
-(ns clojure.test.tap
+(ns #^{:doc "clojure.test extensions for the Test Anything Protocol (TAP)
+
+  TAP is a simple text-based syntax for reporting test results.  TAP
+  was originally develped for Perl, and now has implementations in
+  several languages.  For more information on TAP, see
+  http://testanything.org/ and
+  http://search.cpan.org/~petdance/TAP-1.0.0/TAP.pm
+
+  To use this library, wrap any calls to
+  clojure.test/run-tests in the with-tap-output macro,
+  like this:
+
+    (use 'clojure.test)
+    (use 'clojure.test.tap)
+
+    (with-tap-output
+     (run-tests 'my.cool.library))"
+       :author "Stuart Sierra"}
+  clojure.test.tap
   (:require [clojure.test :as t]
             [clojure.stacktrace :as stack]))
 
diff --git a/src/clj/clojure/walk.clj b/src/clj/clojure/walk.clj
index 6b5bad90..b025705f 100644
--- a/src/clj/clojure/walk.clj
+++ b/src/clj/clojure/walk.clj
@@ -11,17 +11,6 @@
 ;; by Stuart Sierra
 ;; December 15, 2008
 
-;; This file defines a generic tree walker for Clojure data
-;; structures.  It takes any data structure (list, vector, map, set,
-;; seq), calls a function on every element, and uses the return value
-;; of the function in place of the original.  This makes it fairly
-;; easy to write recursive search-and-replace functions, as shown in
-;; the examples.
-;;
-;; Note: "walk" supports all Clojure data structures EXCEPT maps
-;; created with sorted-map-by.  There is no (obvious) way to retrieve
-;; the sorting function.
-;;
 ;; CHANGE LOG:
 ;;
 ;; * December 15, 2008: replaced 'walk' with 'prewalk' & 'postwalk'
diff --git a/src/clj/clojure/xml.clj b/src/clj/clojure/xml.clj
index caac770a..ba14d4c7 100644
--- a/src/clj/clojure/xml.clj
+++ b/src/clj/clojure/xml.clj
@@ -6,9 +6,11 @@
 ;   the terms of this license.
 ;   You must not remove this notice, or any other, from this software.
 
-(ns clojure.xml
-    (:import (org.xml.sax ContentHandler Attributes SAXException)
-             (javax.xml.parsers SAXParser SAXParserFactory)))
+(ns #^{:doc "XML reading/writing."
+       :author "Rich Hickey"}
+  clojure.xml
+  (:import (org.xml.sax ContentHandler Attributes SAXException)
+           (javax.xml.parsers SAXParser SAXParserFactory)))
 
 (def *stack*)
 (def *current*)
diff --git a/src/clj/clojure/zip.clj b/src/clj/clojure/zip.clj
index 54e8f180..8896812b 100644
--- a/src/clj/clojure/zip.clj
+++ b/src/clj/clojure/zip.clj
@@ -9,8 +9,11 @@
 ;functional hierarchical zipper, with navigation, editing and enumeration
 ;see Huet
 
-(ns clojure.zip
-    (:refer-clojure :exclude (replace remove next)))
+(ns #^{:doc "Functional hierarchical zipper, with navigation, editing, 
+  and enumeration.  See Huet"
+       :author "Rich Hickey"}
+  clojure.zip
+  (:refer-clojure :exclude (replace remove next)))
 
 (defn zipper
   "Creates a new zipper structure.