From d7cc05cf0ecc4c5ea1c4c73dcfec89fa12c62c75 Mon Sep 17 00:00:00 2001 From: Chouser Date: Wed, 2 Dec 2009 09:44:34 -0500 Subject: [PATCH 1/6] Add branch name "master" to version.properties --- src/clj/clojure/version.properties | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/clj/clojure/version.properties b/src/clj/clojure/version.properties index b76abd0ce4..c14aa8f2b9 100644 --- a/src/clj/clojure/version.properties +++ b/src/clj/clojure/version.properties @@ -1,5 +1,5 @@ clojure.version.major=1 clojure.version.minor=1 clojure.version.incremental=0 -clojure.version.qualifier=alpha +clojure.version.qualifier=master clojure.version.interim=true From 20e4e45f18b8cd9833846aa8cf441ceebd98cca8 Mon Sep 17 00:00:00 2001 From: Stuart Sierra Date: Thu, 3 Dec 2009 15:25:00 -0500 Subject: [PATCH 2/6] Remove deprecated ^ reader macro from core sources; refs #215 Signed-off-by: Chouser --- src/clj/clojure/core.clj | 24 ++++++++++++------------ src/clj/clojure/genclass.clj | 2 +- src/clj/clojure/zip.clj | 28 ++++++++++++++-------------- 3 files changed, 27 insertions(+), 27 deletions(-) diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj index 89929e02ac..0d314a5a8d 100644 --- a/src/clj/clojure/core.clj +++ b/src/clj/clojure/core.clj @@ -2943,7 +2943,7 @@ conds (when (and (next body) (map? (first body))) (first body)) body (if conds (next body) body) - conds (or conds ^params) + conds (or conds (meta params)) pre (:pre conds) post (:post conds) body (if post @@ -3172,7 +3172,7 @@ "test [v] finds fn at key :test in var metadata and calls it, presuming failure will throw exception" [v] - (let [f (:test ^v)] + (let [f (:test (meta v))] (if f (do (f) :ok) :no-test))) @@ -3254,11 +3254,11 @@ (defn print-doc [v] (println "-------------------------") - (println (str (ns-name (:ns ^v)) "/" (:name ^v))) - (prn (:arglists ^v)) - (when (:macro ^v) + (println (str (ns-name (:ns (meta v))) "/" (:name (meta v)))) + (prn (:arglists (meta v))) + (when (:macro (meta v)) (println "Macro")) - (println " " (:doc ^v))) + (println " " (:doc (meta v)))) (defn find-doc "Prints documentation for any var whose documentation or name @@ -3267,9 +3267,9 @@ (let [re (re-pattern re-string-or-pattern)] (doseq [ns (all-ns) v (sort-by (comp :name meta) (vals (ns-interns ns))) - :when (and (:doc ^v) - (or (re-find (re-matcher re (:doc ^v))) - (re-find (re-matcher re (str (:name ^v))))))] + :when (and (:doc (meta v)) + (or (re-find (re-matcher re (:doc (meta v)))) + (re-find (re-matcher re (str (:name (meta v)))))))] (print-doc v)))) (defn special-form-anchor @@ -3297,7 +3297,7 @@ [nspace] (println "-------------------------") (println (str (ns-name nspace))) - (println " " (:doc ^nspace))) + (println " " (:doc (meta nspace)))) (defmacro doc "Prints documentation for a var or special form given its name" @@ -4307,11 +4307,11 @@ metadata from the name symbol. Returns the var." ([ns #^clojure.lang.Symbol name] (let [v (clojure.lang.Var/intern (the-ns ns) name)] - (when ^name (.setMeta v ^name)) + (when (meta name) (.setMeta v (meta name))) v)) ([ns name val] (let [v (clojure.lang.Var/intern (the-ns ns) name val)] - (when ^name (.setMeta v ^name)) + (when (meta name) (.setMeta v (meta name))) v))) (defmacro while diff --git a/src/clj/clojure/genclass.clj b/src/clj/clojure/genclass.clj index 4947b3b3c2..1c61e40b63 100644 --- a/src/clj/clojure/genclass.clj +++ b/src/clj/clojure/genclass.clj @@ -381,7 +381,7 @@ mm (mapcat #(.getMethods #^Class %) interfaces)) ;extra methods (doseq [[mname pclasses rclass :as msig] methods] - (emit-forwarding-method (str mname) pclasses rclass (:static ^msig) + (emit-forwarding-method (str mname) pclasses rclass (:static (meta msig)) emit-unsupported)) ;expose specified overridden superclass methods (doseq [[local-mname #^java.lang.reflect.Method m] (reduce (fn [ms [[name _ _] m]] diff --git a/src/clj/clojure/zip.clj b/src/clj/clojure/zip.clj index 7423513fc0..54e8f180d6 100644 --- a/src/clj/clojure/zip.clj +++ b/src/clj/clojure/zip.clj @@ -61,20 +61,20 @@ (defn branch? "Returns true if the node at loc is a branch" [loc] - ((:zip/branch? ^loc) (node loc))) + ((:zip/branch? (meta loc)) (node loc))) (defn children "Returns a seq of the children of node at loc, which must be a branch" [loc] (if (branch? loc) - ((:zip/children ^loc) (node loc)) + ((:zip/children (meta loc)) (node loc)) (throw (Exception. "called children on a leaf node")))) (defn make-node "Returns a new branch node, given an existing node and new children. The loc is only used to supply the constructor." [loc node children] - ((:zip/make-node ^loc) node children)) + ((:zip/make-node (meta loc)) node children)) (defn path "Returns a seq of nodes leading to this loc" @@ -103,7 +103,7 @@ (with-meta [c {:l [] :pnodes (if path (conj (:pnodes path) node) [node]) :ppath path - :r cnext}] ^loc))))) + :r cnext}] (meta loc)))))) (defn up "Returns the loc of the parent of the node at this loc, or nil if at @@ -116,7 +116,7 @@ [(make-node loc pnode (concat l (cons node r))) (and ppath (assoc ppath :changed? true))] [pnode ppath]) - ^loc))))) + (meta loc)))))) (defn root "zips all the way up and returns the root node, reflecting any @@ -134,14 +134,14 @@ [loc] (let [[node {l :l [r & rnext :as rs] :r :as path}] loc] (when (and path rs) - (with-meta [r (assoc path :l (conj l node) :r rnext)] ^loc)))) + (with-meta [r (assoc path :l (conj l node) :r rnext)] (meta loc))))) (defn rightmost "Returns the loc of the rightmost sibling of the node at this loc, or self" [loc] (let [[node {l :l r :r :as path}] loc] (if (and path r) - (with-meta [(last r) (assoc path :l (apply conj l node (butlast r)) :r nil)] ^loc) + (with-meta [(last r) (assoc path :l (apply conj l node (butlast r)) :r nil)] (meta loc)) loc))) (defn left @@ -149,14 +149,14 @@ [loc] (let [[node {l :l r :r :as path}] loc] (when (and path (seq l)) - (with-meta [(peek l) (assoc path :l (pop l) :r (cons node r))] ^loc)))) + (with-meta [(peek l) (assoc path :l (pop l) :r (cons node r))] (meta loc))))) (defn leftmost "Returns the loc of the leftmost sibling of the node at this loc, or self" [loc] (let [[node {l :l r :r :as path}] loc] (if (and path (seq l)) - (with-meta [(first l) (assoc path :l [] :r (concat (rest l) [node] r))] ^loc) + (with-meta [(first l) (assoc path :l [] :r (concat (rest l) [node] r))] (meta loc)) loc))) (defn insert-left @@ -166,7 +166,7 @@ (let [[node {l :l :as path}] loc] (if (nil? path) (throw (new Exception "Insert at top")) - (with-meta [node (assoc path :l (conj l item) :changed? true)] ^loc)))) + (with-meta [node (assoc path :l (conj l item) :changed? true)] (meta loc))))) (defn insert-right "Inserts the item as the right sibling of the node at this loc, @@ -175,13 +175,13 @@ (let [[node {r :r :as path}] loc] (if (nil? path) (throw (new Exception "Insert at top")) - (with-meta [node (assoc path :r (cons item r) :changed? true)] ^loc)))) + (with-meta [node (assoc path :r (cons item r) :changed? true)] (meta loc))))) (defn replace "Replaces the node at this loc, without moving" [loc node] (let [[_ path] loc] - (with-meta [node (assoc path :changed? true)] ^loc))) + (with-meta [node (assoc path :changed? true)] (meta loc)))) (defn edit "Replaces the node at this loc with the value of (f node args)" @@ -239,13 +239,13 @@ (if (nil? path) (throw (new Exception "Remove at top")) (if (pos? (count l)) - (loop [loc (with-meta [(peek l) (assoc path :l (pop l) :changed? true)] ^loc)] + (loop [loc (with-meta [(peek l) (assoc path :l (pop l) :changed? true)] (meta loc))] (if-let [child (and (branch? loc) (down loc))] (recur (rightmost child)) loc)) (with-meta [(make-node loc (peek pnodes) rs) (and ppath (assoc ppath :changed? true))] - ^loc))))) + (meta loc)))))) (comment From b3b1fa5081172d9931d7dffac4e12a535871cfde Mon Sep 17 00:00:00 2001 From: Chouser Date: Thu, 3 Dec 2009 22:06:38 -0500 Subject: [PATCH 3/6] Print deprecation warning for ^ reader macro; refs #215 Signed-off-by: Chouser --- src/jvm/clojure/lang/LispReader.java | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/src/jvm/clojure/lang/LispReader.java b/src/jvm/clojure/lang/LispReader.java index 368bc1fa2c..0f0864a19f 100644 --- a/src/jvm/clojure/lang/LispReader.java +++ b/src/jvm/clojure/lang/LispReader.java @@ -68,7 +68,7 @@ public class LispReader{ macros[';'] = new CommentReader(); macros['\''] = new WrappingReader(QUOTE); macros['@'] = new WrappingReader(DEREF);//new DerefReader(); - macros['^'] = new WrappingReader(META); + macros['^'] = new DeprecatedWrappingReader(META, "^"); macros['`'] = new SyntaxQuoteReader(); macros['~'] = new UnquoteReader(); macros['('] = new ListReader(); @@ -491,6 +491,26 @@ public Object invoke(Object reader, Object quote) throws Exception{ } +public static class DeprecatedWrappingReader extends AFn{ + final Symbol sym; + final String macro; + + public DeprecatedWrappingReader(Symbol sym, String macro){ + this.sym = sym; + this.macro = macro; + } + + public Object invoke(Object reader, Object quote) throws Exception{ + System.out.println("WARNING: reader macro " + macro + + " is deprecated; use " + sym.getName() + + " instead"); + PushbackReader r = (PushbackReader) reader; + Object o = read(r, true, null, true); + return RT.list(sym, o); + } + +} + public static class VarReader extends AFn{ public Object invoke(Object reader, Object quote) throws Exception{ PushbackReader r = (PushbackReader) reader; From f047dc4acc69350d3513b4e69e093690cdb92e40 Mon Sep 17 00:00:00 2001 From: Stuart Sierra Date: Thu, 3 Dec 2009 15:34:13 -0500 Subject: [PATCH 4/6] Remove deprecated ^ reader macro from tests; fixes #215 Signed-off-by: Chouser --- test/clojure/test_clojure/compilation.clj | 2 +- test/clojure/test_clojure/test.clj | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/test/clojure/test_clojure/compilation.clj b/test/clojure/test_clojure/compilation.clj index 1d3a78a76c..2ee68002b3 100644 --- a/test/clojure/test_clojure/compilation.clj +++ b/test/clojure/test_clojure/compilation.clj @@ -19,7 +19,7 @@ (deftest test-compiler-metadata - (let [m ^#'when] + (let [m (meta #'when)] (are [x y] (= x y) (list? (:arglists m)) true (> (count (:arglists m)) 0) true diff --git a/test/clojure/test_clojure/test.clj b/test/clojure/test_clojure/test.clj index b96cb60f06..002af625ba 100644 --- a/test/clojure/test_clojure/test.clj +++ b/test/clojure/test_clojure/test.clj @@ -73,7 +73,7 @@ (is (re-find #"cd" "abbabba") "Should fail")) (deftest #^{:has-meta true} can-add-metadata-to-tests - (is (:has-meta ^#'can-add-metadata-to-tests) "Should pass")) + (is (:has-meta (meta #'can-add-metadata-to-tests)) "Should pass")) ;; still have to declare the symbol before testing unbound symbols (declare does-not-exist) From c5abcf6751c0fed34b72eab49ec9989458651bbf Mon Sep 17 00:00:00 2001 From: Stuart Sierra Date: Thu, 3 Dec 2009 13:07:49 -0500 Subject: [PATCH 5/6] deprecate add-classpath in docstring, print warning; fixes #214 Signed-off-by: Chouser --- src/clj/clojure/core.clj | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj index 0d314a5a8d..e37fe768ea 100644 --- a/src/clj/clojure/core.clj +++ b/src/clj/clojure/core.clj @@ -3484,8 +3484,13 @@ [f] (lazy-seq (cons (f) (repeatedly f)))) (defn add-classpath - "Adds the url (String or URL object) to the classpath per URLClassLoader.addURL" - [url] (. clojure.lang.RT addURL url)) + "DEPRECATED + + Adds the url (String or URL object) to the classpath per + URLClassLoader.addURL" + [url] + (println "WARNING: add-classpath is deprecated") + (clojure.lang.RT/addURL url)) From 76e7c4317dc3eac80c4908ac5e5fb885e302b2a4 Mon Sep 17 00:00:00 2001 From: Stuart Sierra Date: Thu, 3 Dec 2009 13:27:39 -0500 Subject: [PATCH 6/6] Add :doc and :author metadata to core namespaces; fixes #216, fixes #217 Signed-off-by: Chouser --- src/clj/clojure/core.clj | 4 +- src/clj/clojure/inspector.clj | 4 +- src/clj/clojure/main.clj | 4 +- src/clj/clojure/parallel.clj | 4 +- src/clj/clojure/set.clj | 4 +- src/clj/clojure/stacktrace.clj | 5 +- src/clj/clojure/template.clj | 4 +- src/clj/clojure/test.clj | 233 +-------------------------------- src/clj/clojure/test/junit.clj | 42 +++--- src/clj/clojure/test/tap.clj | 38 +++--- src/clj/clojure/walk.clj | 11 -- src/clj/clojure/xml.clj | 8 +- src/clj/clojure/zip.clj | 7 +- 13 files changed, 71 insertions(+), 297 deletions(-) diff --git a/src/clj/clojure/core.clj b/src/clj/clojure/core.clj index e37fe768ea..b48b6c641a 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 4e1ac07727..d7f8f30fbf 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 8c2e9449dc..5f480a6082 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 93c119ff7e..9b2f3b8725 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 8711350864..e881ebe906 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 52d03b9bb0..ebe00aac0c 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 d62390a623..f84e602a3c 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 37cdd7e825..60a887eb94 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 - - (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" - ;; - - (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 c42887eb15..a9844afb51 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 11550db06b..3e41f8780a 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 6b5bad906c..b025705f31 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 caac770ac6..ba14d4c7b3 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 54e8f180d6..8896812b1a 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.