diff --git a/include/mbedtls/sha512.h b/include/mbedtls/sha512.h
index 7453c44..52ae204 100644
--- a/include/mbedtls/sha512.h
+++ b/include/mbedtls/sha512.h
@@ -1,10 +1,10 @@
 /**
  * \file sha512.h
  *
- * \brief SHA-384 and SHA-512 cryptographic hash function
+ * \brief The SHA-384 and SHA-512 cryptographic hash function.
  */
 /*
- *  Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
+ *  Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
  *  SPDX-License-Identifier: Apache-2.0
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may
@@ -19,7 +19,7 @@
  *  See the License for the specific language governing permissions and
  *  limitations under the License.
  *
- *  This file is part of mbed TLS (https://tls.mbed.org)
+ *  This file is part of Mbed TLS (https://tls.mbed.org)
  */
 #ifndef MBEDTLS_SHA512_H
 #define MBEDTLS_SHA512_H
@@ -39,7 +39,6 @@
     !defined(inline) && !defined(__cplusplus)
 #define inline __inline
 #endif
-
 #if !defined(MBEDTLS_SHA512_ALT)
 // Regular implementation
 //
@@ -49,85 +48,97 @@
 #endif
 
 /**
- * \brief          SHA-512 context structure
+ * \brief          The SHA-512 context structure.
+ *
+ *                 The structure is used both for SHA-384 and for SHA-512
+ *                 checksum calculations. The choice between these two is
+ *                 made in the call to mbedtls_sha512_starts_ret().
  */
 typedef struct
 {
-    uint64_t total[2];          /*!< number of bytes processed  */
-    uint64_t state[8];          /*!< intermediate digest state  */
-    unsigned char buffer[128];  /*!< data block being processed */
-    int is384;                  /*!< 0 => SHA-512, else SHA-384 */
+    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> */
 }
 mbedtls_sha512_context;
 
 /**
- * \brief          Initialize SHA-512 context
+ * \brief          This function initializes a SHA-512 context.
  *
- * \param ctx      SHA-512 context to be initialized
+ * \param ctx      The SHA-512 context to initialize.
  */
 void mbedtls_sha512_init( mbedtls_sha512_context *ctx );
 
 /**
- * \brief          Clear SHA-512 context
+ * \brief          This function clears a SHA-512 context.
  *
- * \param ctx      SHA-512 context to be cleared
+ * \param ctx      The SHA-512 context to clear.
  */
 void mbedtls_sha512_free( mbedtls_sha512_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-512 context
+ * \brief          This function clones the state of a SHA-512 context.
  *
- * \param dst      The destination context
- * \param src      The context to be cloned
+ * \param dst      The destination context.
+ * \param src      The context to clone.
  */
 void mbedtls_sha512_clone( mbedtls_sha512_context *dst,
                            const mbedtls_sha512_context *src );
 
 /**
- * \brief          SHA-512 context setup
+ * \brief          This function starts a SHA-384 or SHA-512 checksum
+ *                 calculation.
  *
- * \param ctx      context to be initialized
- * \param is384    0 = use SHA512, 1 = use SHA384
+ * \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>
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha512_starts_ret( mbedtls_sha512_context *ctx, int is384 );
 
 /**
- * \brief          SHA-512 process buffer
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-512 checksum calculation.
  *
- * \param ctx      SHA-512 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-512 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha512_update_ret( mbedtls_sha512_context *ctx,
-                               const unsigned char *input,
-                               size_t ilen );
+                    const unsigned char *input,
+                    size_t ilen );
 
 /**
- * \brief          SHA-512 final digest
+ * \brief          This function finishes the SHA-512 operation, and writes
+ *                 the result to the output buffer. This function is for
+ *                 internal use only.
  *
- * \param ctx      SHA-512 context
- * \param output   SHA-384/512 checksum result
+ * \param ctx      The SHA-512 context.
+ * \param output   The SHA-384 or SHA-512 checksum result.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha512_finish_ret( mbedtls_sha512_context *ctx,
                                unsigned char output[64] );
 
 /**
- * \brief          SHA-512 process data block (internal use only)
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-512 computation.
  *
- * \param ctx      SHA-512 context
- * \param data     buffer holding one block of data
+ * \param ctx      The SHA-512 context.
+ * \param data     The buffer holding one block of data.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_internal_sha512_process( mbedtls_sha512_context *ctx,
                                      const unsigned char data[128] );
-
 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
 #if defined(MBEDTLS_DEPRECATED_WARNING)
 #define MBEDTLS_DEPRECATED      __attribute__((deprecated))
@@ -135,12 +146,15 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          SHA-512 context setup
+ * \brief          This function starts a SHA-384 or SHA-512 checksum
+ *                 calculation.
  *
  * \deprecated     Superseded by mbedtls_sha512_starts_ret() in 2.7.0
  *
- * \param ctx      context to be initialized
- * \param is384    0 = use SHA512, 1 = use SHA384
+ * \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>
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha512_starts(
                                                 mbedtls_sha512_context *ctx,
@@ -150,13 +164,14 @@
 }
 
 /**
- * \brief          SHA-512 process buffer
+ * \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
  *
- * \param ctx      SHA-512 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-512 context.
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha512_update(
                                                 mbedtls_sha512_context *ctx,
@@ -167,12 +182,13 @@
 }
 
 /**
- * \brief          SHA-512 final digest
+ * \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
  *
- * \param ctx      SHA-512 context
- * \param output   SHA-384/512 checksum result
+ * \param ctx      The SHA-512 context.
+ * \param output   The SHA-384 or SHA-512 checksum result.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha512_finish(
                                                 mbedtls_sha512_context *ctx,
@@ -182,12 +198,14 @@
 }
 
 /**
- * \brief          SHA-512 process data block (internal use only)
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-512 computation. This function is for
+ *                 internal use only.
  *
  * \deprecated     Superseded by mbedtls_internal_sha512_process() in 2.7.0
  *
- * \param ctx      SHA-512 context
- * \param data     buffer holding one block of data
+ * \param ctx      The SHA-512 context.
+ * \param data     The buffer holding one block of data.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha512_process(
                                             mbedtls_sha512_context *ctx,
@@ -212,14 +230,23 @@
 #endif
 
 /**
- * \brief          Output = SHA-512( input buffer )
+ * \brief          This function calculates the SHA-512 or SHA-384
+ *                 checksum of a buffer.
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-384/512 checksum result
- * \param is384    0 = use SHA512, 1 = use SHA384
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
  *
- * \return         0 if successful
+ *                 The SHA-512 result is calculated as
+ *                 output = SHA-512(input buffer).
+ *
+ * \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>
+ *
+ * \return         \c 0 on success.
  */
 int mbedtls_sha512_ret( const unsigned char *input,
                         size_t ilen,
@@ -233,14 +260,23 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          Output = SHA-512( input buffer )
+ * \brief          This function calculates the SHA-512 or SHA-384
+ *                 checksum of a buffer.
+ *
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
+ *
+ *                 The SHA-512 result is calculated as
+ *                 output = SHA-512(input buffer).
  *
  * \deprecated     Superseded by mbedtls_sha512_ret() in 2.7.0
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-384/512 checksum result
- * \param is384    0 = use SHA512, 1 = use SHA384
+ * \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>
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha512(
                                                     const unsigned char *input,
@@ -253,11 +289,10 @@
 
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
-
-/**
- * \brief          Checkup routine
+ /**
+ * \brief          The SHA-384 or SHA-512 checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_sha512_self_test( int verbose );