Fix documentation.

4 files changed, 46 insertions, 12 deletions

diff --git a/README b/README
index a049a2d..21afb2f 100644
--- a/README
+++ b/README
@@ -5,13 +5,39 @@ the specification.
 The code is licensed under the LGPLv3 or any later version, unless specified
 otherwise in a file.
 
-Depends on Alexandria, Ironclad version 0.58+, function-cache, and fiveam for
-the tests.
+Depends on Alexandria, Ironclad version 0.58+, function-cache,
+trivial-gray-streams, bordeaux-threads, and fiveam for testing. In addition, on
+POSIX systems the mmap and osicat libraries are used for the parallel decoder.
 
 Until the Ironclad library released version 0.58, you have to use the master
 branch as it contains the necessary patch to add the RFC Chacha variant to
 Ironclad.
 
-TODO:
-+ fix the bugs
-+ clean up the code
\ No newline at end of file
+
+The public API is exported by the ERIS package.
+
+There are the following functions for converting to and from ERIS
+representations to eris-cl objects:
+
+read-capability-to-urn
+urn-to-read-capability
+octets-to-read-capability
+read-capability-to-octets
+reference-to-block-urn
+block-urn-to-reference
+
+The eris-encode (INPUT BLOCK-SIZE OUTPUT-FUNCTION &KEY SECRET HASH-OUTPUT)
+function can be used to encode a vector or a stream into an ERIS
+read-capability.
+
+The eris-decode (READ-CAPABILITY FETCH-FUNCTION &KEY (CACHE-CAPACITY 2048))
+function can be used to decode an ERIS read-capability. It returns a stream of
+the class ERIS-DECODE-STREAM: this class implements the Gray streams protocol.
+
+In addition, on POSIX systems, eris-decode-parallel (READ-CAPABILITY
+FETCH-FUNCTION OUTPUT-FILE &KEY (CACHE-CAPACITY 4096) (THREADS 4)
+(INITIAL-BINDINGS *DEFAULT-SPECIAL-BINDINGS*)) function is available. This
+function will attempt to decode an ERIS read-capability in parallel into a file
+specified by the OUTPUT-FILE string or pathspec.
+
+See the docstrings of the specific functions for more details.
diff --git a/src/eris-decode.lisp b/src/eris-decode.lisp
index 351da72..508dc67 100644
--- a/src/eris-decode.lisp
+++ b/src/eris-decode.lisp
@@ -209,12 +209,13 @@ it is necessary and sets the position in the buffer to 0."
 
 (defun eris-decode (read-capability fetch-function &key (cache-capacity 2048))
   "Using the FETCH-FUNCTION, return a stream that decodes the READ-CAPABILITY.
+This stream implements the Gray streams protocol.
 
 Fetch-function must be a function with one argument, the reference octet, which
 returns a (simple-array (unsigned-byte 8)) containing the block. The block will
 be destructively modified, so you MUST provide a fresh array every time. If a
 hash-table is used, a (copy-seq) needs to be done on the return value of
-gethash. 
+gethash.
 
 The keyword argument CACHE-CAPACITY indicates the amount of blocks stored in the
 cache."
diff --git a/src/eris.lisp b/src/eris.lisp
index 5e3ed2a..0509ecb 100644
--- a/src/eris.lisp
+++ b/src/eris.lisp
@@ -194,14 +194,18 @@ read-capability object. Returns the read-capability."
 
 (defgeneric eris-encode (input block-size output-function &key secret hash-output)
   (:documentation
-   "Encode an input into block-size (32kib or 1kib) blocks, that are output using
-the function output-function. This function wil be called with two arguments: an
-encoded block and a 32-byte reference octet vector.
+   "Encode an INPUT into BLOCK-SIZE (32kib or 1kib) blocks, that are output using
+the function OUTPUT-FUNCTION. This function wil be called with two arguments: an
+encoded block and a 32-byte reference octet vector. Returns a read-capability
+object.
 
 An optional 32-byte secret can be passed for additional encryption using the
-:secret keyword."))
+SECRET keyword argument.
 
-(defmethod eris-encode ((input simple-array) block-size output-function &key (secret null-secret) hash-output)
+The HASH-OUTPUT keyword argument controls whether a hash-table is used to
+guarantee that a reference is only output once."))
+
+(defmethod eris-encode ((input simple-array) block-size output-function &key (secret null-secret) (hash-output t))
   (declare (type block-size block-size)
            (type function output-function)
            (type (simple-array (unsigned-byte 8) (32)) secret))
diff --git a/src/parallel-decoder.lisp b/src/parallel-decoder.lisp
index 9af1ceb..8b4f568 100644
--- a/src/parallel-decoder.lisp
+++ b/src/parallel-decoder.lisp
@@ -88,7 +88,10 @@ be destructively modified, so you MUST provide a fresh array every time. In
 addition, the function MUST be thread-safe.
 
 CACHE-CAPACITY indicates the total amount of blocks stored for all threads. Each
-thread has its own cache."
+thread has its own cache.
+
+INITIAL-BINDINGS is passed to make-thread. This is only useful if you are
+locally binding a special variable to some value."
   (declare (type read-capability read-capability)
            (type function fetch-function)
            (type integer cache-capacity))