diff --git a/include/mbedtls/md.h b/include/mbedtls/md.h
index df2ab63..6b6f5c5 100644
--- a/include/mbedtls/md.h
+++ b/include/mbedtls/md.h
@@ -54,15 +54,15 @@
  *
  */
 typedef enum {
-    MBEDTLS_MD_NONE=0, /**< None. */
-    MBEDTLS_MD_MD2, /**< The MD2 message digest. */
-    MBEDTLS_MD_MD4, /**< The MD4 message digest. */
-    MBEDTLS_MD_MD5, /**< The MD5 message digest. */
-    MBEDTLS_MD_SHA1, /**< The SHA-1 message digest. */
-    MBEDTLS_MD_SHA224, /**< The SHA-224 message digest. */
-    MBEDTLS_MD_SHA256, /**< The SHA-256 message digest. */
-    MBEDTLS_MD_SHA384, /**< The SHA-384 message digest. */
-    MBEDTLS_MD_SHA512,  /**< The SHA-512 message digest. */
+    MBEDTLS_MD_NONE=0,    /**< None. */
+    MBEDTLS_MD_MD2,       /**< The MD2 message digest. */
+    MBEDTLS_MD_MD4,       /**< The MD4 message digest. */
+    MBEDTLS_MD_MD5,       /**< The MD5 message digest. */
+    MBEDTLS_MD_SHA1,      /**< The SHA-1 message digest. */
+    MBEDTLS_MD_SHA224,    /**< The SHA-224 message digest. */
+    MBEDTLS_MD_SHA256,    /**< The SHA-256 message digest. */
+    MBEDTLS_MD_SHA384,    /**< The SHA-384 message digest. */
+    MBEDTLS_MD_SHA512,    /**< The SHA-512 message digest. */
     MBEDTLS_MD_RIPEMD160, /**< The RIPEMD-160 message digest. */
 } mbedtls_md_type_t;
 
@@ -108,8 +108,8 @@
  *
  * \param md_name   The name of the digest to search for.
  *
- * \return          The message-digest information associated with \p md_name,
- *                  or NULL if not found.
+ * \return          The message-digest information associated with \p md_name.
+ * \return          NULL if the associated message-digest information is not found.
  */
 const mbedtls_md_info_t *mbedtls_md_info_from_string( const char *md_name );
 
@@ -168,9 +168,10 @@
  * \param md_info   The information structure of the message-digest algorithm
  *                  to use.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
- * \returns         #MBEDTLS_ERR_MD_ALLOC_FAILED memory allocation failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
+ * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_md_init_ctx( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info ) MBEDTLS_DEPRECATED;
 #undef MBEDTLS_DEPRECATED
@@ -190,9 +191,10 @@
  * \param hmac      Defines if HMAC is used. 0: HMAC is not used (saves some memory),
  *                  or non-zero: HMAC is used with this context.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
- * \returns         #MBEDTLS_ERR_MD_ALLOC_FAILED on memory allocation failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
+ * \return          #MBEDTLS_ERR_MD_ALLOC_FAILED on memory-allocation failure.
  */
 int mbedtls_md_setup( mbedtls_md_context_t *ctx, const mbedtls_md_info_t *md_info, int hmac );
 
@@ -213,7 +215,7 @@
  * \param src       The context to be cloned.
  *
  * \return          \c 0 on success.
- * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter failure.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification failure.
  */
 int mbedtls_md_clone( mbedtls_md_context_t *dst,
                       const mbedtls_md_context_t *src );
@@ -260,9 +262,9 @@
  *
  * \param ctx       The generic message-digest context.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_starts( mbedtls_md_context_t *ctx );
 
@@ -278,9 +280,9 @@
  * \param input     The buffer holding the input data.
  * \param ilen      The length of the input data.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_update( mbedtls_md_context_t *ctx, const unsigned char *input, size_t ilen );
 
@@ -298,9 +300,9 @@
  * \param ctx       The generic message-digest context.
  * \param output    The buffer for the generic message-digest checksum result.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_finish( mbedtls_md_context_t *ctx, unsigned char *output );
 
@@ -318,9 +320,9 @@
  * \param ilen     The length of the input data.
  * \param output   The generic message-digest checksum result.
  *
- * \returns        \c 0 on success.
- * \returns        #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                 fails.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                 failure.
  */
 int mbedtls_md( const mbedtls_md_info_t *md_info, const unsigned char *input, size_t ilen,
         unsigned char *output );
@@ -339,8 +341,9 @@
  * \param output   The generic message-digest checksum result.
  *
  * \return         \c 0 on success.
- * \returns        #MBEDTLS_ERR_MD_FILE_IO_ERROR if file input failed.
- * \returns        #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
+ * \return         #MBEDTLS_ERR_MD_FILE_IO_ERROR on an I/O error accessing
+ *                 the file pointed by \p path.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if \p md_info was NULL.
  */
 int mbedtls_md_file( const mbedtls_md_info_t *md_info, const char *path,
                      unsigned char *output );
@@ -360,9 +363,9 @@
  * \param key       The HMAC secret key.
  * \param keylen    The length of the HMAC key in Bytes.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_starts( mbedtls_md_context_t *ctx, const unsigned char *key,
                     size_t keylen );
@@ -382,9 +385,9 @@
  * \param input     The buffer holding the input data.
  * \param ilen      The length of the input data.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_update( mbedtls_md_context_t *ctx, const unsigned char *input,
                     size_t ilen );
@@ -403,9 +406,9 @@
  *                  context.
  * \param output    The generic HMAC checksum result.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_finish( mbedtls_md_context_t *ctx, unsigned char *output);
 
@@ -420,9 +423,9 @@
  * \param ctx       The message digest context containing an embedded HMAC
  *                  context.
  *
- * \returns         \c 0 on success.
- * \returns         #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                  fails.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                  failure.
  */
 int mbedtls_md_hmac_reset( mbedtls_md_context_t *ctx );
 
@@ -444,9 +447,9 @@
  * \param ilen     The length of the input data.
  * \param output   The generic HMAC result.
  *
- * \returns        \c 0 on success.
- * \returns        #MBEDTLS_ERR_MD_BAD_INPUT_DATA if parameter verification
- *                 fails.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_MD_BAD_INPUT_DATA on parameter-verification
+ *                 failure.
  */
 int mbedtls_md_hmac( const mbedtls_md_info_t *md_info, const unsigned char *key, size_t keylen,
                 const unsigned char *input, size_t ilen,