diff --git a/common-math-package.lisp b/common-math-package.lisp
index fe8e77619746674ad39aa3f580db2de002d8a0bd..36c5fd0278945351d08d42b9cb5dd99aac6bcf4b 100644
--- a/common-math-package.lisp
+++ b/common-math-package.lisp
@@ -5,6 +5,30 @@
;;;; See file COPYING in the main folder for licensing information.
(defpackage "IT.UNIMIB.DISCO.MA.CL.EXT.MATH" (:use "CL")
+ (:documentation "The Common Math Common Lisp Package.
+
+The main package containign the symbols that comprise the generic math
+operations library. Most math library symbols form the CL package are
+shadowed and re-exported. The other symbols are mostly the hooks into
+the generic function machinery for generic math.
+
+The symbols in the API are constants, mostly covering IEEE 754 names
+and values, and generic functions of fixed arity. These functions
+usually come in two flavors: monadic and dyadic. They have names
+following a simple scheme: monadic functions have a single dot
+indicating the single argument, and dyadic ones have tw,o indicating
+both arguments. E.g.,
+
+Monadic minus: -.
+Dyadic minus: .-.
+
+All fixed arity generic functions also have an optional argument
+possibly holding the resul. This is ignored for simple arithmetic
+results but is useful when writing, for example, matrix libraries that
+must allocate the result, say, of a sum; one can pass the resulting
+argument as the optional one.
+")
+
(:nicknames
"COMMON-MATH"
"MATH"