diff --git a/include/mbedtls/gcm.h b/include/mbedtls/gcm.h
index 1e5a507a2..119e2752e 100644
--- a/include/mbedtls/gcm.h
+++ b/include/mbedtls/gcm.h
@@ -1,9 +1,11 @@
 /**
  * \file gcm.h
  *
- * \brief Galois/Counter Mode (GCM) for 128-bit block ciphers, as defined
- *        in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
- *        (GCM), Natl. Inst. Stand. Technol.</em>
+ * \brief This file contains GCM definitions and functions.
+ *
+ * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
+ * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
+ * (GCM), Natl. Inst. Stand. Technol.</em>
  *
  * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
  * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
@@ -91,7 +93,8 @@ void mbedtls_gcm_init( mbedtls_gcm_context *ctx );
  *                  <li>192 bits</li>
  *                  <li>256 bits</li></ul>
  *
- * \return          \c 0 on success, or a cipher specific error code.
+ * \return          \c 0 on success.
+ * \return          A cipher-specific error code on failure.
  */
 int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
                         mbedtls_cipher_id_t cipher,
@@ -101,15 +104,16 @@ int mbedtls_gcm_setkey( mbedtls_gcm_context *ctx,
 /**
  * \brief           This function performs GCM encryption or decryption of a buffer.
  *
- * \note For encryption, the output buffer can be the same as the input buffer.
- *       For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For encryption, the output buffer can be the same as the
+ *                  input buffer. For decryption, the output buffer cannot be
+ *                  the same as input buffer. If the buffers overlap, the output
+ *                  buffer must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context to use for encryption or decryption.
  * \param mode      The operation to perform: #MBEDTLS_GCM_ENCRYPT or
  *                  #MBEDTLS_GCM_DECRYPT.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple of 
+ *                  16 except in the last call before mbedtls_gcm_finish().
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
  * \param add       The buffer holding the additional data.
@@ -137,12 +141,13 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
  * \brief           This function performs a GCM authenticated decryption of a
  *                  buffer.
  *
- * \note For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For decryption, the output buffer cannot be the same as
+ *                  input buffer. If the buffers overlap, the output buffer
+ *                  must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple
+ *                  of 16 except in the last call before mbedtls_gcm_finish().
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
  * \param add       The buffer holding the additional data.
@@ -152,8 +157,8 @@ int mbedtls_gcm_crypt_and_tag( mbedtls_gcm_context *ctx,
  * \param input     The buffer holding the input data.
  * \param output    The buffer for holding the output data.
  *
- * \return         0 if successful and authenticated, or
- *                 #MBEDTLS_ERR_GCM_AUTH_FAILED if tag does not match.
+ * \return         0 if successful and authenticated.
+ * \return         #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
  */
 int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
                       size_t length,
@@ -175,10 +180,12 @@ int mbedtls_gcm_auth_decrypt( mbedtls_gcm_context *ctx,
  *                  #MBEDTLS_GCM_DECRYPT.
  * \param iv        The initialization vector.
  * \param iv_len    The length of the IV.
- * \param add       The buffer holding the additional data, or NULL if \p add_len is 0.
- * \param add_len   The length of the additional data. If 0, \p  add is NULL.
+ * \param add       The buffer holding the additional data, or NULL
+ *                  if \p add_len is 0.
+ * \param add_len   The length of the additional data. If 0,
+ *                  \p add is NULL.
  *
- * \return         \c 0 on success.
+ * \return          \c 0 on success.
  */
 int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
                 int mode,
@@ -195,16 +202,18 @@ int mbedtls_gcm_starts( mbedtls_gcm_context *ctx,
  *                  Bytes. Only the last call before calling
  *                  mbedtls_gcm_finish() can be less than 16 Bytes.
  *
- * \note For decryption, the output buffer cannot be the same as input buffer.
- *       If the buffers overlap, the output buffer must trail at least 8 Bytes
- *       behind the input buffer.
+ * \note            For decryption, the output buffer cannot be the same as
+ *                  input buffer. If the buffers overlap, the output buffer
+ *                  must trail at least 8 Bytes behind the input buffer.
  *
  * \param ctx       The GCM context.
- * \param length    The length of the input data. This must be a multiple of 16 except in the last call before mbedtls_gcm_finish().
+ * \param length    The length of the input data. This must be a multiple of
+ *                  16 except in the last call before mbedtls_gcm_finish().
  * \param input     The buffer holding the input data.
  * \param output    The buffer for holding the output data.
  *
- * \return         \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return         \c 0 on success.
+ * \return         #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
                 size_t length,
@@ -222,7 +231,8 @@ int mbedtls_gcm_update( mbedtls_gcm_context *ctx,
  * \param tag       The buffer for holding the tag.
  * \param tag_len   The length of the tag to generate. Must be at least four.
  *
- * \return          \c 0 on success, or #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
+ * \return          \c 0 on success.
+ * \return          #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
  */
 int mbedtls_gcm_finish( mbedtls_gcm_context *ctx,
                 unsigned char *tag,
@@ -251,7 +261,8 @@ extern "C" {
 /**
  * \brief          The GCM checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_gcm_self_test( int verbose );