diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 8404a2d59..ee88fcf31 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,7 +1,9 @@
 /**
  * \file sha512.h
+ * \brief This file contains SHA-384 and SHA-512 definitions and functions.
  *
- * \brief The SHA-384 and SHA-512 cryptographic hash function.
+ * The Secure Hash Algorithms 384 and 512 (SHA-384 and SHA-512) cryptographic
+ * hash functions are defined in <em>FIPS 180-4: Secure Hash Standard (SHS)</em>.
  */
 /*
  *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -55,9 +57,8 @@ typedef struct
     uint64_t total[2];          /*!< The number of Bytes processed. */
     uint64_t state[8];          /*!< The intermediate digest state. */
     unsigned char buffer[128];  /*!< The data block being processed. */
-    int is384;                  /*!< Determines which function to use.
-                                 *   <ul><li>0: Use SHA-512.</li>
-                                 *   <li>1: Use SHA-384.</li></ul> */
+    int is384;                  /*!< Determines which function to use:
+                                     0: Use SHA-512, or 1: Use SHA-384. */
 }
 mbedtls_sha512_context;
 
@@ -89,9 +90,8 @@ void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
  *                 calculation.
  *
  * \param ctx      The SHA-512 context to initialize.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  *
  * \return         \c 0 on success.
  */
@@ -148,9 +148,8 @@ int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
  *
  * \param ctx      The SHA-512 context to initialize.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
                                                int is384 );
@@ -159,7 +158,7 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_starts( mbedtls_sha512_context *ctx,
  * \brief          This function feeds an input buffer into an ongoing
  *                 SHA-512 checksum calculation.
  *
- * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha512_update_ret() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param input    The buffer holding the data.
@@ -173,7 +172,7 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_update( mbedtls_sha512_context *ctx,
  * \brief          This function finishes the SHA-512 operation, and writes
  *                 the result to the output buffer.
  *
- * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha512_finish_ret() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param output   The SHA-384 or SHA-512 checksum result.
@@ -186,7 +185,7 @@ MBEDTLS_DEPRECATED void mbedtls_sha512_finish( mbedtls_sha512_context *ctx,
  *                 the ongoing SHA-512 computation. This function is for
  *                 internal use only.
  *
- * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0
+ * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0.
  *
  * \param ctx      The SHA-512 context.
  * \param data     The buffer holding one block of data.
@@ -223,9 +222,8 @@ extern "C" {
  * \param input    The buffer holding the input data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-384 or SHA-512 checksum result.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  *
  * \return         \c 0 on success.
  */
@@ -255,9 +253,8 @@ int mbedtls_sha512_ret( const unsigned char *input,
  * \param input    The buffer holding the data.
  * \param ilen     The length of the input data.
  * \param output   The SHA-384 or SHA-512 checksum result.
- * \param is384    Determines which function to use.
- *                 <ul><li>0: Use SHA-512.</li>
- *                 <li>1: Use SHA-384.</li></ul>
+ * \param is384    Determines which function to use:
+ *                 0: Use SHA-512, or 1: Use SHA-384.
  */
 MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
                                         size_t ilen,
@@ -269,7 +266,8 @@ MBEDTLS_DEPRECATED void mbedtls_sha512( const unsigned char *input,
  /**
  * \brief          The SHA-384 or SHA-512 checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_sha512_self_test( int verbose );