diff --git a/include/mbedtls/cmac.h b/include/mbedtls/cmac.h
index 628c9daba..b9c6f2210 100644
--- a/include/mbedtls/cmac.h
+++ b/include/mbedtls/cmac.h
@@ -1,8 +1,10 @@
 /**
  * \file cmac.h
  *
- * \brief The Cipher-based Message Authentication Code (CMAC) Mode for
- *        Authentication.
+ * \brief This file contains CMAC definitions and functions.
+ *
+ * The Cipher-based Message Authentication Code (CMAC) Mode for
+ * Authentication is defined in <em>RFC-4493: The AES-CMAC Algorithm</em>.
  */
 /*
  *  Copyright (C) 2015-2018, Arm Limited (or its affiliates), All Rights Reserved
@@ -38,9 +40,9 @@ extern "C" {
 #define MBEDTLS_DES3_BLOCK_SIZE         8
 
 #if defined(MBEDTLS_AES_C)
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /* The longest block used by CMAC is that of AES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      16  /**< The longest block used by CMAC is that of AES. */
 #else
-#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /* The longest block used by CMAC is that of 3DES. */
+#define MBEDTLS_CIPHER_BLKSIZE_MAX      8   /**< The longest block used by CMAC is that of 3DES. */
 #endif
 
 #if !defined(MBEDTLS_CMAC_ALT)
@@ -67,16 +69,15 @@ struct mbedtls_cmac_context_t
  *                      Must be called with an initialized cipher context.
  *
  * \param ctx           The cipher context used for the CMAC operation, initialized
- *                      as one of the following types:<ul>
- *                      <li>MBEDTLS_CIPHER_AES_128_ECB</li>
- *                      <li>MBEDTLS_CIPHER_AES_192_ECB</li>
- *                      <li>MBEDTLS_CIPHER_AES_256_ECB</li>
- *                      <li>MBEDTLS_CIPHER_DES_EDE3_ECB</li></ul>
+ *                      as one of the following types: MBEDTLS_CIPHER_AES_128_ECB,
+ *                      MBEDTLS_CIPHER_AES_192_ECB, MBEDTLS_CIPHER_AES_256_ECB,
+ *                      or MBEDTLS_CIPHER_DES_EDE3_ECB.
  * \param key           The CMAC key.
  * \param keybits       The length of the CMAC key in bits.
  *                      Must be supported by the cipher.
  *
- * \return              \c 0 on success, or a cipher-specific error code.
+ * \returns             \c 0 on success.
+ * \returns             A cipher-specific error code on failure.
  */
 int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *key, size_t keybits );
@@ -93,8 +94,9 @@ int mbedtls_cipher_cmac_starts( mbedtls_cipher_context_t *ctx,
  * \param input         The buffer holding the input data.
  * \param ilen          The length of the input data.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
- *                      if parameter verification fails.
+ * \returns            \c 0 on success.
+ * \returns            #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ *                     if parameter verification fails.
  */
 int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
                                 const unsigned char *input, size_t ilen );
@@ -110,7 +112,8 @@ int mbedtls_cipher_cmac_update( mbedtls_cipher_context_t *ctx,
  * \param ctx           The cipher context used for the CMAC operation.
  * \param output        The output buffer for the CMAC checksum result.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \returns             \c 0 on success.
+ * \returns             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
@@ -126,7 +129,8 @@ int mbedtls_cipher_cmac_finish( mbedtls_cipher_context_t *ctx,
  *
  * \param ctx           The cipher context used for the CMAC operation.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \returns             \c 0 on success.
+ * \returns             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
@@ -149,7 +153,8 @@ int mbedtls_cipher_cmac_reset( mbedtls_cipher_context_t *ctx );
  * \param ilen          The length of the input data.
  * \param output        The buffer for the generic CMAC result.
  *
- * \returns             \c 0 on success, or #MBEDTLS_ERR_MD_BAD_INPUT_DATA
+ * \returns             \c 0 on success.
+ * \returns             #MBEDTLS_ERR_MD_BAD_INPUT_DATA
  *                      if parameter verification fails.
  */
 int mbedtls_cipher_cmac( const mbedtls_cipher_info_t *cipher_info,
@@ -196,7 +201,8 @@ extern "C" {
 /**
  * \brief          The CMAC checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_cmac_self_test( int verbose );
 #endif /* MBEDTLS_SELF_TEST && ( MBEDTLS_AES_C || MBEDTLS_DES_C ) */