diff --git a/include/mbedtls/sha256.h b/include/mbedtls/sha256.h
index 5c5d07a..a2b6e11 100644
--- a/include/mbedtls/sha256.h
+++ b/include/mbedtls/sha256.h
@@ -1,10 +1,10 @@
 /**
  * \file sha256.h
  *
- * \brief SHA-224 and SHA-256 cryptographic hash function
+ * \brief The SHA-224 and SHA-256 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_SHA256_H
 #define MBEDTLS_SHA256_H
@@ -39,7 +39,6 @@
     !defined(inline) && !defined(__cplusplus)
 #define inline __inline
 #endif
-
 #if !defined(MBEDTLS_SHA256_ALT)
 // Regular implementation
 //
@@ -49,81 +48,94 @@
 #endif
 
 /**
- * \brief          SHA-256 context structure
+ * \brief          The SHA-256 context structure.
+ *
+ *                 The structure is used both for SHA-256 and for SHA-224
+ *                 checksum calculations. The choice between these two is
+ *                 made in the call to mbedtls_sha256_starts_ret().
  */
 typedef struct
 {
-    uint32_t total[2];          /*!< number of bytes processed  */
-    uint32_t state[8];          /*!< intermediate digest state  */
-    unsigned char buffer[64];   /*!< data block being processed */
-    int is224;                  /*!< 0 => SHA-256, else SHA-224 */
+    uint32_t total[2];          /*!< The number of Bytes processed.  */
+    uint32_t state[8];          /*!< The intermediate digest state.  */
+    unsigned char buffer[64];   /*!< The data block being processed. */
+    int is224;                  /*!< Determines which function to use.
+                                     <ul><li>0: Use SHA-256.</li>
+                                     <li>1: Use SHA-224.</li></ul> */
 }
 mbedtls_sha256_context;
 
 /**
- * \brief          Initialize SHA-256 context
+ * \brief          This function initializes a SHA-256 context.
  *
- * \param ctx      SHA-256 context to be initialized
+ * \param ctx      The SHA-256 context to initialize.
  */
 void mbedtls_sha256_init( mbedtls_sha256_context *ctx );
 
 /**
- * \brief          Clear SHA-256 context
+ * \brief          This function clears a SHA-256 context.
  *
- * \param ctx      SHA-256 context to be cleared
+ * \param ctx      The SHA-256 context to clear.
  */
 void mbedtls_sha256_free( mbedtls_sha256_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-256 context
+ * \brief          This function clones the state of a SHA-256 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_sha256_clone( mbedtls_sha256_context *dst,
                            const mbedtls_sha256_context *src );
 
 /**
- * \brief          SHA-256 context setup
+ * \brief          This function starts a SHA-224 or SHA-256 checksum
+ *                 calculation.
  *
- * \param ctx      context to be initialized
- * \param is224    0 = use SHA256, 1 = use SHA224
+ * \param ctx      The context to initialize.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha256_starts_ret( mbedtls_sha256_context *ctx, int is224 );
 
 /**
- * \brief          SHA-256 process buffer
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-256 checksum calculation.
  *
  * \param ctx      SHA-256 context
  * \param input    buffer holding the data
  * \param ilen     length of the input data
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha256_update_ret( mbedtls_sha256_context *ctx,
                                const unsigned char *input,
                                size_t ilen );
 
 /**
- * \brief          SHA-256 final digest
+ * \brief          This function finishes the SHA-256 operation, and writes
+ *                 the result to the output buffer.
  *
- * \param ctx      SHA-256 context
- * \param output   SHA-224/256 checksum result
+ * \param ctx      The SHA-256 context.
+ * \param output   The SHA-224 or SHA-256 checksum result.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_sha256_finish_ret( mbedtls_sha256_context *ctx,
                                unsigned char output[32] );
 
 /**
- * \brief          SHA-256 process data block (internal use only)
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-256 computation. This function is for
+ *                 internal use only.
  *
- * \param ctx      SHA-256 context
- * \param data     buffer holding one block of data
+ * \param ctx      The SHA-256 context.
+ * \param data     The buffer holding one block of data.
  *
- * \return         0 if successful
+ * \return         \c 0 on success.
  */
 int mbedtls_internal_sha256_process( mbedtls_sha256_context *ctx,
                                      const unsigned char data[64] );
@@ -135,12 +147,14 @@
 #define MBEDTLS_DEPRECATED
 #endif
 /**
- * \brief          SHA-256 context setup
+ * \brief          This function starts a SHA-256 checksum calculation.
  *
- * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha256_starts_ret() in 2.7.0.
  *
- * \param ctx      context to be initialized
- * \param is224    0 = use SHA256, 1 = use SHA224
+ * \param ctx      The SHA-256 context to initialize.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha256_starts(
                                                 mbedtls_sha256_context *ctx,
@@ -150,13 +164,14 @@
 }
 
 /**
- * \brief          SHA-256 process buffer
+ * \brief          This function feeds an input buffer into an ongoing
+ *                 SHA-256 checksum calculation.
  *
- * \deprecated     Superseded by mbedtls_sha256_update_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha256_update_ret() in 2.7.0.
  *
- * \param ctx      SHA-256 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-256 context to initialize.
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha256_update(
                                                 mbedtls_sha256_context *ctx,
@@ -167,12 +182,13 @@
 }
 
 /**
- * \brief          SHA-256 final digest
+ * \brief          This function finishes the SHA-256 operation, and writes
+ *                 the result to the output buffer.
  *
- * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0
+ * \deprecated     Superseded by mbedtls_sha256_finish_ret() in 2.7.0.
  *
- * \param ctx      SHA-256 context
- * \param output   SHA-224/256 checksum result
+ * \param ctx      The SHA-256 context.
+ * \param output   The SHA-224or SHA-256 checksum result.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha256_finish(
                                                 mbedtls_sha256_context *ctx,
@@ -182,12 +198,14 @@
 }
 
 /**
- * \brief          SHA-256 process data block (internal use only)
+ * \brief          This function processes a single data block within
+ *                 the ongoing SHA-256 computation. This function is for
+ *                 internal use only.
  *
- * \deprecated     Superseded by mbedtls_internal_sha256_process() in 2.7.0
+ * \deprecated     Superseded by mbedtls_internal_sha256_process() in 2.7.0.
  *
- * \param ctx      SHA-256 context
- * \param data     buffer holding one block of data
+ * \param ctx      The SHA-256 context.
+ * \param data     The buffer holding one block of data.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha256_process(
                                                 mbedtls_sha256_context *ctx,
@@ -198,7 +216,6 @@
 
 #undef MBEDTLS_DEPRECATED
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
-
 #ifdef __cplusplus
 }
 #endif
@@ -212,14 +229,21 @@
 #endif
 
 /**
- * \brief          Output = SHA-256( input buffer )
+ * \brief          This function calculates the SHA-224 or SHA-256
+ *                 checksum of a buffer.
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-224/256 checksum result
- * \param is224    0 = use SHA256, 1 = use SHA224
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
  *
- * \return         0 if successful
+ *                 The SHA-256 result is calculated as
+ *                 output = SHA-256(input buffer).
+ *
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ * \param output   The SHA-224 or SHA-256 checksum result.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
  */
 int mbedtls_sha256_ret( const unsigned char *input,
                         size_t ilen,
@@ -232,15 +256,25 @@
 #else
 #define MBEDTLS_DEPRECATED
 #endif
+
 /**
- * \brief          Output = SHA-256( input buffer )
+ * \brief          This function calculates the SHA-224 or SHA-256 checksum
+ *                 of a buffer.
  *
- * \deprecated     Superseded by mbedtls_sha256_ret() in 2.7.0
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-224/256 checksum result
- * \param is224    0 = use SHA256, 1 = use SHA224
+ *                 The SHA-256 result is calculated as
+ *                 output = SHA-256(input buffer).
+ *
+ * \deprecated     Superseded by mbedtls_sha256_ret() in 2.7.0.
+ *
+ * \param input    The buffer holding the data.
+ * \param ilen     The length of the input data.
+ * \param output   The SHA-224 or SHA-256 checksum result.
+ * \param is224    Determines which function to use.
+ *                 <ul><li>0: Use SHA-256.</li>
+ *                 <li>1: Use SHA-224.</li></ul>
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha256(
                                                     const unsigned char *input,
@@ -255,9 +289,9 @@
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
- * \brief          Checkup routine
+ * \brief          The SHA-224 and SHA-256 checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_sha256_self_test( int verbose );