diff --git a/include/mbedtls/chacha20.h b/include/mbedtls/chacha20.h
index d32da1b..579ea38 100644
--- a/include/mbedtls/chacha20.h
+++ b/include/mbedtls/chacha20.h
@@ -1,11 +1,18 @@
 /**
  * \file chacha20.h
  *
- * \brief ChaCha20 cipher.
+ * \brief   This file contains ChaCha20 definitions and functions.
+ *
+ *          ChaCha20 is a stream cipher that can encrypt and decrypt
+ *          information. ChaCha was created by Daniel Bernstein as a variant of
+ *          its Salsa cipher https://cr.yp.to/chacha/chacha-20080128.pdf
+ *          ChaCha20 is the variant with 20 rounds, that was also standardized
+ *          in RFC 7539.
  *
  * \author Daniel King <damaki.gh@gmail.com>
- *
- *  Copyright (C) 2006-2016, 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
@@ -20,8 +27,9 @@
  *  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_CHACHA20_H
 #define MBEDTLS_CHACHA20_H
 
@@ -44,10 +52,10 @@
 
 typedef struct
 {
-    uint32_t initial_state[16];  /*! Holds the initial state (before round operations) */
-    uint32_t working_state[16];  /*! Holds the working state (after round operations) */
-    uint8_t  keystream8[64];     /*! Holds leftover keystream bytes */
-    size_t keystream_bytes_used; /*! Number of keystream bytes currently used */
+    uint32_t initial_state[16];  /*! The initial state (before round operations). */
+    uint32_t working_state[16];  /*! The working state (after round operations). */
+    uint8_t  keystream8[64];     /*! Leftover keystream bytes. */
+    size_t keystream_bytes_used; /*! Number of keystream bytes already used. */
 }
 mbedtls_chacha20_context;
 
@@ -56,118 +64,141 @@
 #endif /* MBEDTLS_CHACHA20_ALT */
 
 /**
- * \brief           Initialize ChaCha20 context
+ * \brief           This function initializes the specified ChaCha20 context.
  *
- * \param ctx       ChaCha20 context to be initialized
+ *                  It must be the first API called before using
+ *                  the context.
+ *
+ *                  It is usually followed by calls to
+ *                  \c mbedtls_chacha20_setkey() and
+ *                  \c mbedtls_chacha20_starts(), then one or more calls to
+ *                  to \c mbedtls_chacha20_update(), and finally to
+ *                  \c mbedtls_chacha20_free().
+ *
+ * \param ctx       The ChaCha20 context to initialize.
  */
 void mbedtls_chacha20_init( mbedtls_chacha20_context *ctx );
 
 /**
- * \brief           Clear ChaCha20 context
+ * \brief           This function releases and clears the specified ChaCha20 context.
  *
- * \param ctx       ChaCha20 context to be cleared
+ * \param ctx       The ChaCha20 context to clear.
  */
 void mbedtls_chacha20_free( mbedtls_chacha20_context *ctx );
 
 /**
- * \brief           Set the ChaCha20 key.
+ * \brief           This function sets the encryption/decryption key.
  *
- * \note            The nonce and counter must be set after calling this function,
- *                  before data can be encrypted/decrypted. The nonce and
- *                  counter are set by calling mbedtls_chacha20_starts.
+ * \note            After using this function, you must also call
+ *                  \c mbedtls_chacha20_starts() to set a nonce before you
+ *                  start encrypting/decrypting data with
+ *                  \c mbedtls_chacha_update().
  *
- * \see             mbedtls_chacha20_starts
+ * \param ctx       The ChaCha20 context to which the key should be bound.
+ * \param key       The encryption/decryption key. Must be 32 bytes in length.
  *
- * \param ctx       The context to setup.
- * \param key       Buffer containing the 256-bit key. Must be 32 bytes in length.
- *
- * \return          MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or key
- *                  is NULL, or if key_bits is not 128 or 256.
- *                  Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or key is NULL.
  */
 int mbedtls_chacha20_setkey( mbedtls_chacha20_context *ctx,
                              const unsigned char key[32] );
 
 /**
- * \brief           Set the ChaCha20 nonce and initial counter value.
+ * \brief           This function sets the nonce and initial counter value.
  *
  * \note            A ChaCha20 context can be re-used with the same key by
- *                  calling this function to change the nonce and/or initial
- *                  counter value.
+ *                  calling this function to change the nonce.
  *
- * \param ctx       The ChaCha20 context.
- * \param nonce     Buffer containing the 96-bit nonce. Must be 12 bytes in size.
- * \param counter   Initial counter value to use. This is usually 0.
+ * \warning         You must never use the same nonce twice with the same key.
+ *                  This would void any confidentiality guarantees for the
+ *                  messages encrypted with the same nonce and key.
  *
- * \return          MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA is returned if ctx or
- *                  nonce is NULL.
- *                  Otherwise, 0 is returned to indicate success.
+ * \param ctx       The ChaCha20 context to which the nonce should be bound.
+ * \param nonce     The nonce. Must be 12 bytes in size.
+ * \param counter   The initial counter value. This is usually 0.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if ctx or nonce is
+ *                  NULL.
  */
 int mbedtls_chacha20_starts( mbedtls_chacha20_context* ctx,
                              const unsigned char nonce[12],
                              uint32_t counter );
 
 /**
- * \brief           Encrypt or decrypt data.
+ * \brief           This function encrypts or decrypts data.
  *
- *                  This function is used to both encrypt and decrypt data.
+ *                  Since ChaCha20 is a stream cipher, the same operation is
+ *                  used for encrypting and decrypting data.
  *
  * \note            The \p input and \p output pointers must either be equal or
  *                  point to non-overlapping buffers.
  *
- * \note            mbedtls_chacha20_setkey and mbedtls_chacha20_starts must be
- *                  called at least once to setup the context before this function
- *                  can be called.
+ * \note            \c mbedtls_chacha20_setkey() and
+ *                  \c mbedtls_chacha20_starts() must be called at least once
+ *                  to setup the context before this function can be called.
  *
- * \param ctx       The ChaCha20 context.
- * \param size      The length (in bytes) to process. This can have any length.
- * \param input     Buffer containing the input data.
+ * \note            This function can be called mutliple times in a row in
+ *                  order to encrypt of decrypt data piecewise with the same
+ *                  key and nonce.
+ *
+ * \param ctx       The ChaCha20 context to use for encryption or decryption.
+ * \param size      The length of the input data in bytes.
+ * \param input     The buffer holding the input data.
  *                  This pointer can be NULL if size == 0.
- * \param output    Buffer containing the output data.
+ * \param output    The buffer holding the output data.
+ *                  Must be able to hold \p size bytes.
  *                  This pointer can be NULL if size == 0.
  *
- * \return          MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if the ctx, input, or
  *                  output pointers are NULL.
- *                  Otherwise, 0 is returned to indicate success.
  */
 int mbedtls_chacha20_update( mbedtls_chacha20_context *ctx,
-                              size_t size,
-                              const unsigned char *input,
-                              unsigned char *output );
+                             size_t size,
+                             const unsigned char *input,
+                             unsigned char *output );
 
 /**
- * \brief           Encrypt or decrypt a message using ChaCha20.
+ * \brief           This function encrypts or decrypts data with ChaCha20 and
+ *                  the given key and nonce.
  *
- *                  This function is used the same way for encrypting and
- *                  decrypting data. It's not necessary to specify which
- *                  operation is being performed.
+ *                  Since ChaCha20 is a stream cipher, the same operation is
+ *                  used for encrypting and decrypting data.
  *
- * \note            The \p input and \p output buffers may overlap, but only
- *                  if input >= output (i.e. only if input points ahead of
- *                  the output pointer).
+ * \warning         You must never use the same (key, nonce) pair more than
+ *                  once. This would void any confidentiality guarantees for
+ *                  the messages encrypted with the same nonce and key.
  *
- * \param key       Buffer containing the 256-bit key. Must be 32 bytes in length.
- * \param nonce     Buffer containing the 96-bit nonce. Must be 12 bytes in length.
+ * \note            The \p input and \p output pointers must either be equal or
+ *                  point to non-overlapping buffers.
+ *
+ * \param key       The encryption/decryption key. Must be 32 bytes in length.
+ * \param nonce     The nonce. Must be 12 bytes in size.
  * \param counter   The initial counter value. This is usually 0.
- * \param data_len  The number of bytes to process.
- * \param input     Buffer containing the input data (data to encrypt or decrypt).
- * \param output    Buffer to where the processed data is written.
+ * \param size      The length of the input data in bytes.
+ * \param input     The buffer holding the input data.
+ *                  This pointer can be NULL if size == 0.
+ * \param output    The buffer holding the output data.
+ *                  Must be able to hold \p size bytes.
+ *                  This pointer can be NULL if size == 0.
  *
- * \return          MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHA20_BAD_INPUT_DATA if key, nonce, input,
  *                  or output is NULL.
- *                  Otherwise, 0 is returned to indicate success.
  */
 int mbedtls_chacha20_crypt( const unsigned char key[32],
                             const unsigned char nonce[12],
                             uint32_t counter,
-                            size_t data_len,
+                            size_t size,
                             const unsigned char* input,
                             unsigned char* output );
 
 /**
- * \brief           Checkup routine
+ * \brief           The ChaCha20 checkup routine.
  *
- * \return          0 if successful, or 1 if the test failed
+ * \return          \c 0 on success.
+ * \return          \c 1 on failure.
  */
 int mbedtls_chacha20_self_test( int verbose );
 
diff --git a/include/mbedtls/chachapoly.h b/include/mbedtls/chachapoly.h
index e7413b3..ddcd549 100644
--- a/include/mbedtls/chachapoly.h
+++ b/include/mbedtls/chachapoly.h
@@ -1,9 +1,18 @@
 /**
  * \file chachapoly.h
  *
- * \brief ChaCha20-Poly1305 AEAD construction based on RFC 7539.
+ * \brief   This file contains the AEAD-ChaCha20-Poly1305 definitions and
+ *          functions.
  *
- *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
+ *          ChaCha20-Poly1305 is an algorithm for Authenticated Encryption
+ *          with Associated Data (AEAD) that can be used to encrypt and
+ *          authenticate data. It is based on ChaCha20 and Poly1305 by Daniel
+ *          Bernstein and was standardized in RFC 7539.
+ *
+ * \author Daniel King <damaki.gh@gmail.com>
+ */
+
+/*  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
@@ -18,8 +27,9 @@
  *  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_CHACHAPOLY_H
 #define MBEDTLS_CHACHAPOLY_H
 
@@ -30,7 +40,7 @@
 #endif
 
 #define MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA -0x00047 /**< Invalid input parameter(s). */
-#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE      -0x00049 /**< The requested operation is not permitted in the current state */
+#define MBEDTLS_ERR_CHACHAPOLY_BAD_STATE      -0x00049 /**< The requested operation is not permitted in the current state. */
 #define MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED    -0x00049 /**< Authenticated decryption failed: data was not authentic. */
 
 
@@ -40,8 +50,8 @@
 
 typedef enum
 {
-    MBEDTLS_CHACHAPOLY_ENCRYPT,
-    MBEDTLS_CHACHAPOLY_DECRYPT
+    MBEDTLS_CHACHAPOLY_ENCRYPT,     /**< The mode value for performing encryption. */
+    MBEDTLS_CHACHAPOLY_DECRYPT      /**< The mode value for performing decryption. */
 }
 mbedtls_chachapoly_mode_t;
 
@@ -52,12 +62,12 @@
 
 typedef struct
 {
-    mbedtls_chacha20_context chacha20_ctx;      /** ChaCha20 context */
-    mbedtls_poly1305_context poly1305_ctx;      /** Poly1305 context */
-    uint64_t aad_len;                           /** Length (bytes) of the Additional Authenticated Data */
-    uint64_t ciphertext_len;                    /** Length (bytes) of the ciphertext */
-    int state;                                  /** Current state of the context */
-    mbedtls_chachapoly_mode_t mode; /** Cipher mode (encrypt or decrypt) */
+    mbedtls_chacha20_context chacha20_ctx;  /**< The ChaCha20 context. */
+    mbedtls_poly1305_context poly1305_ctx;  /**< The Poly1305 context. */
+    uint64_t aad_len;                       /**< The length (bytes) of the Additional Authenticated Data. */
+    uint64_t ciphertext_len;                /**< The length (bytes) of the ciphertext. */
+    int state;                              /**< The current state of the context. */
+    mbedtls_chachapoly_mode_t mode;         /**< Cipher mode (encrypt or decrypt). */
 }
 mbedtls_chachapoly_context;
 
@@ -66,112 +76,144 @@
 #endif /* !MBEDTLS_CHACHAPOLY_ALT */
 
 /**
- * \brief               Initialize ChaCha20-Poly1305 context
+ * \brief           This function initializes the specified ChaCha20-Poly1305 context.
  *
- * \param ctx           ChaCha20-Poly1305 context to be initialized
+ *                  It must be the first API called before using
+ *                  the context. It must be followed by a call to
+ *                  \c mbedtls_chachapoly_setkey() before any operation can be
+ *                  done, and to \c mbedtls_chachapoly_free() once all
+ *                  operations with that context have been finished.
+ *
+ *                  In order to encrypt or decrypt full messages at once, for
+ *                  each message you should make a single call to
+ *                  \c mbedtls_chachapoly_crypt_and_tag() or
+ *                  \c mbedtls_chachapoly_auth_decrypt().
+ *
+ *                  In order to encrypt or decrypt messages piecewise, for each
+ *                  message you should make a call to
+ *                  \c mbedtls_chachapoly_starts(), then 0 or more calls to
+ *                  \c mbedtls_chachapoly_update_aad(), then 0 or more calls to
+ *                  \c mbedtls_chachapoly_update(), then one call to
+ *                  \c mbedtls_chachapoly_finish().
+ *
+ *
+ * \param ctx       The ChachaPoly context to initialize.
  */
 void mbedtls_chachapoly_init( mbedtls_chachapoly_context *ctx );
 
 /**
- * \brief               Clear ChaCha20-Poly1305 context
+ * \brief           This function releases and clears the specified ChaCha20-Poly1305 context.
  *
- * \param ctx           ChaCha20-Poly1305 context to be cleared
+ * \param ctx       The ChachaPoly context to clear.
  */
 void mbedtls_chachapoly_free( mbedtls_chachapoly_context *ctx );
 
 /**
- * \brief               Set the ChaCha20-Poly1305 symmetric encryption key.
+ * \brief           This function sets the ChaCha20-Poly1305 symmetric encryption key.
  *
- * \param ctx           The ChaCha20-Poly1305 context.
- * \param key           The 256-bit (32 bytes) key.
+ * \param ctx       The ChaCha20-Poly1305 context to which the key should be
+ *                  bound.
+ * \param key       The 256-bit (32 bytes) key.
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if \p ctx or \p key are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if \p ctx or \p key are NULL.
  */
 int mbedtls_chachapoly_setkey( mbedtls_chachapoly_context *ctx,
                                const unsigned char key[32] );
 
 /**
- * \brief               Setup ChaCha20-Poly1305 context for encryption or decryption.
+ * \brief           This function starts a ChaCha20-Poly1305 encryption or
+ *                  decryption operation.
  *
- * \note                If the context is being used for AAD only (no data to
- *                      encrypt or decrypt) then \p mode can be set to any value.
+ * \warning         You must never use the same nonce twice with the same key.
+ *                  This would void any confidentiality and authenticity
+ *                  guarantees for the messages encrypted with the same nonce
+ *                  and key.
  *
- * \param ctx           The ChaCha20-Poly1305 context.
- * \param nonce         The nonce/IV to use for the message. This must be unique
- *                      for every message encrypted under the same key.
- * \param mode          Specifies whether the context is used to encrypt or
- *                      decrypt data.
+ * \note            If the context is being used for AAD only (no data to
+ *                  encrypt or decrypt) then \p mode can be set to any value.
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if \p ctx or \p mac are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \param ctx       The ChaCha20-Poly1305 context.
+ * \param nonce     The nonce/IV to use for the message. Must be 12 bytes.
+ * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
+ *                  #MBEDTLS_CHACHAPOLY_DECRYPT.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if \p ctx or \p mac are NULL.
  */
 int mbedtls_chachapoly_starts( mbedtls_chachapoly_context *ctx,
                                const unsigned char nonce[12],
                                mbedtls_chachapoly_mode_t mode );
 
 /**
- * \brief               Process additional authenticated data (AAD).
+ * \brief           This function feeds additional data to be authenticated
+ *                  into an ongoing ChaCha20-Poly1305 operation.
  *
- *                      This function processes data that is authenticated, but
- *                      not encrypted.
+ *                  The Additional Authenticated Data (AAD), also called
+ *                  Associated Data (AD) is only authenticated but not
+ *                  encrypted nor included in the encrypted output. It is
+ *                  usually transmitted separately fro mthe ciphertext or
+ *                  computed locally by each party.
  *
- * \note                This function is called before data is encrypted/decrypted.
- *                      I.e. call this function to process the AAD before calling
- *                      mbedtls_chachapoly_update.
+ * \note            This function is called before data is encrypted/decrypted.
+ *                  I.e. call this function to process the AAD before calling
+ *                  \c mbedtls_chachapoly_update().
  *
- *                      You may call this function multiple times to process
- *                      an arbitrary amount of AAD. It is permitted to call
- *                      this function 0 times, if no AAD is used.
+ *                  You may call this function multiple times to process
+ *                  an arbitrary amount of AAD. It is permitted to call
+ *                  this function 0 times, if no AAD is used.
  *
- *                      This function cannot be called any more if data has
- *                      been processed by mbedtls_chachapoly_update,
- *                      or if the context has been finished.
+ *                  This function cannot be called any more if data has
+ *                  been processed by \c mbedtls_chachapoly_update(),
+ *                  or if the context has been finished.
  *
- * \param ctx           The ChaCha20-Poly1305 context.
- * \param aad_len       The length (in bytes) of the AAD. The length has no
- *                      restrictions.
- * \param aad           Buffer containing the AAD.
- *                      This pointer can be NULL if aad_len == 0.
+ * \param ctx       The ChaCha20-Poly1305 context to use.
+ * \param aad_len   The length (in bytes) of the AAD. The length has no
+ *                  restrictions.
+ * \param aad       Buffer containing the AAD.
+ *                  This pointer can be NULL if aad_len == 0.
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if \p ctx or \p aad are NULL.
- *                      MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
- *                      the context has not been setup, the context has been
- *                      finished, or if the AAD has been finished.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if \p ctx or \p aad are NULL.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
+ *                  if the operations has not been started or has been
+ *                  finished, or if the AAD has been finished.
  */
 int mbedtls_chachapoly_update_aad( mbedtls_chachapoly_context *ctx,
                                    size_t aad_len,
                                    const unsigned char *aad );
 
 /**
- * \brief               Encrypt/decrypt data.
+ * \brief           Thus function feeds data to be encrypted or decrypted
+ *                  into an on-going ChaCha20-Poly1305
+ *                  operation.
  *
- *                      The direction (encryption or decryption) depends on the
- *                      mode that was given when calling
- *                      mbedtls_chachapoly_starts.
+ *                  The direction (encryption or decryption) depends on the
+ *                  mode that was given when calling
+ *                  \c mbedtls_chachapoly_starts().
  *
- *                      You may call this function multiple times to process
- *                      an arbitrary amount of data. It is permitted to call
- *                      this function 0 times, if no data is to be encrypted
- *                      or decrypted.
+ *                  You may call this function multiple times to process
+ *                  an arbitrary amount of data. It is permitted to call
+ *                  this function 0 times, if no data is to be encrypted
+ *                  or decrypted.
  *
- * \param ctx           The ChaCha20-Poly1305 context.
- * \param len           The length (in bytes) of the data to encrypt or decrypt.
- * \param input         Buffer containing the data to encrypt or decrypt.
- *                      This pointer can be NULL if len == 0.
- * \param output        Buffer to where the encrypted or decrypted data is written.
- *                      This pointer can be NULL if len == 0.
+ * \param ctx       The ChaCha20-Poly1305 context to use.
+ * \param len       The length (in bytes) of the data to encrypt or decrypt.
+ * \param input     The buffer containing the data to encrypt or decrypt.
+ *                  This pointer can be NULL if len == 0.
+ * \param output    The buffer to where the encrypted or decrypted data is written.
+ *                  Must be able to hold \p len bytes.
+ *                  This pointer can be NULL if len == 0.
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if \p ctx, \p input, or \p output are NULL.
- *                      MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
- *                      the context has not been setup, or if the context has been
- *                      finished.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if \p ctx, \p input, or \p output are NULL.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
+ *                  if the operation has not been started or has been
+ *                  finished.
  */
 int mbedtls_chachapoly_update( mbedtls_chachapoly_context *ctx,
                                size_t len,
@@ -179,42 +221,51 @@
                                unsigned char *output );
 
 /**
- * \brief               Compute the ChaCha20-Poly1305 MAC.
+ * \brief           This function finished the ChaCha20-Poly1305 operation and
+ *                  generates the MAC (authentication tag).
  *
- * \param ctx           The ChaCha20-Poly1305 context.
- * \param mac           Buffer to where the 128-bit (16 bytes) MAC is written.
+ * \param ctx       The ChaCha20-Poly1305 context to use.
+ * \param mac       The buffer to where the 128-bit (16 bytes) MAC is written.
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if \p ctx or \p mac are NULL.
- *                      MBEDTLS_ERR_CHACHAPOLY_BAD_STATE is returned if
- *                      the context has not been setup.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if \p ctx or \p mac are NULL.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_STATE
+ *                  if the operation has not been started or has been
+ *                  finished.
  */
 int mbedtls_chachapoly_finish( mbedtls_chachapoly_context *ctx,
                                unsigned char mac[16] );
 
 /**
- * \brief               Encrypt or decrypt data, and produce a MAC (tag) with ChaCha20-Poly1305.
+ * \brief           This function performs a complete ChaCha20-Poly1305
+ *                  operation with the previously-set key.
  *
- * \param ctx           The ChachaPoly context.
- * \param mode          Specifies whether the data in the \p input buffer is to
- *                      be encrypted or decrypted. If there is no data to encrypt
- *                      or decrypt (i.e. \p ilen is 0) then the value of this
- *                      parameter does not matter.
- * \param length        The length (in bytes) of the data to encrypt or decrypt.
- * \param nonce         The 96-bit (12 bytes) nonce/IV to use.
- * \param aad           Buffer containing the additional authenticated data (AAD).
- *                      This pointer can be NULL if aad_len == 0.
- * \param aad_len       The length (in bytes) of the AAD data to process.
- * \param input         Buffer containing the data to encrypt or decrypt.
- *                      This pointer can be NULL if ilen == 0.
- * \param output        Buffer to where the encrypted or decrypted data is written.
- *                      This pointer can be NULL if ilen == 0.
- * \param tag           Buffer to where the computed 128-bit (16 bytes) MAC is written.
+ * \note            Before using this function, you must set the key with
+ *                  \c mbedtls_chachapoly_setkey().
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if one or more of the required parameters are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \warning         You must never use the same nonce twice with the same key.
+ *                  This would void any confidentiality and authenticity
+ *                  guarantees for the messages encrypted with the same nonce
+ *                  and key.
+ *
+ * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
+ * \param mode      The operation to perform: #MBEDTLS_CHACHAPOLY_ENCRYPT or
+ *                  #MBEDTLS_CHACHAPOLY_DECRYPT.
+ * \param length    The length (in bytes) of the data to encrypt or decrypt.
+ * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
+ * \param aad       The buffer containing the additional authenticated data (AAD).
+ *                  This pointer can be NULL if aad_len == 0.
+ * \param aad_len   The length (in bytes) of the AAD data to process.
+ * \param input     The buffer containing the data to encrypt or decrypt.
+ *                  This pointer can be NULL if ilen == 0.
+ * \param output    The buffer to where the encrypted or decrypted data is written.
+ *                  This pointer can be NULL if ilen == 0.
+ * \param tag       The buffer to where the computed 128-bit (16 bytes) MAC is written.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if one or more of the required parameters are NULL.
  */
 int mbedtls_chachapoly_crypt_and_tag( mbedtls_chachapoly_context *ctx,
                                       mbedtls_chachapoly_mode_t mode,
@@ -227,22 +278,29 @@
                                       unsigned char tag[16] );
 
 /**
- * \brief           Decrypt data and check a MAC (tag) with ChaCha20-Poly1305.
+ * \brief           This function performs a complete ChaCha20-Poly1305
+ *                  authenticated decryption with the previously-set key.
  *
- * \param ctx       The ChachaPoly context.
- * \param length    The length of the input and output data.
- * \param nonce     The nonce / initialization vector.
- * \param aad       The buffer holding the additional authenticated data.
- * \param aad_len   The length of the additional authenticated data.
- * \param tag       The buffer holding the tag.
- * \param input     The buffer holding the input data.
- * \param output    The buffer for holding the output data.
+ * \note            Before using this function, you must set the key with
+ *                  \c mbedtls_chachapoly_setkey().
  *
- * \return              MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA is returned
- *                      if one or more of the required parameters are NULL.
- *                      MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED if the tag does not
- *                      match.
- *                      Otherwise, 0 is returned to indicate success.
+ * \param ctx       The ChaCha20-Poly1305 context to use (holds the key).
+ * \param length    The length (in bytes) of the data to decrypt.
+ * \param nonce     The 96-bit (12 bytes) nonce/IV to use.
+ * \param aad       The buffer containing the additional authenticated data (AAD).
+ *                  This pointer can be NULL if aad_len == 0.
+ * \param aad_len   The length (in bytes) of the AAD data to process.
+ * \param tag       The buffer holding the authentication tag.
+ * \param input     The buffer containing the data to decrypt.
+ *                  This pointer can be NULL if ilen == 0.
+ * \param output    The buffer to where the decrypted data is written.
+ *                  This pointer can be NULL if ilen == 0.
+ *
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_BAD_INPUT_DATA
+ *                  if one or more of the required parameters are NULL.
+ * \return          #MBEDTLS_ERR_CHACHAPOLY_AUTH_FAILED
+ *                  if the data was not authentic.
  */
 int mbedtls_chachapoly_auth_decrypt( mbedtls_chachapoly_context *ctx,
                                      size_t length,
@@ -254,9 +312,10 @@
                                      unsigned char *output );
 
 /**
- * \brief               Checkup routine
+ * \brief           The ChaCha20-Poly1305 checkup routine.
  *
- * \return              0 if successful, or 1 if the test failed
+ * \return          \c 0 on success.
+ * \return          \c 1 on failure.
  */
 int mbedtls_chachapoly_self_test( int verbose );
 
diff --git a/include/mbedtls/cipher.h b/include/mbedtls/cipher.h
index ac1f564..591aa79 100644
--- a/include/mbedtls/cipher.h
+++ b/include/mbedtls/cipher.h
@@ -86,7 +86,7 @@
     MBEDTLS_CIPHER_ID_CAMELLIA,  /**< The Camellia cipher. */
     MBEDTLS_CIPHER_ID_BLOWFISH,  /**< The Blowfish cipher. */
     MBEDTLS_CIPHER_ID_ARC4,      /**< The RC4 cipher. */
-    MBEDTLS_CIPHER_ID_CHACHA20,  /**< The Chacha20 cipher. */
+    MBEDTLS_CIPHER_ID_CHACHA20,  /**< The ChaCha20 cipher. */
 } mbedtls_cipher_id_t;
 
 /**
@@ -146,8 +146,8 @@
     MBEDTLS_CIPHER_CAMELLIA_128_CCM,     /**< Camellia cipher with 128-bit CCM mode. */
     MBEDTLS_CIPHER_CAMELLIA_192_CCM,     /**< Camellia cipher with 192-bit CCM mode. */
     MBEDTLS_CIPHER_CAMELLIA_256_CCM,     /**< Camellia cipher with 256-bit CCM mode. */
-    MBEDTLS_CIPHER_CHACHA20,             /**< Chacha20 stream cipher. */
-    MBEDTLS_CIPHER_CHACHA20_POLY1305,    /**< Chacha20-Poly1305 AEAD cipher. */
+    MBEDTLS_CIPHER_CHACHA20,             /**< ChaCha20 stream cipher. */
+    MBEDTLS_CIPHER_CHACHA20_POLY1305,    /**< ChaCha20-Poly1305 AEAD cipher. */
 } mbedtls_cipher_type_t;
 
 /** Supported cipher modes. */
diff --git a/include/mbedtls/poly1305.h b/include/mbedtls/poly1305.h
index f691915..c2e2655 100644
--- a/include/mbedtls/poly1305.h
+++ b/include/mbedtls/poly1305.h
@@ -1,9 +1,18 @@
 /**
  * \file poly1305.h
  *
- * \brief Poly1305 authenticator algorithm.
+ * \brief   This file containts Poly1305 definitions and functions.
  *
- *  Copyright (C) 2006-2016, ARM Limited, All Rights Reserved
+ *          Poly1305 is a one-time message authenticator that can be used to
+ *          authenticate messages. Poly1305-AES was created by Daniel
+ *          Bernstein https://cr.yp.to/mac/poly1305-20050329.pdf The generic
+ *          Poly1305 algorithm (not tied to AES) was also standardized in RFC
+ *          7539.
+ *
+ * \author Daniel King <damaki.gh@gmail.com>
+ */
+
+/*  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
@@ -18,8 +27,9 @@
  *  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_POLY1305_H
 #define MBEDTLS_POLY1305_H
 
@@ -42,11 +52,11 @@
 
 typedef struct
 {
-    uint32_t r[4];      /** Stores the value for 'r' (low 128 bits of the key) */
-    uint32_t s[4];      /** Stores the value for 's' (high 128 bits of the key) */
-    uint32_t acc[5];    /** Accumulator number */
-    uint8_t queue[16];  /** Stores partial block data */
-    size_t queue_len;   /** Number of bytes stored in 'queue'. Always less than 16 */
+    uint32_t r[4];      /** The value for 'r' (low 128 bits of the key). */
+    uint32_t s[4];      /** The value for 's' (high 128 bits of the key). */
+    uint32_t acc[5];    /** The accumulator number. */
+    uint8_t queue[16];  /** The current partial block of data. */
+    size_t queue_len;   /** The number of bytes stored in 'queue'. */
 }
 mbedtls_poly1305_context;
 
@@ -55,82 +65,97 @@
 #endif /* MBEDTLS_POLY1305_ALT */
 
 /**
- * \brief               Initialize a Poly1305 context
+ * \brief           This function initializes the specified Poly1305 context.
  *
- * \param ctx           The Poly1305 context to be initialized
+ *                  It must be the first API called before using
+ *                  the context.
+ *
+ *                  It is usually followed by a call to
+ *                  \c mbedtls_poly1305_starts(), then one or more calls to
+ *                  \c mbedtls_poly1305_update(), then one call to
+ *                  \c mbedtls_poly1305_finish(), then finally
+ *                  \c mbedtls_poly1305_free().
+ *
+ * \param ctx       The Poly1305 context to initialize.
  */
 void mbedtls_poly1305_init( mbedtls_poly1305_context *ctx );
 
 /**
- * \brief               Clear a Poly1305 context
+ * \brief           This function releases and clears the specified Poly1305 context.
  *
- * \param ctx           The Poly1305 context to be cleared
+ * \param ctx       The Poly1305 context to clear.
  */
 void mbedtls_poly1305_free( mbedtls_poly1305_context *ctx );
 
 /**
- * \brief               Set the Poly1305 authentication key.
+ * \brief           This function sets the one-time authentication key.
  *
- * \warning             The key should be unique, and \b MUST be
- *                      unpredictable for each invocation of Poly1305.
+ * \warning         The key must be unique and unpredictable for each
+ *                  invocation of Poly1305.
  *
- * \param ctx           The Poly1305 context.
- * \param key           Buffer containing the 256-bit key.
+ * \param ctx       The Poly1305 context to which the key should be bound.
+ * \param key       The buffer containing the 256-bit key.
  *
- * \return              MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
- *                      or key are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
+ *                  if ctx or key are NULL.
  */
 int mbedtls_poly1305_starts( mbedtls_poly1305_context *ctx,
                              const unsigned char key[32] );
 
 /**
- * \brief               Process data with Poly1305.
+ * \brief           This functions feeds an input bufer into an ongoing
+ *                  Poly1305 computation.
  *
- *                      This function can be called multiple times to process
- *                      a stream of data.
+ *                  It is called between \c mbedtls_cipher_cmac_starts() and
+ *                  \c mbedtls_cipher_cmac_finish().
+ *                  Can be called repeatedly to process a stream of data.
  *
- * \param ctx           The Poly1305 context.
- * \param ilen          The input length (in bytes). Any value is accepted.
- * \param input         Buffer containing the input data to Process.
- *                      This pointer can be NULL if ilen == 0.
+ * \param ctx       The Poly1305 context to use for the Poly1305 operation.
+ * \param ilen      The length of the input data (in bytes). Any value is accepted.
+ * \param input     The buffer holding the input data.
+ *                  This pointer can be NULL if ilen == 0.
  *
- * \return              MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
- *                      or input are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
+ *                  if ctx or input are NULL.
  */
 int mbedtls_poly1305_update( mbedtls_poly1305_context *ctx,
                              size_t ilen,
                              const unsigned char *input );
 
 /**
- * \brief               Generate the Poly1305 MAC.
+ * \brief           This function generates the Poly1305 Message
+ *                  Authentication Code (MAC).
  *
- * \param ctx           The Poly1305 context.
- * \param mac           Buffer to where the MAC is written. Must be big enough
- *                      to hold the 16-byte MAC.
+ * \param ctx       The Poly1305 context to use for the Poly1305 operation.
+ * \param mac       The buffer to where the MAC is written. Must be big enough
+ *                  to hold the 16-byte MAC.
  *
- * \return              MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if ctx
- *                      or mac are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
+ *                  if ctx or mac are NULL.
  */
 int mbedtls_poly1305_finish( mbedtls_poly1305_context *ctx,
                              unsigned char mac[16] );
 
 /**
- * \brief               Generate the Poly1305 MAC of some data with the given key.
+ * \brief           This function calculates the Poly1305 MAC of the input
+ *                  buffer with the provided key.
  *
- * \warning             The key should be unique, and \b MUST be
- *                      unpredictable for each invocation of Poly1305.
+ * \warning         The key must be unique and unpredictable for each
+ *                  invocation of Poly1305.
  *
- * \param key           Buffer containing the 256-bit (32 bytes) key.
- * \param ilen          The length of the input data (in bytes).
- * \param input         Buffer containing the input data to process.
- * \param mac           Buffer to where the 128-bit (16 bytes) MAC is written.
+ * \param key       The buffer containing the 256-bit key.
+ * \param ilen      The length of the input data (in bytes). Any value is accepted.
+ * \param input     The buffer holding the input data.
+ *                  This pointer can be NULL if ilen == 0.
+ * \param mac       The buffer to where the MAC is written. Must be big enough
+ *                  to hold the 16-byte MAC.
  *
- * \return              MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA is returned if key,
- *                      input, or mac are NULL.
- *                      Otherwise, 0 is returned to indicate success.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_POLY1305_BAD_INPUT_DATA
+ *                  if key, input, or mac are NULL.
  */
 int mbedtls_poly1305_mac( const unsigned char key[32],
                           size_t ilen,
@@ -138,9 +163,10 @@
                           unsigned char mac[16] );
 
 /**
- * \brief               Checkup routine
+ * \brief           The Poly1305 checkup routine.
  *
- * \return              0 if successful, or 1 if the test failed
+ * \return          \c 0 on success.
+ * \return          \c 1 on failure.
  */
 int mbedtls_poly1305_self_test( int verbose );