From 78d8e29d8ce116c875f9db946eb961aa58dcba98 Mon Sep 17 00:00:00 2001
Message-Id: <78d8e29d8ce116c875f9db946eb961aa58dcba98.1715471938.git.mdw@distorted.org.uk>
From: Mark Wooding <mdw@chiark.greenend.org.uk>
Date: Sat, 22 Dec 2007 13:59:32 +0000
Subject: [PATCH 1/1] comments
Organization: Straylight/Edgeware

From: Richard Kettlewell <rjk@greenend.org.uk>

---
 lib/base64.c |  6 ++++++
 lib/mime.c   | 23 +++++++++++++++++++++--
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/lib/base64.c b/lib/base64.c
index 8015b1a..1a0dca2 100644
--- a/lib/base64.c
+++ b/lib/base64.c
@@ -38,6 +38,9 @@ static const char mime_base64_table[] =
 /** @brief Convert MIME base64
  * @param s base64 data
  * @return Decoded data
+ *
+ * See <a href="http://tools.ietf.org/html/rfc2045#section-6.8">RFC
+ * 2045 s6.8</a>.
  */
 char *mime_base64(const char *s, size_t *nsp) {
   struct dynstr d;
@@ -76,6 +79,9 @@ char *mime_base64(const char *s, size_t *nsp) {
  * @return Encoded data
  *
  * This function does not attempt to split up lines.
+ *
+ * See <a href="http://tools.ietf.org/html/rfc2045#section-6.8">RFC
+ * 2045 s6.8</a>.
  */
 char *mime_to_base64(const uint8_t *s, size_t ns) {
   struct dynstr d[1];
diff --git a/lib/mime.c b/lib/mime.c
index 7575b7b..a97c4d1 100644
--- a/lib/mime.c
+++ b/lib/mime.c
@@ -209,6 +209,8 @@ static const char *parsetoken(const char *s, char **valuep,
  * @param parameternamep Where to store parameter name
  * @param parameternvaluep Wher to store parameter value
  * @return 0 on success, non-0 on error
+ *
+ * See <a href="http://tools.ietf.org/html/rfc2045#section-5">RFC 2045 s5</a>.
  */
 int mime_content_type(const char *s,
 		      char **typep,
@@ -254,7 +256,12 @@ int mime_content_type(const char *s,
  * @param s Start of message
  * @param callback Called for each header field
  * @param u Passed to callback
- * @return Pointer to decoded body (might be in original string)
+ * @return Pointer to decoded body (might be in original string), or NULL on error
+ *
+ * This does an RFC 822-style parse and honors Content-Transfer-Encoding as
+ * described in <a href="http://tools.ietf.org/html/rfc2045#section-6">RFC 2045
+ * s6</a>.  @p callback is called for each header field encountered, in order,
+ * with ASCII characters in the header name forced to lower case.
  */
 const char *mime_parse(const char *s,
 		       int (*callback)(const char *name, const char *value,
@@ -291,6 +298,7 @@ const char *mime_parse(const char *s,
   return s;
 }
 
+/** @brief Match the boundary string */
 static int isboundary(const char *ptr, const char *boundary, size_t bl) {
   return (ptr[0] == '-'
 	  && ptr[1] == '-'
@@ -301,6 +309,7 @@ static int isboundary(const char *ptr, const char *boundary, size_t bl) {
 		  && (iscrlf(ptr + bl + 4) || *(ptr + bl + 4) == 0))));
 }
 
+/** @brief Match the final boundary string */
 static int isfinal(const char *ptr, const char *boundary, size_t bl) {
   return (ptr[0] == '-'
 	  && ptr[1] == '-'
@@ -312,10 +321,14 @@ static int isfinal(const char *ptr, const char *boundary, size_t bl) {
 
 /** @brief Parse a multipart MIME body
  * @param s Start of message
- * @param callback CAllback for each part
+ * @param callback Callback for each part
  * @param boundary Boundary string
  * @param u Passed to callback
  * @return 0 on success, non-0 on error
+ * 
+ * See <a href="http://tools.ietf.org/html/rfc2046#section-5.1">RFC 2046
+ * s5.1</a>.  @p callback is called for each part (not yet decoded in any way)
+ * in succession; you should probably call mime_parse() for each part.
  */
 int mime_multipart(const char *s,
 		   int (*callback)(const char *s, void *u),
@@ -351,6 +364,9 @@ int mime_multipart(const char *s,
  * @param parameternamep Where to store parameter name
  * @param parameternvaluep Wher to store parameter value
  * @return 0 on success, non-0 on error
+ *
+ * See <a href="http://tools.ietf.org/html/rfc2388#section-3">RFC 2388 s3</a>
+ * and <a href="http://tools.ietf.org/html/rfc2183">RFC 2183</a>.
  */
 int mime_rfc2388_content_disposition(const char *s,
 				     char **dispositionp,
@@ -389,6 +405,9 @@ int mime_rfc2388_content_disposition(const char *s,
 /** @brief Convert MIME quoted-printable
  * @param s Quoted-printable data
  * @return Decoded data
+ *
+ * See <a href="http://tools.ietf.org/html/rfc2045#section-6.7">RFC 2045
+ * s6.7</a>.
  */
 char *mime_qp(const char *s) {
   struct dynstr d;
-- 
[mdw]