diff --git a/include/mbedtls/sha1.h b/include/mbedtls/sha1.h
index 4d3a164..700a348 100644
--- a/include/mbedtls/sha1.h
+++ b/include/mbedtls/sha1.h
@@ -1,10 +1,10 @@
 /**
  * \file sha1.h
  *
- * \brief SHA-1 cryptographic hash function
+ * \brief The SHA-1 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_SHA1_H
 #define MBEDTLS_SHA1_H
@@ -49,68 +49,70 @@
 #endif
 
 /**
- * \brief          SHA-1 context structure
+ * \brief          The SHA-1 context structure.
  */
 typedef struct
 {
-    uint32_t total[2];          /*!< number of bytes processed  */
-    uint32_t state[5];          /*!< intermediate digest state  */
-    unsigned char buffer[64];   /*!< data block being processed */
+    uint32_t total[2];          /*!< The number of Bytes processed.  */
+    uint32_t state[5];          /*!< The intermediate digest state.  */
+    unsigned char buffer[64];   /*!< The data block being processed. */
 }
 mbedtls_sha1_context;
 
 /**
- * \brief          Initialize SHA-1 context
+ * \brief          This function initializes a SHA-1 context.
  *
- * \param ctx      SHA-1 context to be initialized
+ * \param ctx      The SHA-1 context to initialize.
  */
 void mbedtls_sha1_init( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          Clear SHA-1 context
+ * \brief          This function clears a SHA-1 context.
  *
- * \param ctx      SHA-1 context to be cleared
+ * \param ctx      The SHA-1 context to clear.
  */
 void mbedtls_sha1_free( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          Clone (the state of) a SHA-1 context
+ * \brief          This function clones the state of a SHA-1 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_sha1_clone( mbedtls_sha1_context *dst,
                          const mbedtls_sha1_context *src );
 
 /**
- * \brief          SHA-1 context setup
+ * \brief          This function starts a SHA-1 checksum calculation.
  *
- * \param ctx      context to be initialized
+ * \param ctx      The context to initialize.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful
  */
 int mbedtls_sha1_starts_ret( mbedtls_sha1_context *ctx );
 
 /**
- * \brief          SHA-1 process buffer
+ * \brief          This function feeds an input buffer into an ongoing SHA-1
+ *                 checksum calculation.
  *
- * \param ctx      SHA-1 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful
  */
 int mbedtls_sha1_update_ret( mbedtls_sha1_context *ctx,
                              const unsigned char *input,
                              size_t ilen );
 
 /**
- * \brief          SHA-1 final digest
+ * \brief          This function finishes the SHA-1 operation, and writes
+ *                 the result to the output buffer.
  *
- * \param ctx      SHA-1 context
- * \param output   SHA-1 checksum result
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful
  */
 int mbedtls_sha1_finish_ret( mbedtls_sha1_context *ctx,
                              unsigned char output[20] );
@@ -119,9 +121,9 @@
  * \brief          SHA-1 process data block (internal use only)
  *
  * \param ctx      SHA-1 context
- * \param data     buffer holding one block of data
+ * \param data     The data block being processed.
  *
- * \return         0 if successful
+ * \return         \c 0 if successful
  */
 int mbedtls_internal_sha1_process( mbedtls_sha1_context *ctx,
                                    const unsigned char data[64] );
@@ -137,7 +139,7 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_starts_ret() in 2.7.0
  *
- * \param ctx      context to be initialized
+ * \param ctx      The SHA-1 context to be initialized.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha1_starts(
                                                 mbedtls_sha1_context *ctx )
@@ -150,9 +152,9 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_update_ret() in 2.7.0
  *
- * \param ctx      SHA-1 context
- * \param input    buffer holding the data
- * \param ilen     length of the input data
+ * \param ctx      The SHA-1 context.
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha1_update(
                                                 mbedtls_sha1_context *ctx,
@@ -167,8 +169,8 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_finish_ret() in 2.7.0
  *
- * \param ctx      SHA-1 context
- * \param output   SHA-1 checksum result
+ * \param ctx      The SHA-1 context.
+ * \param output   The SHA-1 checksum result.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha1_finish(
                                                 mbedtls_sha1_context *ctx,
@@ -182,8 +184,8 @@
  *
  * \deprecated     Superseded by mbedtls_internal_sha1_process() in 2.7.0
  *
- * \param ctx      SHA-1 context
- * \param data     buffer holding one block of data
+ * \param ctx      The SHA-1 context.
+ * \param data     The data block being processed.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha1_process(
                                                 mbedtls_sha1_context *ctx,
@@ -208,13 +210,19 @@
 #endif
 
 /**
- * \brief          Output = SHA-1( input buffer )
+ * \brief          This function calculates the SHA-1 checksum of a buffer.
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-1 checksum result
+ *                 The function allocates the context, performs the
+ *                 calculation, and frees the context.
  *
- * \return         0 if successful
+ *                 The SHA-1 result is calculated as
+ *                 output = SHA-1(input buffer).
+ *
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ * \param output   The SHA-1 checksum result.
+ *
+ * \return         \c 0 if successful
  */
 int mbedtls_sha1_ret( const unsigned char *input,
                       size_t ilen,
@@ -231,9 +239,9 @@
  *
  * \deprecated     Superseded by mbedtls_sha1_ret() in 2.7.0
  *
- * \param input    buffer holding the data
- * \param ilen     length of the input data
- * \param output   SHA-1 checksum result
+ * \param input    The buffer holding the input data.
+ * \param ilen     The length of the input data.
+ * \param output   The SHA-1 checksum result.
  */
 MBEDTLS_DEPRECATED static inline void mbedtls_sha1( const unsigned char *input,
                                                     size_t ilen,
@@ -246,9 +254,9 @@
 #endif /* !MBEDTLS_DEPRECATED_REMOVED */
 
 /**
- * \brief          Checkup routine
+ * \brief          The SHA-1 checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_sha1_self_test( int verbose );