From 611a9c65e30303b9654cf1200d03b1c29088a35c Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@gmail.com>
Date: Wed, 31 Jul 2013 11:03:23 -0500
Subject: [PATCH] Draft documentation for DEFINE-PACKAGE.

---
 uiop/package.lisp | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/uiop/package.lisp b/uiop/package.lisp
index 1a62eb1e..897b5847 100644
--- a/uiop/package.lisp
+++ b/uiop/package.lisp
@@ -484,7 +484,14 @@ or when loading the package is optional."
                     (home-package-p existing to-package) (symbol-package-name existing)))
             (t
              (ensure-inherited name symbol to-package from-package t shadowed imported inherited)))))))
+  
   (defun recycle-symbol (name recycle exported)
+    ;; Takes a symbol NAME (a string), a list of package designators for RECYCLE
+    ;; packages, and a hash-table of names (strings) of symbols scheduled to be
+    ;; EXPORTED from the package being defined. It returns two values, the
+    ;; symbol found (if any, or else NIL), and a boolean flag indicating whether
+    ;; a symbol was found. The caller (DEFINE-PACKAGE) will then do the
+    ;; re-homing of the symbol, etc.
     (check-type name string)
     (check-type recycle list)
     (check-type exported hash-table)
@@ -698,6 +705,22 @@ or when loading the package is optional."
                          :mix ,mix :reexport ,reexport :unintern ,unintern)))))
 
 (defmacro define-package (package &rest clauses)
+  "Supports the following keyword arguments:
+USE, SHADOW, SHADOWING-IMPORT-FROM, IMPORT-FROM, EXPORT, INTERN -- as per CL:DEFPACKAGE.
+RECYCLE -- Recycle the package's exported symbols from the specified packages,
+in order.  For every symbol scheduled to be exported by the DEFINE-PACKAGE,
+either through an :EXPORT option or a :REEXPORT option, if the symbol exists in
+one of the :RECYCLE packages, the first such symbol is re-homed to the package
+being defined.
+For the sake of idempotence, it is important that the package being defined
+should appear in first position if it already exists, and even if it doesn't,
+ahead of any package that is not going to be deleted afterwards and never
+created again. In short, except for special cases, always make it the first
+package on the list if the list is not empty.
+MIX -- ?
+REEXPORT -- A list of packages.  For each package in the list, export the 
+symbols from this package.
+UNINTERN -- Remove symbols here from PACKAGE."
   (let ((ensure-form
           `(apply 'ensure-package ',(parse-define-package-form package clauses))))
     `(progn
-- 
GitLab