From 34623a5cc419b27087853f61b96138d3895e048f Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Mon, 3 Mar 2014 20:52:57 -0500
Subject: [PATCH] Beef up a few docstrings in uiop/image.

---
 uiop/image.lisp | 39 +++++++++++++++++++++++++++++++++++----
 1 file changed, 35 insertions(+), 4 deletions(-)

diff --git a/uiop/image.lisp b/uiop/image.lisp
index 27ad1915..47bb43b9 100644
--- a/uiop/image.lisp
+++ b/uiop/image.lisp
@@ -258,8 +258,9 @@ if we are not called from a directly executable image."
       (rest arguments)))
 
   (defun argv0 ()
-    "On supported implementations (most that matter), return a string that for the name with which
-the program was invoked, i.e. argv[0] in C. On other implementations, return NIL."
+    "On supported implementations (most that matter), or when invoked by a proper wrapper script,
+return a string that for the name with which the program was invoked, i.e. argv[0] in C.
+Otherwise, return NIL."
     (cond
       ((eq *image-dumped-p* :executable) ; yes, this ARGV0 is our argv0 !
        ;; NB: not currently available on ABCL, Corman, Genera, MCL, MKCL
@@ -280,7 +281,29 @@ the program was invoked, i.e. argv[0] in C. On other implementations, return NIL
                           (entry-point *image-entry-point*)
                           (if-already-restored '(cerror "RUN RESTORE-IMAGE ANYWAY")))
     "From a freshly restarted Lisp image, restore the saved Lisp environment
-by setting appropriate variables, running various hooks, and calling any specified entry point."
+by setting appropriate variables, running various hooks, and calling any specified entry point.
+
+If the image has already been restored or is already being restored, as per *IMAGE-RESTORED-P*,
+call the IF-ALREADY-RESTORED error handler (by default, a continuable error), and do return
+immediately to the surrounding restore process if allowed to continue.
+
+Then, comes the restore process itself:
+First, call each function in the RESTORE-HOOK,
+in the order they were registered with REGISTER-RESTORE-HOOK.
+Second, evaluate the prelude, which is often Lisp text that is read,
+as per EVAL-INPUT.
+Third, call the ENTRY-POINT function, if any is specified, with no argument.
+
+The restore process happens in a WITH-FATAL-CONDITION-HANDLER, so that if LISP-INTERACTION is NIL,
+any unhandled error leads to a backtrace and an exit with an error status.
+If LISP-INTERACTION is NIL, the process also exits when no error occurs:
+if neither restart nor entry function is provided, the program will exit with status 0 (success);
+if a function was provided, the program will exit after the function returns (if it returns),
+with status 0 if and only if the primary return value of result is generalized boolean true,
+and with status 1 if this value is NIL.
+
+If LISP-INTERACTION is true, unhandled errors will take you to the debugger, and the result
+of the function will be returned rather than interpreted as a boolean designating an exit code."
     (when *image-restored-p*
       (if if-already-restored
           (call-function if-already-restored "Image already ~:[being ~;~]restored"
@@ -312,7 +335,15 @@ by setting appropriate variables, running various hooks, and calling any specifi
                                 #+clozure prepend-symbols #+clozure (purify t)
                                 #+sbcl compression
                                 #+(and sbcl windows) application-type)
-    "Dump an image of the current Lisp environment at pathname FILENAME, with various options"
+    "Dump an image of the current Lisp environment at pathname FILENAME, with various options.
+
+First, finalize the image, by evaluating the POSTLUDE as per EVAL-INPUT, then calling each of
+ the functions in DUMP-HOOK, in reverse order of registration by REGISTER-DUMP-HOOK.
+
+If EXECUTABLE is true, create an standalone executable program that calls RESTORE-IMAGE on startup.
+
+Pass various implementation-defined options, such as PREPEND-SYMBOLS and PURITY on CCL,
+or COMPRESSION on SBCL, and APPLICATION-TYPE on SBCL/Windows."
     ;; Note: at least SBCL saves only global values of variables in the heap image,
     ;; so make sure things you want to dump are NOT just local bindings shadowing the global values.
     (declare (ignorable filename output-name executable))
-- 
GitLab