diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 2e3e6e9..64ee66e 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -371,7 +371,7 @@
                           uint32_t flags );
 
 /**
- * \brief          Verify the certificate signature
+ * \brief          Verify a chain of certificates.
  *
  *                 The verify callback is a user-supplied callback that
  *                 can clear / modify / add flags for a certificate. If set,
@@ -411,22 +411,25 @@
  *                 specific peers you know) - in that case, the self-signed
  *                 certificate doesn't need to have the CA bit set.
  *
- * \param crt      a certificate (chain) to be verified
- * \param trust_ca the list of trusted CAs (see note above)
- * \param ca_crl   the list of CRLs for trusted CAs (see note above)
- * \param cn       expected Common Name (can be set to
- *                 NULL if the CN must not be verified)
- * \param flags    result of the verification
- * \param f_vrfy   verification function
- * \param p_vrfy   verification parameter
+ * \param crt      The certificate chain to be verified.
+ * \param trust_ca The list of trusted CAs.
+ * \param ca_crl   The list of CRLs for trusted CAs.
+ * \param cn       The expected Common Name. This may be \c NULL if the
+ *                 CN need not be verified.
+ * \param flags    The address at which to store the result of the verification.
+ * \param f_vrfy   The verification callback to use. See the documentation
+ *                 of mbedtls_x509_crt_verify() for more information.
+ * \param p_vrfy   The context to be passed to \p f_vrfy.
  *
- * \return         0 (and flags set to 0) if the chain was verified and valid,
- *                 MBEDTLS_ERR_X509_CERT_VERIFY_FAILED if the chain was verified
- *                 but found to be invalid, in which case *flags will have one
- *                 or more MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX
- *                 flags set, or another error (and flags set to 0xffffffff)
- *                 in case of a fatal error encountered during the
- *                 verification process.
+ * \return         \c 0 if the chain is valid with respect to the
+ *                 passed CN, CAs, CRLs and security profile.
+ * \return         #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
+ *                 certificate chain verification failed. In this case,
+ *                 \c *flags will have one or more
+ *                 \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
+ *                 flags set.
+ * \return         Another negative error code in case of a fatal error
+ *                 encountered during the verification process.
  */
 int mbedtls_x509_crt_verify( mbedtls_x509_crt *crt,
                      mbedtls_x509_crt *trust_ca,
@@ -436,7 +439,8 @@
                      void *p_vrfy );
 
 /**
- * \brief          Verify the certificate signature according to profile
+ * \brief          Verify a chain of certificates with respect to
+ *                 a configurable security profile.
  *
  * \note           Same as \c mbedtls_x509_crt_verify(), but with explicit
  *                 security profile.
@@ -445,22 +449,26 @@
  *                 for ECDSA) apply to all certificates: trusted root,
  *                 intermediate CAs if any, and end entity certificate.
  *
- * \param crt      a certificate (chain) to be verified
- * \param trust_ca the list of trusted CAs
- * \param ca_crl   the list of CRLs for trusted CAs
- * \param profile  security profile for verification
- * \param cn       expected Common Name (can be set to
- *                 NULL if the CN must not be verified)
- * \param flags    result of the verification
- * \param f_vrfy   verification function
- * \param p_vrfy   verification parameter
+ * \param crt      The certificate chain to be verified.
+ * \param trust_ca The list of trusted CAs.
+ * \param ca_crl   The list of CRLs for trusted CAs.
+ * \param profile  The security profile to use for the verification.
+ * \param cn       The expected Common Name. This may be \c NULL if the
+ *                 CN need not be verified.
+ * \param flags    The address at which to store the result of the verification.
+ * \param f_vrfy   The verification callback to use. See the documentation
+ *                 of mbedtls_x509_crt_verify() for more information.
+ * \param p_vrfy   The context to be passed to \p f_vrfy.
  *
- * \return         0 if successful or MBEDTLS_ERR_X509_CERT_VERIFY_FAILED
- *                 in which case *flags will have one or more
- *                 MBEDTLS_X509_BADCERT_XXX or MBEDTLS_X509_BADCRL_XXX flags
- *                 set,
- *                 or another error in case of a fatal error encountered
- *                 during the verification process.
+ * \return         \c 0 if the chain is valid with respect to the
+ *                 passed CN, CAs, CRLs and security profile.
+ * \return         #MBEDTLS_ERR_X509_CERT_VERIFY_FAILED in case the
+ *                 certificate chain verification failed. In this case,
+ *                 \c *flags will have one or more
+ *                 \c MBEDTLS_X509_BADCERT_XXX or \c MBEDTLS_X509_BADCRL_XXX
+ *                 flags set.
+ * \return         Another negative error code in case of a fatal error
+ *                 encountered during the verification process.
  */
 int mbedtls_x509_crt_verify_with_profile( mbedtls_x509_crt *crt,
                      mbedtls_x509_crt *trust_ca,
@@ -477,16 +485,18 @@
  *                 but can return early and restart according to the limit
  *                 set with \c mbedtls_ecp_set_max_ops() to reduce blocking.
  *
- * \param crt      a certificate (chain) to be verified
- * \param trust_ca the list of trusted CAs
- * \param ca_crl   the list of CRLs for trusted CAs
- * \param profile  security profile for verification
- * \param cn       expected Common Name (can be set to
- *                 NULL if the CN must not be verified)
- * \param flags    result of the verification
- * \param f_vrfy   verification function
- * \param p_vrfy   verification parameter
- * \param rs_ctx   restart context (NULL to disable restart)
+ * \param crt      The certificate chain to be verified.
+ * \param trust_ca The list of trusted CAs.
+ * \param ca_crl   The list of CRLs for trusted CAs.
+ * \param profile  The security profile to use for the verification.
+ * \param cn       The expected Common Name. This may be \c NULL if the
+ *                 CN need not be verified.
+ * \param flags    The address at which to store the result of the verification.
+ * \param f_vrfy   The verification callback to use. See the documentation
+ *                 of mbedtls_x509_crt_verify() for more information.
+ * \param p_vrfy   The context to be passed to \p f_vrfy.
+ * \param rs_ctx   The restart context to use. This may be set to \c NULL
+ *                 to disable restartable ECC.
  *
  * \return         See \c mbedtls_crt_verify_with_profile(), or
  * \return         #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of