From: Nikodemus Siivola <nikodemus@random-state.net>
Date: Wed, 29 Jul 2009 16:01:29 +0000 (+0000)
Subject: 1.0.30.14: some SB-CLTL2 docstrings
X-Git-Url: http://repo.macrolet.net/gitweb/?a=commitdiff_plain;h=9af8ab0a80bbd4d579ed4a12d2a2819a7490901a;p=sbcl.git

1.0.30.14: some SB-CLTL2 docstrings

 * Add docstrings for DECLARATION-INFORMATION, PARSE-MACRO and ENCLOSE.

 * Rename a test for variable-information that had the same name as another.

   Patch by Larry D'Anna, prose and indentation somewhat altered
   by yours truly.
---

diff --git a/NEWS b/NEWS
index 0a00d61..9fdeecc 100644
--- a/NEWS
+++ b/NEWS
@@ -19,6 +19,8 @@ changes relative to sbcl-1.0.30:
     but assumed or declared function as well.
   * improvement: recompilation of systems using SB-GROVEL now works
     (thanks to Leslie Polzer)
+  * improvement: SB-CLTL2 functions DECLARATION-INFORMATION, PARSE-MACRO,
+    and ENCLOSE have been documented (thanks to Larry D'Anna)
   * bug fix: the low-level debugger had 32-bit assumptions and was missing
     information about some array types. (thanks to Luis Oliveira)
   * bug fix: moderately complex combinations of inline expansions could
diff --git a/contrib/sb-cltl2/env.lisp b/contrib/sb-cltl2/env.lisp
index dd9efd5..8c35440 100644
--- a/contrib/sb-cltl2/env.lisp
+++ b/contrib/sb-cltl2/env.lisp
@@ -223,6 +223,13 @@ appear with CDR as T if the variable has been declared always bound."
 (declaim (ftype (sfunction (symbol &optional (or null lexenv)) t)
                 declaration-information))
 (defun declaration-information (declaration-name &optional env)
+  "Return information about declarations named by DECLARATION-NAME.
+
+If DECLARATION-NAME is optimize return a list who's entries are of the
+form (quality value).
+
+If DECLARATION-NAME is SB-EXT:MUFFLE-CONDITIONS return a type specifier for
+the condition types that have been muffled."
   (let ((env (or env (make-null-lexenv))))
     (case declaration-name
       (optimize
@@ -239,6 +246,11 @@ appear with CDR as T if the variable has been declared always bound."
       (t (error "Unsupported declaration ~S." declaration-name)))))
 
 (defun parse-macro (name lambda-list body &optional env)
+  "Process a macro definition of the kind that might appear in a DEFMACRO form
+into a lambda expression of two variables: a form and an environment. The
+lambda edxpression will parse its form argument, binding the variables in
+LAMBDA-LIST appropriately, and then excute BODY with those bindings in
+effect."
   (declare (ignore env))
   (with-unique-names (whole environment)
     (multiple-value-bind (body decls)
@@ -249,8 +261,13 @@ appear with CDR as T if the variable has been declared always bound."
          ,@decls
          ,body))))
 
-(defun enclose (lambda-expression &optional env)
-  (let ((env (if env
-                 (sb-c::make-restricted-lexenv env)
+(defun enclose (lambda-expression &optional environment)
+  "Return a function consistent with LAMBDA-EXPRESSION in ENVIRONMENT: the
+lambda expression is allowed to reference the declarations and macro
+definitions in ENVIRONMENT, but consequences are undefined if lexical
+variables, functions, tags or any other run-time entity defined in ENVIRONMENT
+is referred to by the expression."
+  (let ((env (if environment
+                 (sb-c::make-restricted-lexenv environment)
                  (make-null-lexenv))))
     (compile-in-lexenv nil lambda-expression env)))
diff --git a/contrib/sb-cltl2/tests.lisp b/contrib/sb-cltl2/tests.lisp
index ec5e8c9..a314d8d 100644
--- a/contrib/sb-cltl2/tests.lisp
+++ b/contrib/sb-cltl2/tests.lisp
@@ -182,7 +182,7 @@
           (assert (plusp x)))))
   (:lexical t nil))
 
-(deftest variable-info.lexical.type.2
+(deftest variable-info.lexical.type.3
     (let ((x 42))
       (locally (declare (fixnum x))
         (var-info x)))
diff --git a/version.lisp-expr b/version.lisp-expr
index 20e1fbd..fe94287 100644
--- a/version.lisp-expr
+++ b/version.lisp-expr
@@ -17,4 +17,4 @@
 ;;; checkins which aren't released. (And occasionally for internal
 ;;; versions, especially for internal versions off the main CVS
 ;;; branch, it gets hairier, e.g. "0.pre7.14.flaky4.13".)
-"1.0.30.13"
+"1.0.30.14"