diff --git a/include/mbedtls/pkcs5.h b/include/mbedtls/pkcs5.h
index aaf8fe7..be54b25 100644
--- a/include/mbedtls/pkcs5.h
+++ b/include/mbedtls/pkcs5.h
@@ -69,7 +69,7 @@
  *                   time, this function does not validate the CBC padding.
  *
  * \param pbe_params the ASN.1 algorithm parameters
- * \param mode       either MBEDTLS_PKCS5_DECRYPT or MBEDTLS_PKCS5_ENCRYPT
+ * \param mode       either #MBEDTLS_PKCS5_DECRYPT or #MBEDTLS_PKCS5_ENCRYPT
  * \param pwd        password to use when generating key
  * \param pwdlen     length of password
  * \param data       data to process
@@ -106,7 +106,7 @@
  *                   password are about 1/255).
  *
  * \param pbe_params the ASN.1 algorithm parameters
- * \param mode       either MBEDTLS_PKCS5_DECRYPT or MBEDTLS_PKCS5_ENCRYPT
+ * \param mode       either #MBEDTLS_PKCS5_DECRYPT or #MBEDTLS_PKCS5_ENCRYPT
  * \param pwd        password to use when generating key
  * \param pwdlen     length of password
  * \param data       data to process
@@ -124,7 +124,7 @@
  *                    padding data.
  * \param output_len On success, length of actual data written to the output buffer.
  *
- * \returns        0 on success, or a MBEDTLS_ERR_XXX code if verification fails.
+ * \returns        0 on success, or a MBEDTLS_ERR_XXX code if parsing or decryption fails.
  */
 int mbedtls_pkcs5_pbes2_ext(const mbedtls_asn1_buf *pbe_params, int mode,
                             const unsigned char *pwd,  size_t pwdlen,