diff options
| -rw-r--r-- | src/clj/clojure/core.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/inspector.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/main.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/parallel.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/set.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/stacktrace.clj | 5 | ||||
| -rw-r--r-- | src/clj/clojure/template.clj | 4 | ||||
| -rw-r--r-- | src/clj/clojure/test.clj | 233 | ||||
| -rw-r--r-- | src/clj/clojure/test/junit.clj | 42 | ||||
| -rw-r--r-- | src/clj/clojure/test/tap.clj | 38 | ||||
| -rw-r--r-- | src/clj/clojure/walk.clj | 11 | ||||
| -rw-r--r-- | src/clj/clojure/xml.clj | 8 | ||||
| -rw-r--r-- | 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 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. |