diff --git a/man/zip_source_function.mdoc b/man/zip_source_function.mdoc
index 8dd6501..b395b44 100644
--- a/man/zip_source_function.mdoc
+++ b/man/zip_source_function.mdoc
@@ -1,4 +1,4 @@
-.\" $NiH: zip_source_function.mdoc,v 1.1 2004/11/18 16:48:08 wiz Exp $
+.\" $NiH: zip_source_function.mdoc,v 1.2 2004/11/18 17:26:54 wiz Exp $
 .\"
 .\" zip_source_function.mdoc -- create data source from function
 .\" Copyright (C) 2004 Dieter Baron and Thomas Klausner
@@ -31,7 +31,7 @@
 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 4, 2004
+.Dd December 10, 2004
 .Dt ZIP_SOURCE_FUNCTION 3
 .Os
 .Sh NAME
@@ -46,50 +46,75 @@
 .Sh DESCRIPTION
 The function
 .Fn zip_source_function
-creates a zip source from an arbitrary given function
-.Ar fn .
-.Ar fn
-is a user-supplied function of the following type:
+creates a zip source from the user-provided function
+.Ar fn ,
+which must be of the following type:
 .Bd -literal
 typedef ssize_t (*zip_read_func)(void *state,
     void *data, size_t len, enum zip_cmd cmd);
 .Ed
 .Pp
-.Ar fn
-will be called by the library with the
-.Fn zip_source
+When called by the library, the first argument is the
 .Ar state
-argument as the first argument, a buffer
+argument supplied to
+.Fn zip_source_function .
+The next two arguments are a buffer
 .Ar data
 of size
 .Ar len
-for the data as second and third arguments when actually
-reading data, and
-.Ar cmd
-as the fourth argument.
-.Ar cmd
-can be any of the following:
+when data is expected to be returned, or else
+.Dv NULL
+and 0.
+The last argument,
+.Ar cmd ,
+specifies which action the function should perform:
 .Bl -tag -width XZIPXCMDXCLOSEXX -offset indent
 .It Dv ZIP_CMD_OPEN
-Prepare for reading.
+Prepare for reading.  Return 0 on success, \-1 on error.
 .It Dv ZIP_CMD_READ
 Read data into the buffer
 .Ar data
 of size
-.Ar len.
+.Ar len .
+Return the number of bytes placed into
+.Ar data
+on success, \-1 on error.
 .It Dv ZIP_CMD_CLOSE
-Reading is done, close the input file.
+Reading is done.
 .It Dv ZIP_CMD_STAT
 Get meta information for the input file.
-.\" XXX: format?
+.Ar data
+points to a struct zip_stat, which should be filled in.  Return 0 on
+succeess, \-1 on error.
 .It Dv ZIP_CMD_ERROR
 Get error information.
-.\" XXX: more detail
+.Ar data
+points to an array of two ints, which should be filled with the libzip
+error code and the corresponding system error code for the error that
+occurred.  Return 0.
+.\" XXX: we should document all error codes somewhere
 .It Dv ZIP_CMD_FREE
-Cleanup and free resources.
-.\" XXX: more detail when this is called
+Clean up and free all resources.  Return 0.
 .El
-.El
+.Pp
+The library will always issue
+.Dv ZIP_CMD_OPEN
+before issuing
+.Dv ZIP_CMD_READ .
+When it no longer wishes to read from this source, it will issue
+.Dv ZIP_CMD_READ .
+If the library wishes to read the data again, it will issue
+.Dv ZIP_CMD_OPEN
+a second time.  If the function is unable to provide
+the data again, it should return \-1.
+.Pp
+.Dv ZIP_CMD_STAT
+can be issued at any time.
+.Dv ZIP_CMD_ERROR
+will only be issued in response to the function
+returning \-1.
+.Dv ZIP_CMD_FREE
+will be the last command issued.
 .Sh RETURN VALUES
 Upon successful completion, the created source is returned.
 Otherwise,