From ab2fd196b56b79c6d447284f6b8c4f3df8b543bd Mon Sep 17 00:00:00 2001
From: Richard Aas <richard@db.org>
Date: Fri, 9 Dec 2011 11:45:17 +0000
Subject: [PATCH] httpauth: add doxygen comments + const

---
 include/re_httpauth.h |  4 +++-
 src/httpauth/digest.c | 27 ++++++++++++++++++++++++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/include/re_httpauth.h b/include/re_httpauth.h
index a548268..32786e3 100644
--- a/include/re_httpauth.h
+++ b/include/re_httpauth.h
@@ -5,6 +5,7 @@
  */
 
 
+/** HTTP Digest Challenge */
 struct httpauth_digest_chall {
 	struct pl realm;
 	struct pl nonce;
@@ -16,6 +17,7 @@ struct httpauth_digest_chall {
 	struct pl qop;
 };
 
+/** HTTP Digest response */
 struct httpauth_digest_resp {
 	struct pl realm;
 	struct pl nonce;
@@ -34,5 +36,5 @@ int httpauth_digest_challenge_decode(struct httpauth_digest_chall *chall,
 				     const struct pl *hval);
 int httpauth_digest_response_decode(struct httpauth_digest_resp *resp,
 				    const struct pl *hval);
-int httpauth_digest_response_auth(struct httpauth_digest_resp *resp,
+int httpauth_digest_response_auth(const struct httpauth_digest_resp *resp,
 				  const struct pl *method, const uint8_t *ha1);
diff --git a/src/httpauth/digest.c b/src/httpauth/digest.c
index 4677894..002ceec 100644
--- a/src/httpauth/digest.c
+++ b/src/httpauth/digest.c
@@ -97,6 +97,14 @@ static int digest_decode(const struct pl *hval, digest_decode_h *dech,
 }
 
 
+/**
+ * Decode a Digest challenge
+ *
+ * @param chall Digest challenge object to decode into
+ * @param hval  Header value to decode from
+ *
+ * @return 0 if successfully decoded, otherwise errorcode
+ */
 int httpauth_digest_challenge_decode(struct httpauth_digest_chall *chall,
 				     const struct pl *hval)
 {
@@ -118,6 +126,14 @@ int httpauth_digest_challenge_decode(struct httpauth_digest_chall *chall,
 }
 
 
+/**
+ * Decode a Digest response
+ *
+ * @param resp Digest response object to decode into
+ * @param hval Header value to decode from
+ *
+ * @return 0 if successfully decoded, otherwise errorcode
+ */
 int httpauth_digest_response_decode(struct httpauth_digest_resp *resp,
 				    const struct pl *hval)
 {
@@ -143,7 +159,16 @@ int httpauth_digest_response_decode(struct httpauth_digest_resp *resp,
 }
 
 
-int httpauth_digest_response_auth(struct httpauth_digest_resp *resp,
+/**
+ * Authenticate a digest response
+ *
+ * @param resp   Digest response
+ * @param method Request method
+ * @param ha1    HA1 value from MD5(username:realm:password)
+ *
+ * @return 0 if successfully authenticated, otherwise errorcode
+ */
+int httpauth_digest_response_auth(const struct httpauth_digest_resp *resp,
 				  const struct pl *method, const uint8_t *ha1)
 {
 	uint8_t ha2[MD5_SIZE], digest[MD5_SIZE], response[MD5_SIZE];