Change docstrings to match suggested usage, regularize formatting.

md5.lisp

@@ -348,7 +348,7 @@ accordingly."
 (declaim (inline fill-block fill-block-ub8 fill-block-char))
 (defun fill-block-ub8 (block buffer offset)
   "Convert a complete 64 (unsigned-byte 8) input vector segment
-starting from offset into the given 16 word MD5 block."
+starting from `offset' into the given 16 word MD5 block."
   (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
            (type md5-block block)
            (type (simple-array (unsigned-byte 8) (*)) buffer)
@@ -373,8 +373,8 @@ starting from offset into the given 16 word MD5 block."
                              (aref buffer (+ j 3))))))
 
 (defun fill-block-char (block buffer offset)
-  "Convert a complete 64 character input string segment starting from
-offset into the given 16 word MD5 block."
+  "DEPRECATED: Convert a complete 64 character input string segment
+starting from `offset' into the given 16 word MD5 block."
   (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
            (type md5-block block)
            (type simple-string buffer)
@@ -402,7 +402,8 @@ offset into the given 16 word MD5 block."
   "Convert a complete 64 byte input vector segment into the given 16
 word MD5 block.  This currently works on (unsigned-byte 8) and
 character simple-arrays, via the functions `fill-block-ub8' and
-`fill-block-char' respectively."
+`fill-block-char' respectively.  Note that it will not work correctly
+on character simple-arrays if `char-code-limit' is greater than 256."
   (declare (type (integer 0 #.(- most-positive-fixnum 64)) offset)
            (type md5-block block)
            (type (simple-array * (*)) buffer)
@@ -419,7 +420,7 @@ character simple-arrays, via the functions `fill-block-ub8' and
 (declaim (inline md5regs-digest))
 (defun md5regs-digest (regs)
   "Create the final 16 byte message-digest from the MD5 working state
-in regs.  Returns a (simple-array (unsigned-byte 8) (16))."
+in `regs'.  Returns a (simple-array (unsigned-byte 8) (16))."
   (declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
                      #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
            (type md5-regs regs))
@@ -458,9 +459,9 @@ in regs.  Returns a (simple-array (unsigned-byte 8) (16))."
 
 (declaim (inline copy-to-buffer))
 (defun copy-to-buffer (from from-offset count buffer buffer-offset)
-  "Copy a partial segment from input vector from starting at
-from-offset and copying count elements into the 64 byte buffer
-starting at buffer-offset."
+  "Copy a partial segment from input vector `from' starting at
+`from-offset' and copying `count' elements into the 64 byte buffer
+starting at `buffer-offset'."
   (declare (optimize (speed 3) (safety 0) (space 0) (debug 0)
                      #+lw-int32 (float 0) #+lw-int32 (hcl:fixnum-safety 0))
            (type (unsigned-byte 29) from-offset)
@@ -494,9 +495,13 @@ starting at buffer-offset."
                        from-index))))))
 
 (defun update-md5-state (state sequence &key (start 0) (end (length sequence)))
-  "Update the given md5-state from sequence, which is either a
+  "Update the given md5-state from `sequence', which is either a
 simple-string or a simple-array with element-type (unsigned-byte 8),
-bounded by start and end, which must be numeric bounding-indices."
+bounded by `start' and `end', which must be numeric bounding-indices.
+Note that usage on simple-strings is DEPRECATED, since this will not
+work correctly if `char-code-limit' is more than 256.  String input
+should be converted to (unsigned-byte 8) simple-arrays with
+external-format conversion routines beforehand."
   (declare (type md5-state state)
            (type (simple-array * (*)) sequence)
            (type fixnum start end)
@@ -613,10 +618,13 @@ The resulting MD5 message-digest is returned as an array of sixteen
 ;;; High-Level Drivers
 
 (defun md5sum-sequence (sequence &key (start 0) end)
-  "Calculate the MD5 message-digest of data in sequence.  On CMU CL
-this works for all sequences whose element-type is supported by the
-underlying MD5 routines, on other implementations it only works for 1d
-simple-arrays with such element types."
+  "Calculate the MD5 message-digest of data in `sequence', which should
+be a 1d simple-array with element type (unsigned-byte 8).  On CMU CL
+and SBCL non-simple and non-1d arrays with this element-type are also
+supported.  Use with strings is DEPRECATED, since this will not work
+correctly on implementations with `char-code-limit' > 256 and ignores
+character-coding issues.  Use md5sum-string instead, or convert to the
+required (unsigned-byte 8) format through other means before-hand."
   (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))
            (type vector sequence) (type fixnum start))
   (locally
@@ -645,10 +653,12 @@ simple-arrays with such element types."
       (finalize-md5-state state))))
 
 (defun md5sum-string (string &key (external-format :default) (start 0) end)
-  "Calculate the MD5 message-digest of the binary representation
-of STRING (as octets) in EXTERNAL-FORMAT. The boundaries START
-and END refer to character positions in the string, not to octets
-in the resulting binary representation."
+  "Calculate the MD5 message-digest of the binary representation of
+`string' (as octets) in the external format specified by
+`external-format'. The boundaries `start' and `end' refer to character
+positions in the string, not to octets in the resulting binary
+representation.  The permissible external format specifiers are
+determined by the underlying implementation."
   (declare (optimize (speed 3) (safety 3) (space 0) (debug 1))
            (type string string) (type fixnum start))
   (locally
@@ -688,14 +698,16 @@ in the resulting binary representation."
 
 (eval-when (:compile-toplevel :load-toplevel :execute)
   (defconstant +buffer-size+ (* 128 1024)
-    "Size of internal buffer to use for md5sum-stream and md5sum-file
+    "Size of internal buffer to use for `md5sum-stream' and `md5sum-file'
 operations.  This should be a multiple of 64, the MD5 block size."))
 
 (deftype buffer-index () `(integer 0 ,+buffer-size+))
 
 (defun md5sum-stream (stream)
-  "Calculate an MD5 message-digest of the contents of stream.  Its
-element-type has to be either (unsigned-byte 8) or character."
+  "Calculate an MD5 message-digest of the contents of `stream'.  Its
+element-type has to be (unsigned-byte 8). Use on character streams is
+DEPRECATED, as this will not work correctly on implementations with
+`char-code-limit' > 256 and ignores character coding issues."
   (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
   (locally
       (declare (optimize (safety 1) (debug 0)))
@@ -725,7 +737,7 @@ element-type has to be either (unsigned-byte 8) or character."
                 (stream-element-type stream) stream))))))
 
 (defun md5sum-file (pathname)
-  "Calculate the MD5 message-digest of the file specified by pathname."
+  "Calculate the MD5 message-digest of the file specified by `pathname'."
   (declare (optimize (speed 3) (safety 3) (space 0) (debug 1)))
   (with-open-file (stream pathname :element-type '(unsigned-byte 8))
     (md5sum-stream stream)))