Fri Feb  5 03:21:40 UTC 2010  pix@kepibu.org
  * Unified docstrings.
diff -rN -u old-cl-unification-1/match-block.lisp new-cl-unification-1/match-block.lisp
--- old-cl-unification-1/match-block.lisp	2014-09-11 07:35:02.000000000 +0000
+++ new-cl-unification-1/match-block.lisp	2014-09-11 07:35:02.000000000 +0000
@@ -117,6 +117,11 @@
                ,@(when default-clauses `((t ,@(cdar default-clauses))))
                ,@(when default `((t ,default))))))))))
 
+(defmacro %set-documentation ((&rest symbols) docstring)
+  `(eval-when (:load-toplevel :execute)
+     (mapcar (lambda (fn) (setf (documentation fn 'function) ,docstring))
+             ',symbols)))
+
 (defmacro match ((template object
                            &key
                            (named nil)
@@ -125,25 +130,6 @@
                            (errorp t)
                            (error-value nil))
                  &body forms)
-  "Sets up a lexical environment to evaluate FORMS after an unification.
-
-MATCH unifies a TEMPLATE and an OBJECT and then sets up a lexical
-environment where the variables present in the template are bound
-lexically.  Note that both variable names '?FOO' and 'FOO' are bound
-for convenience.
-
-The MATCH form returns the values returned by the evaluation of the
-last of the FORMS.
-
-If ERRORP is non-NIL (the default) then the form raises a
-UNIFICATION-FAILURE, otherwise the result of evaluating ERROR-VALUE,
-whose default is NIL is returned. (Note that UNIFICATION-FAILUREs
-raising from the evaluation of FORMS will also be caught and handled
-according to ERRORP settings.)
-
-If MATCH-NAMED is not NIL, then a surrounding BLOCK named MATCH-NAMED
-is set up around the matching code.
-"
   (when match-named-p
     (warn ":match-named is deprecated.  Use :named instead."))
   (%match-expander 'match
@@ -162,9 +148,21 @@
                             (errorp t)
                             (error-value nil))
                   &body forms)
-  "Sets up a lexical environment to evaluate FORMS after an unification.
+  (when match-named-p
+    (warn ":match-named is deprecated.  Use :named instead."))
+  (%match-expander 'matchf
+                   'nil
+                   `((,template ,object ,@forms))
+                   :default error-value
+                   :named (or named match-named)
+                   :environment substitution
+                   :errorp errorp))
+
+(%set-documentation
+ (match matchf)
+ "Sets up a lexical environment to evaluate FORMS after an unification.
 
-MATCHF unifies a TEMPLATE and an OBJECT and then sets up a lexical
+MATCH and MATCHF unify a TEMPLATE and an OBJECT and then set up a lexical
 environment where the variables present in the template are bound
 lexically.  Note that both variable names '?FOO' and 'FOO' are bound
 for convenience.
@@ -172,27 +170,16 @@
 MATCHF does not 'evaluate' TEMPLATE (note that using the #T syntax will
 generate a template at read-time).
 
-The MATCHF form returns the values returned by the evaluation of the
+MATCH and MATCHF forms return the values returned by the evaluation of the
 last of the FORMS.
 
 If ERRORP is non-NIL (the default) then the form raises a
 UNIFICATION-FAILURE, otherwise the result of evaluating ERROR-VALUE,
 whose default is NIL is returned. (Note that UNIFICATION-FAILUREs
-raising from the evaluation of FORMS will also be caught and handled
+raising from the evaluation of FORMS will /not/ be caught and handled
 according to ERRORP settings.)
 
-If MATCH-NAMED is not NIL, then a surrounding BLOCK named MATCH-NAMED
-is set up around the matching code.
-"
-  (when match-named-p
-    (warn ":match-named is deprecated.  Use :named instead."))
-  (%match-expander 'matchf
-                   'nil
-                   `((,template ,object ,@forms))
-                   :default error-value
-                   :named (or named match-named)
-                   :environment substitution
-                   :errorp errorp))
+A surrounding BLOCK named NAMED is set up around the matching code.")
 
 
 
@@ -203,11 +190,9 @@
 
 
 (defmacro match-cond (&body clauses)
-  "A combination of COND and MATCH."
   (%match-expander 'match 'cond clauses))
 
 (defmacro matchf-cond (&body clauses)
-  "A combination of COND and MATCHF."
   (%match-expander 'matchf 'cond clauses))
 
 (defmacro matching ((&key errorp
@@ -215,33 +200,6 @@
                           (named nil)
                           (matching-named nil matching-named-p))
                     &body match-clauses)
-  "MATCHING sets up a COND-like environment for multiple template matching clauses.
-
-The syntax of MATCHING comprises a number of clauses of the form
-
-  <clause> ::= <regular-clause> | <default-clause>
-  <regular-clause> ::= ((<template> <form>) &body <forms>)
-  <default-clause> ::= (t &body <forms>)
-                   |   (otherwise &body <forms>)
-<form> and <forms> are regular Common Lisp forms.
-<template> is a unification template.
-
-The full syntax of MATCHING is
-
-  matching (&key errorp default-substitution) <clauses>
-
-Each clause evaluates its forms in an environment where the variables
-present in the template are bound lexically.  Note that both variable
-names '?FOO' and 'FOO' are bound for convenience.
-
-The values returned by the MATCHING form are those of the last form in
-the first clause that satisfies the match test.
-
-If ERRORP is non-NIL then if none of the regular clauses matches, then
-an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
-any default clause.  Otherwise, the default clause behaves as a
-standard COND default clause.  The default value of ERRORP is NIL.
-"
   (when matching-named-p
     (warn ":matching-named is deprecated.  Use :named instead."))
   (%match-expander 'match 'cond match-clauses
@@ -250,35 +208,40 @@
                    :named (or named matching-named)
                    :environment default-substitution))
 
-(defmacro match-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
-                      &body clauses)
-  "MATCH-CASE sets up a CASE-like environment for multiple template matching clauses.
-
-The syntax of MATCH-CASE comprises a number of clauses of the form
+(%set-documentation
+ (match-cond matchf-cond matching)
+ "MATCH-COND, MATCHF-COND, and MATCHING set up a COND-like environment for
+multiple template matching clauses.
 
+Their syntax comprises a number of clauses of the form
   <clause> ::= <regular-clause> | <default-clause>
-  <regular-clause> ::= (<template> &body <forms>)
+  <regular-clause> ::= ((<template> <form>) &body <forms>)
   <default-clause> ::= (t &body <forms>)
                    |   (otherwise &body <forms>)
 <form> and <forms> are regular Common Lisp forms.
 <template> is a unification template.
 
-The full syntax of MATCH-CASE is
-
-  match-case <object> (&key errorp default-substitution) <clauses>
+The full syntax is
+  match-cond <clauses>
+  matchf-cond <clauses>
+  matching (&key errorp default-substitution named) <clauses>
 
 Each clause evaluates its forms in an environment where the variables
 present in the template are bound lexically.  Note that both variable
 names '?FOO' and 'FOO' are bound for convenience.
 
-The values returned by the MATCH-CASE form are those of the last form in
+The values returned by the macros are those of the last form in
 the first clause that satisfies the match test.
 
 If ERRORP is non-NIL then if none of the regular clauses matches, then
 an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
 any default clause.  Otherwise, the default clause behaves as a
-standard CASE default clause.  The default value of ERRORP is NIL.
-"
+standard COND default clause.  The default value of ERRORP is NIL.
+")
+
+
+(defmacro match-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
+                      &body clauses)
   (when match-case-named-p
     (warn ":match-case-named is deprecated.  Use :named instead."))
   (%match-expander 'match 'case clauses
@@ -298,37 +261,6 @@
 
 (defmacro matchf-case ((object &key errorp default-substitution named (match-case-named nil match-case-named-p))
                        &body clauses)
-  "MATCHF-CASE sets up a CASE-like environment for multiple template matching clauses.
-
-The syntax of MATCHF-CASE comprises a number of clauses of the form
-
-  <clause> ::= <regular-clause> | <default-clause>
-  <regular-clause> ::= (<template> &body <forms>)
-  <default-clause> ::= (t &body <forms>)
-                   |   (otherwise &body <forms>)
-<form> and <forms> are regular Common Lisp forms.
-<template> is a unification template.
-
-The full syntax of MATCHF-CASE is
-
-  matchf-case <object> (&key errorp default-substitution) <clauses>
-
-Each clause evaluates its forms in an environment where the variables
-present in the template are bound lexically.  Note that both variable
-names '?FOO' and 'FOO' are bound for convenience.
-
-The values returned by the MATCH-CASE form are those of the last form in
-the first clause that satisfies the match test.
-
-If ERRORP is non-NIL then if none of the regular clauses matches, then
-an error of type UNIFICATION-NON-EXAUSTIVE is signalled, regardless of
-any default clause.  Otherwise, the default clause behaves as a
-standard CASE default clause.  The default value of ERRORP is NIL.
-
-MATCHF-CASE behaves like MATCH-CASE, but the patterns are not
-evaluated (i.e., it relies on MATCHF instead of MATCH to construct the
-macro expansion.
-"
   (when match-case-named-p
     (warn ":match-case-named is deprecated.  Use :named instead."))
   (%match-expander 'matchf 'case clauses
@@ -346,6 +278,37 @@
                    :default `(error 'unification-non-exhaustive)
                    :keyform object))
 
+(%set-documentation
+ (match-case match-ecase matchf-case matchf-ecase)
+ "MATCH-CASE, MATCH-ECASE, MATCHF-CASE, and MATCHF-ECASE set up a CASE-like
+environment for multiple template matching clauses.
+
+Their syntax comprises a number of clauses of the form
+  <clause> ::= <regular-clause> | <default-clause>
+  <regular-clause> ::= (<template> &body <forms>)
+  <default-clause> ::= (t &body <forms>)
+                   |   (otherwise &body <forms>)
+<form> and <forms> are regular Common Lisp forms.
+<template> is a unification template.
+
+The full syntax is
+  match-case   (<object> &key default-substitution named errorp) <clauses>
+  match-ecase  (<object> &key default-substitution named)        <clauses>
+  matchf-case  (<object> &key default-substitution named errorp) <clauses>
+  matchf-ecase (<object> &key default-substitution named)        <clauses>
+
+Each clause evaluates its forms in an environment where the variables
+present in the template are bound lexically.  Note that both variable
+names '?FOO' and 'FOO' are bound for convenience.
+
+The values returned by the macros are those of the last form in
+the first clause that satisfies the match test.
+
+MATCHF-ECASE and MATCHF-CASE behave like MATCH-ECASE and MATCH-CASE, but the
+patterns are not evaluated (i.e., they rely on MATCHF instead of MATCH to
+construct the macro expansion).
+")
+
 
 ;;;;---------------------------------------------------------------------------
 ;;;; Testing.