--- image.lisp.orig	2005-02-18 10:31:42.000000000 +0100
+++ image.lisp	2005-02-18 11:03:44.000000000 +0100
@@ -50,7 +50,13 @@
 (defgeneric (setf image-pixel) (x y pixel image))
 (defgeneric image-color (image x y))
 (defgeneric (setf image-color) (x y pixel color image))
-(defgeneric write-pnm (image filename output-format))
+(defgeneric write-pnm (image filename output-format)
+  (:documentation
+   "Write IMAGE to FILENAME.
+IMAGE must be an IMAGE class instance.
+If OUTPUT-FORMAT is present and its value is the symbol :ASCII, then the PNM
+image is written in ASCII format, otherwise it is written in the binary
+format."))
 
 (defmethod image-width ((image image))
   (cadr (array-dimensions (image-pixels image))))
@@ -87,6 +93,13 @@
    (max-level :initarg :max-level :type card-8 :reader image-max-level)))
 
 (defun make-truecolor-image (pixels max-value)
+  "Create and return a TRUECOLOR-IMAGE instance.
+PIXELS must be a two dimensional array of dimensions (HEIGHT WIDTH)
+corresponding to image height and width in pixels, with integer image pixels
+values as its elements.
+MAX-VALUE is used to initialize the MAX-LEVEL slot of the resulting
+TRUECOLOR-IMAGE instance, without any known actual later use; you can use 255
+as the argument value without triggering a type error."
   (make-instance 'truecolor-image :pixels pixels :max-level max-value))
 
 (defmethod color-image-max-level ((image truecolor-image))
@@ -373,5 +386,10 @@
 	    (t (error "unknown file format ~A" byte1))))))
 
 (defun read-image-file (filename &key (format :pnm))
+  "Read image data from a PNM file FILENAME.
+Return a two dimensional array of dimensions (HEIGHT WIDTH) corresponding to
+image height and width in pixels, with integer image pixel values as its
+elements.
+The FORMAT argument is currently ignored."
   (declare (ignore format))
   (read-pnm-file filename))
