Clean up docstrings and type declarations.

1 files changed, 44 insertions, 21 deletions

diff --git a/src/eris.lisp b/src/eris.lisp
index b30c6a4..5e3ed2a 100644
--- a/src/eris.lisp
+++ b/src/eris.lisp
@@ -15,15 +15,6 @@
 
 (in-package :eris)
 
-(defun pad (input block-size)
-  (declare (type (simple-array (unsigned-byte 8)) input)
-           (type integer block-size))
-  (let* ((pad-size (- block-size (mod (length input) block-size)))
-         (padded-input (adjust-array input (+ pad-size (length input)) :initial-element 0)))
-    (replace padded-input input)
-    (setf (aref padded-input (length input)) #x80)
-    padded-input))
-
 (deftype block-size ()
         `(member 1024 32768))
 
@@ -36,14 +27,22 @@
     ((reference :initarg :reference :accessor reference :type (simple-array (unsigned-byte 8) 32))
      (key :initarg :key :accessor key :type (simple-array (unsigned-byte 8) 32)))))
 
-(define-constant null-secret (make-array 32 :element-type '(unsigned-byte 8) :initial-element 0) :test #'equalp)
+(define-constant null-secret (make-array 32 :element-type '(unsigned-byte 8) :initial-element 0)
+  :test #'equalp
+  :documentation
+  "32-byte null vector.")
 
 (defun reference-pair-to-octets (pair buf &optional (start 0))
-    (replace buf (reference pair) :start1 start)
+  "Convert a reference-pair object PAIR into the standard binary representation by
+filling the buffer BUF from the START keyword argument. "
+  (declare (type vector buf))
+  (replace buf (reference pair) :start1 start)
     (replace buf (key pair) :start1 (+ 32 start)))
 
 (defun octets-to-reference-pair (octets &optional (start 0))
-  (declare (type (simple-array (unsigned-byte 8)) octets))
+  "Convert the standard reference-pair binary representation into a reference-pair
+object, using the bytes from the OCTETS vector from at START."
+  (declare (type vector octets))
   (make-instance 'reference-pair :key (subseq octets (+ 32 start) (+ 64 start))
                                  :reference (subseq octets start (+ 32 start))))
 
@@ -54,8 +53,6 @@
     (ironclad:digest-sequence :blake2/256 block :digest reference)
     reference))
 
-(declaim (inline make-nonce))
-
 (defun make-nonce (level)
   (let ((nonce (make-array 12 :element-type '(unsigned-byte 8) :initial-element 0)))
     (setf (aref nonce 0) level)
@@ -98,20 +95,31 @@
                :type block-size
                :documentation "A value of either 1024 or 1kb blocks.") 
    (level :initarg :level :accessor level :type (unsigned-byte 8))
-   (root-reference-pair :initarg :reference-pair :accessor reference-pair)))
-
+   (root-reference-pair :initarg :reference-pair :accessor reference-pair))
+  (:documentation "Class representing the concept of an ERIS read capability."))
 
+(declaim
+ (ftype (function (read-capability) (values (simple-array (unsigned-byte 8) (66)) &optional)) read-capability-to-octets)
+ (ftype (function ((simple-array (unsigned-byte 8) (66))) read-capability) octets-to-read-capability)
+ (ftype (function (read-capability) string) read-capability-to-urn)
+ (ftype (function (string) read-capability) urn-to-read-capability)
+ (ftype (function ((simple-array (unsigned-byte 8) (32))) string) reference-to-block-urn)
+ (ftype (function (string) (values (simple-array (unsigned-byte 8) (32)) &optional)) block-urn-to-reference))
 
 (defun read-capability-to-octets (read-capability)
+  "Convert a read-capability object to its standard binary representation. Returns
+a (simple-array (unsigned-byte 8)) object."
   (declare (type read-capability read-capability))
   (let ((cap (make-array 66 :element-type '(unsigned-byte 8))))
     (case (block-size read-capability) ;; This depends on the version of the standard
-        (1024 (setf (aref cap 0) #x0a))
-        (32768 (setf (aref cap 0) #x0f)))
+      (1024 (setf (aref cap 0) #x0a))
+      (32768 (setf (aref cap 0) #x0f)))
     (setf (aref cap 1) (level read-capability))
     (reference-pair-to-octets (reference-pair read-capability) cap 2)))
 
 (defun octets-to-read-capability (octets)
+  "Convert the standard binary representation for ERIS read capabilities into a
+read-capability object. Returns the read-capability."
   (declare (type (simple-array (unsigned-byte 8) (66)) octets))
   (let ((capability (make-instance 'read-capability)))
     (setf (block-size capability)
@@ -126,21 +134,36 @@
     capability))
 
 (defun read-capability-to-urn (capability)
+  "Convert a read-capability object into a URN string."
+  (declare (type read-capability capability))
   (concatenate 'string
                "urn:eris:"
                (bytes-to-base32-unpadded (read-capability-to-octets capability))))
 
 (defun urn-to-read-capability (urn)
+  "Convert a urn:eris URN string into a read-capability object."
+  (declare (type string urn))
   (octets-to-read-capability (base32-to-bytes-unpadded (subseq urn (1+ (position #\: urn :from-end t))))))
 
 (defun reference-to-block-urn (reference)
+  "Convert a 32-byte block reference into a URN string."
   (declare (type (simple-array (unsigned-byte 8) (32)) reference))
   (concatenate 'string "urn:blake2b:" (bytes-to-base32-unpadded reference)))
 
 (defun block-urn-to-reference (urn)
+  "Convert a urn:blake2b URN string into a 32-byte block reference vector."
   (declare (type string urn))
   (base32-to-bytes-unpadded (subseq urn (1+ (position #\: urn :from-end t)))))
 
+(defun pad (input block-size)
+  (declare (type (simple-array (unsigned-byte 8)) input)
+           (type integer block-size))
+  (let* ((pad-size (- block-size (mod (length input) block-size)))
+         (padded-input (adjust-array input (+ pad-size (length input)) :initial-element 0)))
+    (replace padded-input input)
+    (setf (aref padded-input (length input)) #x80)
+    padded-input))
+
 (defvar *output-hashmap* nil)
 
 (defmacro output-block (ref-vector &rest expr)
@@ -230,9 +253,9 @@ An optional 32-byte secret can be passed for additional encryption using the
                    for rk across reference-vector
                    with i = 0
                    when (eql i block-keys)
-                   do (output-internal-block reference-vector-l nonce
-                                    (setf block (make-array block-size :element-type '(unsigned-byte 8) :initial-element 0)
-                                          i 0))
+                     do (output-internal-block reference-vector-l nonce
+                                               (setf block (make-array block-size :element-type '(unsigned-byte 8) :initial-element 0)
+                                                     i 0))
                    do (progn (reference-pair-to-octets rk block (* 64 i))
                              (incf i))
                    finally (unless (zerop i)