microhttpd.h: doxy and other minor improvements

src/include/microhttpd.h

@@ -168,12 +168,6 @@ enum MHD_Result
 
 } _MHD_FIXED_ENUM;
 
-
-/**
- * MHD digest auth internal code for an invalid nonce.
- */
-#define MHD_INVALID_NONCE -1
-
 /**
  * Constant used to indicate unknown size (use when
  * creating a response).
@@ -1546,8 +1540,9 @@ typedef int
  * These values can limit the scope of validity of MHD-generated nonces.
  * Values can be combined with bitwise OR.
  * Any value, except #MHD_DAUTH_BIND_NONCE_NONE, enforce function
- * #MHD_digest_auth_check3() (and similar) to check nonce by re-generating
- * it again with the same parameters, which is CPU-intensive operation.
+ * #MHD_digest_auth_check3() (and similar functions) to check nonce by
+ * re-generating it again with the same parameters, which is CPU-intensive
+ * operation.
  * @note Available since #MHD_VERSION 0x00097531
  */
 enum MHD_DAuthBindNonce
@@ -1555,13 +1550,13 @@ enum MHD_DAuthBindNonce
   /**
    * Generated nonces are valid for any request from any client until expired.
    * This is default and recommended value.
-   * #MHD_digest_auth_check3() (and similar function) would check only whether
+   * #MHD_digest_auth_check3() (and similar functions) would check only whether
    * the nonce value that is used by client has been generated by MHD and not
    * expired yet.
    * It is recommended because RFC 7616 allows clients to use the same nonce
    * for any request in the same "protection space".
    * CPU is loaded less when this value is used when checking client's
-   * authorisation request.
+   * authorisation requests.
    * This mode gives MHD maximum flexibility for nonces generation and can
    * prevent possible nonce collisions (and corresponding log warning messages)
    * when clients' requests are intensive.
@@ -4815,7 +4810,7 @@ struct MHD_DigestAuthInfo
    * The username string.
    * Valid only if username is standard, extended, or userhash.
    * For userhash this is unqoted string without decoding of the
-   * hexadecimal digits (as provided by client).
+   * hexadecimal digits (as provided by the client).
    * If extended notation is used, this string is pct-decoded string
    * with charset and language tag removed (i.e. it is original username
    * extracted from the extended notation).
@@ -4834,6 +4829,7 @@ struct MHD_DigestAuthInfo
    * Used only if username type is userhash, always NULL otherwise.
    * When not NULL, this points to binary sequence @a username_len /2 bytes
    * long.
+   * The valid size should be #MHD_digest_get_hash_size(algo) bytes.
    * @warning This is binary data, no zero termination.
    * @warning To avoid buffer overruns, always check the size of the data before
    *          use, because @a userhash_bin can point even to zero-sized
@@ -4946,8 +4942,10 @@ struct MHD_DigestAuthUsernameInfo
 
   /**
    * The userhash decoded to binary form.
+   * Used only if username type is userhash, always NULL otherwise.
    * When not NULL, this points to binary sequence @a username_len /2 bytes
    * long.
+   * The valid size should be #MHD_digest_get_hash_size(algo) bytes.
    * @warning This is binary data, no zero termination.
    * @warning To avoid buffer overruns, always check the size of the data before
    *          use, because @a userhash_bin can point even to zero-sized
@@ -5250,6 +5248,12 @@ _MHD_EXTERN char *
 MHD_digest_auth_get_username (struct MHD_Connection *connection);
 
 
+/**
+ * MHD digest auth internal code for an invalid nonce.
+ */
+#define MHD_INVALID_NONCE -1
+
+
 /**
  * Which digest algorithm should MHD use for HTTP digest authentication?
  * Used as parameter for #MHD_digest_auth_check2(),