generic: documentation update

4 files changed, 86 insertions, 22 deletions

diff --git a/src/clojure/contrib/generic/arithmetic.clj b/src/clojure/contrib/generic/arithmetic.clj
index b6f0a6ff..2f28799f 100644
--- a/src/clojure/contrib/generic/arithmetic.clj
+++ b/src/clojure/contrib/generic/arithmetic.clj
@@ -1,7 +1,7 @@
 ;; Generic interfaces for arithmetic operations
 
 ;; by Konrad Hinsen
-;; last updated May 3, 2009
+;; last updated May 5, 2009
 
 ;; Copyright (c) Konrad Hinsen, 2009. All rights reserved.  The use
 ;; and distribution terms for this software are covered by the Eclipse
@@ -38,11 +38,15 @@
 ;
 ; Addition
 ;
-; The minimal implementation is for [::binary my-type]. It is possible
+; The minimal implementation is for binary my-type. It is possible
 ; in principle to implement [::unary my-type] as well, though this
 ; doesn't make any sense.
 ;
-(defmulti + nary-dispatch)
+(defmulti + 
+  "Return the sum of all arguments. The minimal implementation for type
+   ::my-type is the binary form with dispatch value [::my-type ::my-type]."
+  {:arglists '([x] [x y] [x y & more])}
+  nary-dispatch)
 
 (defmethod + nulary-type
   []
@@ -70,7 +74,11 @@
 ; implementation is provided as (+ x (- y)), but it is possible to
 ; implement unary my-type explicitly for efficiency reasons.
 ;
-(defmulti - nary-dispatch)
+(defmulti -
+  "Return the difference of the first argument and the sum of all other
+   arguments. The minimal implementation for type ::my-type is the binary
+   form with dispatch value [::my-type ::my-type]."
+  nary-dispatch)
 
 (defmethod - nulary-type
   []
@@ -99,7 +107,10 @@
 ; in principle to implement unary my-type as well, though this
 ; doesn't make any sense.
 ;
-(defmulti * nary-dispatch)
+(defmulti *
+  "Return the product of all arguments. The minimal implementation for type
+   ::my-type is the binary form with dispatch value [::my-type ::my-type]."
+  nary-dispatch)
 
 (defmethod * nulary-type
   []
@@ -127,7 +138,11 @@
 ; implementation is provided as (* x (/ y)), but it is possible to
 ; implement binary [my-type my-type] explicitly for efficiency reasons.
 ;
-(defmulti / nary-dispatch)
+(defmulti /
+  "Return the quotient of the first argument and the product of all other
+   arguments. The minimal implementation for type ::my-type is the binary
+   form with dispatch value [::my-type ::my-type]."
+  nary-dispatch)
 
 (defmethod / nulary-type
   []
@@ -153,11 +168,16 @@
 ; Macros to permit access to the / multimethod via namespace qualification
 ;
 (defmacro defmethod*
+  "Define a method implementation for the multimethod name in namespace ns.
+   Required for implementing the division function from another namespace."
   [ns name & args]
   (let [qsym (symbol (str ns) (str name))]
     `(defmethod ~qsym ~@args)))
 
 (defmacro qsym
+  "Create the qualified symbol corresponding to sym in namespace ns.
+   Required to access the division function from another namespace,
+   e.g. as (qsym clojure.contrib.generic.arithmetic /)."
   [ns sym]
   (symbol (str ns) (str sym)))
 
diff --git a/src/clojure/contrib/generic/collection.clj b/src/clojure/contrib/generic/collection.clj
index 8bb39a94..8f5fc068 100644
--- a/src/clojure/contrib/generic/collection.clj
+++ b/src/clojure/contrib/generic/collection.clj
@@ -1,7 +1,7 @@
 ;; Generic interfaces for collection-related functions
 
 ;; by Konrad Hinsen
-;; last updated May 3, 2009
+;; last updated May 5, 2009
 
 ;; Copyright (c) Konrad Hinsen, 2009. All rights reserved.  The use
 ;; and distribution terms for this software are covered by the Eclipse
@@ -39,7 +39,9 @@
 ;
 ; conj
 ;
-(defmulti conj (fn [coll & xs] (type coll)))
+(defmulti conj
+  "Returns a new collection resulting from adding all xs to coll."
+  (fn [coll & xs] (type coll)))
 
 (defmethod conj :default
   [coll & xs]
diff --git a/src/clojure/contrib/generic/comparison.clj b/src/clojure/contrib/generic/comparison.clj
index dbed2926..e05d8091 100644
--- a/src/clojure/contrib/generic/comparison.clj
+++ b/src/clojure/contrib/generic/comparison.clj
@@ -1,7 +1,7 @@
 ;; Generic interfaces for comparison operations
 
 ;; by Konrad Hinsen
-;; last updated May 3, 2009
+;; last updated May 5, 2009
 
 ;; Copyright (c) Konrad Hinsen, 2009. All rights reserved.  The use
 ;; and distribution terms for this software are covered by the Eclipse
@@ -25,12 +25,19 @@
 ;
 ; zero?
 ;
-(defmulti zero? type)
+(defmulti zero?
+  "Return true of x is zero."
+  {:arglists '([x])}
+  type)
 
 ;
 ; Equality
 ;
-(defmulti = nary-dispatch)
+(defmulti =
+  "Return true if all arguments are equal. The minimal implementation for type
+   ::my-type is the binary form with dispatch value [::my-type ::my-type]."
+  {:arglists '([x] [x y] [x y & more])}
+  nary-dispatch)
 
 (defmethod = root-type
   [x] true)
@@ -46,7 +53,11 @@
 ;
 ; Greater-than
 ;
-(defmulti > nary-dispatch)
+(defmulti >
+  "Return true if each argument is larger than the following ones.
+   The minimal implementation for type ::my-type is the binary form
+   with dispatch value [::my-type ::my-type]."
+  nary-dispatch)
 
 (defmethod > root-type
   [x] true)
@@ -62,7 +73,12 @@
 ;
 ; Less-than defaults to greater-than with arguments inversed
 ;
-(defmulti < nary-dispatch)
+(defmulti <
+  "Return true if each argument is smaller than the following ones.
+   The minimal implementation for type ::my-type is the binary form
+   with dispatch value [::my-type ::my-type]. A default implementation
+   is provided in terms of >."
+  nary-dispatch)
 
 (defmethod < root-type
   [x] true)
@@ -82,7 +98,12 @@
 ;
 ; Greater-or-equal defaults to (complement <)
 ;
-(defmulti >= nary-dispatch)
+(defmulti >=
+  "Return true if each argument is larger than or equal to the following
+   ones. The minimal implementation for type ::my-type is the binary form
+   with dispatch value [::my-type ::my-type]. A default implementation
+   is provided in terms of <."
+  nary-dispatch)
 
 (defmethod >= root-type
   [x] true)
@@ -102,7 +123,12 @@
 ;
 ; Less-than defaults to (complement >)
 ;
-(defmulti <= nary-dispatch)
+(defmulti <=
+  "Return true if each arguments is smaller than or equal to the following
+   ones. The minimal implementation for type ::my-type is the binary form
+   with dispatch value [::my-type ::my-type]. A default implementation
+   is provided in terms of >."
+  nary-dispatch)
 
 (defmethod <= root-type
   [x] true)
diff --git a/src/clojure/contrib/generic/math_functions.clj b/src/clojure/contrib/generic/math_functions.clj
index 3eebe938..a0fb3609 100644
--- a/src/clojure/contrib/generic/math_functions.clj
+++ b/src/clojure/contrib/generic/math_functions.clj
@@ -1,7 +1,7 @@
 ;; Generic interfaces for mathematical functions
 
 ;; by Konrad Hinsen
-;; last updated May 3, 2009
+;; last updated May 5, 2009
 
 ;; Copyright (c) Konrad Hinsen, 2009. All rights reserved.  The use
 ;; and distribution terms for this software are covered by the Eclipse
@@ -26,7 +26,10 @@
   [name]
   (let [java-symbol (symbol "java.lang.Math" (str name))]
     `(do
-       (defmulti ~name type)
+       (defmulti ~name
+	 ~(str "Return the " name " of x.")
+	 {:arglists '([~'x])}
+	 type)
        (defmethod ~name java.lang.Number
 	 [~'x]
 	 (~java-symbol ~'x)))))
@@ -37,7 +40,10 @@
   [name]
   (let [java-symbol (symbol "java.lang.Math" (str name))]
     `(do
-       (defmulti ~name two-types)
+       (defmulti ~name
+	 ~(str "Return the " name " of x and y.")
+	 {:arglists '([~'x ~'y])}
+	 two-types)
        (defmethod ~name [java.lang.Number java.lang.Number]
 	 [~'x ~'y]
 	 (~java-symbol ~'x ~'y)))))
@@ -64,7 +70,11 @@
 ;
 ; Sign
 ;
-(defmulti sgn type)
+(defmulti sgn
+  "Return the sign of x (-1, 0, or 1)."
+  {:arglists '([x])}
+  type)
+
 (defmethod sgn :default
   [x]
   (cond (gc/zero? x) 0
@@ -74,7 +84,10 @@
 ;
 ; Conjugation
 ;
-(defmulti conjugate type)
+(defmulti conjugate
+  "Return the conjugate of x."
+  {:arglists '([x])}
+  type)
 
 (defmethod conjugate :default
   [x] x)
@@ -82,7 +95,10 @@
 ;
 ; Square
 ;
-(defmulti sqr type)
+(defmulti sqr
+  "Return the square of x."
+  {:arglists '([x])}
+  type)
 
 (defmethod sqr :default
   [x]
@@ -93,6 +109,6 @@
 ;
 (defn approx=
   "Return true if the absolute value of the difference between x and y
-   is less than eps"
+   is less than eps."
   [x y eps]
   (gc/< (abs (ga/- x y)) eps))