diff --git a/include/mbedtls/rsa.h b/include/mbedtls/rsa.h
index 7521058..fb2f77f 100644
--- a/include/mbedtls/rsa.h
+++ b/include/mbedtls/rsa.h
@@ -1,10 +1,15 @@
 /**
  * \file rsa.h
  *
- * \brief The RSA public-key cryptosystem
+ * \brief The RSA public-key cryptosystem.
+ *
+ * For more information, see <em>Public-Key Cryptography Standards (PKCS)
+ * #1 v1.5: RSA Encryption</em> and <em>Public-Key Cryptography Standards
+ * (PKCS) #1 v2.1: RSA Cryptography Specifications</em>.
+ *
  */
 /*
- *  Copyright (C) 2006-2015, 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
@@ -19,7 +24,7 @@
  *  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_RSA_H
 #define MBEDTLS_RSA_H
@@ -43,26 +48,26 @@
 #define MBEDTLS_ERR_RSA_BAD_INPUT_DATA                    -0x4080  /**< Bad input parameters to function. */
 #define MBEDTLS_ERR_RSA_INVALID_PADDING                   -0x4100  /**< Input data contains invalid padding and is rejected. */
 #define MBEDTLS_ERR_RSA_KEY_GEN_FAILED                    -0x4180  /**< Something failed during generation of a key. */
-#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED                  -0x4200  /**< Key failed to pass the library's validity check. */
+#define MBEDTLS_ERR_RSA_KEY_CHECK_FAILED                  -0x4200  /**< Key failed to pass the validity check of the library. */
 #define MBEDTLS_ERR_RSA_PUBLIC_FAILED                     -0x4280  /**< The public key operation failed. */
 #define MBEDTLS_ERR_RSA_PRIVATE_FAILED                    -0x4300  /**< The private key operation failed. */
 #define MBEDTLS_ERR_RSA_VERIFY_FAILED                     -0x4380  /**< The PKCS#1 verification failed. */
 #define MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE                  -0x4400  /**< The output buffer for decryption is not large enough. */
 #define MBEDTLS_ERR_RSA_RNG_FAILED                        -0x4480  /**< The random generator failed to generate non-zeros. */
-#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION             -0x4500  /**< The implementation doesn't offer the requested operation, e.g. because of security violations or lack of functionality */
+#define MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION             -0x4500  /**< The implementation does not offer the requested operation, for example, because of security violations or lack of functionality. */
 #define MBEDTLS_ERR_RSA_HW_ACCEL_FAILED                   -0x4580  /**< RSA hardware accelerator failed. */
 
 /*
  * RSA constants
  */
-#define MBEDTLS_RSA_PUBLIC      0
-#define MBEDTLS_RSA_PRIVATE     1
+#define MBEDTLS_RSA_PUBLIC      0 /**< Request private key operation. */
+#define MBEDTLS_RSA_PRIVATE     1 /**< Request public key operation. */
 
-#define MBEDTLS_RSA_PKCS_V15    0
-#define MBEDTLS_RSA_PKCS_V21    1
+#define MBEDTLS_RSA_PKCS_V15    0 /**< Use PKCS-1 v1.5 encoding. */
+#define MBEDTLS_RSA_PKCS_V21    1 /**< Use PKCS-1 v2.1 encoding. */
 
-#define MBEDTLS_RSA_SIGN        1
-#define MBEDTLS_RSA_CRYPT       2
+#define MBEDTLS_RSA_SIGN        1 /**< Identifier for RSA signature operations. */
+#define MBEDTLS_RSA_CRYPT       2 /**< Identifier for RSA encryption and decryption operations. */
 
 #define MBEDTLS_RSA_SALT_LEN_ANY    -1
 
@@ -80,103 +85,106 @@
 #endif
 
 /**
- * \brief   RSA context structure
+ * \brief   The RSA context structure.
  *
  * \note    Direct manipulation of the members of this structure
- *          is deprecated and will no longer be supported starting
- *          from the next major release. All manipulation should instead
- *          be done through the public interface functions.
- *
+ *          is deprecated. All manipulation should instead be done through
+ *          the public interface functions.
  */
 typedef struct
 {
-    int ver;                    /*!<  always 0          */
-    size_t len;                 /*!<  size(N) in chars  */
+    int ver;                    /*!<  Always 0.*/
+    size_t len;                 /*!<  The size of \p N in Bytes. */
 
-    mbedtls_mpi N;                      /*!<  public modulus    */
-    mbedtls_mpi E;                      /*!<  public exponent   */
+    mbedtls_mpi N;                      /*!<  The public modulus. */
+    mbedtls_mpi E;                      /*!<  The public exponent. */
 
-    mbedtls_mpi D;                      /*!<  private exponent  */
-    mbedtls_mpi P;                      /*!<  1st prime factor  */
-    mbedtls_mpi Q;                      /*!<  2nd prime factor  */
+    mbedtls_mpi D;                      /*!<  The private exponent. */
+    mbedtls_mpi P;                      /*!<  The first prime factor. */
+    mbedtls_mpi Q;                      /*!<  The second prime factor. */
 
-    mbedtls_mpi DP;                     /*!<  D % (P - 1)       */
-    mbedtls_mpi DQ;                     /*!<  D % (Q - 1)       */
+    mbedtls_mpi DP;                     /*!<  \p D % (P - 1)       */
+    mbedtls_mpi DQ;                     /*!<  \p D % (Q - 1)       */
     mbedtls_mpi QP;                     /*!<  1 / (Q % P)       */
 
-    mbedtls_mpi RN;                     /*!<  cached R^2 mod N  */
+    mbedtls_mpi RN;                     /*!<  cached R^2 mod \p N  */
 
-    mbedtls_mpi RP;                     /*!<  cached R^2 mod P  */
-    mbedtls_mpi RQ;                     /*!<  cached R^2 mod Q  */
+    mbedtls_mpi RP;                     /*!<  cached R^2 mod \p P  */
+    mbedtls_mpi RQ;                     /*!<  cached R^2 mod \p Q  */
 
-    mbedtls_mpi Vi;                     /*!<  cached blinding value     */
-    mbedtls_mpi Vf;                     /*!<  cached un-blinding value  */
+    mbedtls_mpi Vi;                     /*!<  The cached blinding value. */
+    mbedtls_mpi Vf;                     /*!<  The cached un-blinding value. */
 
-    int padding;                /*!<  \c MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
-                                      \c MBEDTLS_RSA_PKCS_v21 for OAEP/PSS */
-    int hash_id;                /*!<  Hash identifier of mbedtls_md_type_t as
-                                      specified in the mbedtls_md.h header file
-                                      for the EME-OAEP and EMSA-PSS
-                                      encoding                          */
+    int padding;                /*!< Selects padding mode:
+                                     #MBEDTLS_RSA_PKCS_V15 for 1.5 padding and
+                                     #MBEDTLS_RSA_PKCS_V21 for OAEP or PSS. */
+    int hash_id;                /*!< Hash identifier of mbedtls_md_type_t type,
+                                     as specified in md.h for use in the MGF
+                                     mask generating function used in the
+                                     EME-OAEP and EMSA-PSS encodings. */
 #if defined(MBEDTLS_THREADING_C)
-    mbedtls_threading_mutex_t mutex;    /*!<  Thread-safety mutex       */
+    mbedtls_threading_mutex_t mutex;    /*!<  Thread-safety mutex. */
 #endif
 }
 mbedtls_rsa_context;
 
 /**
- * \brief          Initialize an RSA context
+ * \brief          This function initializes an RSA context.
  *
- *                 Note: Set padding to \c MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
+ * \note           Set padding to #MBEDTLS_RSA_PKCS_V21 for the RSAES-OAEP
  *                 encryption scheme and the RSASSA-PSS signature scheme.
  *
- * \param ctx      RSA context to be initialized
- * \param padding  \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id  \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx      The RSA context to initialize.
+ * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ *                 #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id  The hash identifier of #mbedtls_md_type_t type, if
+ *                 \p padding is #MBEDTLS_RSA_PKCS_V21.
  *
- * \note           The hash_id parameter is actually ignored
- *                 when using \c MBEDTLS_RSA_PKCS_V15 padding.
+ * \note           The \p hash_id parameter is ignored when using
+ *                 #MBEDTLS_RSA_PKCS_V15 padding.
  *
- * \note           Choice of padding mode is strictly enforced for private key
+ * \note           The choice of padding mode is strictly enforced for private key
  *                 operations, since there might be security concerns in
- *                 mixing padding modes. For public key operations it's merely
+ *                 mixing padding modes. For public key operations it is
  *                 a default value, which can be overriden by calling specific
- *                 rsa_rsaes_xxx or rsa_rsassa_xxx functions.
+ *                 \c rsa_rsaes_xxx or \c rsa_rsassa_xxx functions.
  *
- * \note           The chosen hash is always used for OEAP encryption.
- *                 For PSS signatures, it's always used for making signatures,
- *                 but can be overriden (and always is, if set to
- *                 \c MBEDTLS_MD_NONE) for verifying them.
+ * \note           The hash selected in \p hash_id is always used for OEAP
+ *                 encryption. For PSS signatures, it is always used for
+ *                 making signatures, but can be overriden for verifying them.
+ *                 If set to #MBEDTLS_MD_NONE, it is always overriden.
  */
 void mbedtls_rsa_init( mbedtls_rsa_context *ctx,
                        int padding,
                        int hash_id);
 
 /**
- * \brief          Import a set of core parameters into an RSA context
+ * \brief          This function imports a set of core parameters into an
+ *                 RSA context.
  *
- * \param ctx      Initialized RSA context to store parameters
- * \param N        RSA modulus, or NULL
- * \param P        First prime factor of N, or NULL
- * \param Q        Second prime factor of N, or NULL
- * \param D        Private exponent, or NULL
- * \param E        Public exponent, or NULL
+ * \param ctx      The initialized RSA context to store the parameters in.
+ * \param N        The RSA modulus, or NULL.
+ * \param P        The first prime factor of \p N, or NULL.
+ * \param Q        The second prime factor of \p N, or NULL.
+ * \param D        The private exponent, or NULL.
+ * \param E        The public exponent, or NULL.
  *
  * \note           This function can be called multiple times for successive
- *                 imports if the parameters are not simultaneously present.
+ *                 imports, if the parameters are not simultaneously present.
+ *
  *                 Any sequence of calls to this function should be followed
- *                 by a call to \c mbedtls_rsa_complete which will check
- *                 and complete the provided information to a ready-for-use
+ *                 by a call to mbedtls_rsa_complete(), which checks and
+ *                 completes the provided information to a ready-for-use
  *                 public or private RSA key.
  *
- * \note           See the documentation of \c mbedtls_rsa_complete for more
- *                 information on which parameters are necessary to setup
- *                 a private or public RSA key.
+ * \note           See mbedtls_rsa_complete() for more information on which
+ *                 parameters are necessary to set up a private or public
+ *                 RSA key.
  *
  * \note           The imported parameters are copied and need not be preserved
  *                 for the lifetime of the RSA context being set up.
  *
- * \return         0 if successful, non-zero error code on failure.
+ * \return         \c 0 on success, or a non-zero error code on failure.
  */
 int mbedtls_rsa_import( mbedtls_rsa_context *ctx,
                         const mbedtls_mpi *N,
@@ -184,36 +192,37 @@
                         const mbedtls_mpi *D, const mbedtls_mpi *E );
 
 /**
- * \brief          Import core RSA parameters in raw big-endian
- *                 binary format into an RSA context
+ * \brief          This function imports core RSA parameters, in raw big-endian
+ *                 binary format, into an RSA context.
  *
- * \param ctx      Initialized RSA context to store parameters
- * \param N        RSA modulus, or NULL
- * \param N_len    Byte length of N, ignored if N == NULL
- * \param P        First prime factor of N, or NULL
- * \param P_len    Byte length of P, ignored if P == NULL
- * \param Q        Second prime factor of N, or NULL
- * \param Q_len    Byte length of Q, ignored if Q == NULL
- * \param D        Private exponent, or NULL
- * \param D_len    Byte length of D, ignored if D == NULL
- * \param E        Public exponent, or NULL
- * \param E_len    Byte length of E, ignored if E == NULL
+ * \param ctx      The initialized RSA context to store the parameters in.
+ * \param N        The RSA modulus, or NULL.
+ * \param N_len    The Byte length of \p N, ignored if \p N == NULL.
+ * \param P        The first prime factor of \p N, or NULL.
+ * \param P_len    The Byte length of \p P, ignored if \p P == NULL.
+ * \param Q        The second prime factor of \p N, or NULL.
+ * \param Q_len    The Byte length of \p Q, ignored if \p Q == NULL.
+ * \param D        The private exponent, or NULL.
+ * \param D_len    The Byte length of \p D, ignored if \p D == NULL.
+ * \param E        The public exponent, or NULL.
+ * \param E_len    The Byte length of \p E, ignored if \p E == NULL.
  *
  * \note           This function can be called multiple times for successive
- *                 imports if the parameters are not simultaneously present.
+ *                 imports, if the parameters are not simultaneously present.
+ *
  *                 Any sequence of calls to this function should be followed
- *                 by a call to \c mbedtls_rsa_complete which will check
- *                 and complete the provided information to a ready-for-use
+ *                 by a call to mbedtls_rsa_complete(), which checks and
+ *                 completes the provided information to a ready-for-use
  *                 public or private RSA key.
  *
- * \note           See the documentation of \c mbedtls_rsa_complete for more
- *                 information on which parameters are necessary to setup
- *                 a private or public RSA key.
+ * \note           See mbedtls_rsa_complete() for more information on which
+ *                 parameters are necessary to set up a private or public
+ *                 RSA key.
  *
  * \note           The imported parameters are copied and need not be preserved
  *                 for the lifetime of the RSA context being set up.
  *
- * \return         0 if successful, non-zero error code on failure.
+ * \return         \c 0 on success, or a non-zero error code on failure.
  */
 int mbedtls_rsa_import_raw( mbedtls_rsa_context *ctx,
                             unsigned char const *N, size_t N_len,
@@ -223,71 +232,71 @@
                             unsigned char const *E, size_t E_len );
 
 /**
- * \brief          Attempt to complete an RSA context from
+ * \brief          This function completes an RSA context from
  *                 a set of imported core parameters.
  *
- * \param ctx      Initialized RSA context to store parameters
+ *                 To setup an RSA public key, precisely \p N and \p E
+ *                 must have been imported.
  *
- * \note
- *                 - To setup an RSA public key, precisely N and E
- *                   must have been imported.
+ *                 To setup an RSA private key, sufficient information must
+ *                 be present for the other parameters to be derivable.
  *
- *                 - To setup an RSA private key, enough information must be
- *                   present for the other parameters to be derivable.
+ *                 The default implementation supports the following:
+ *                 <ul><li>Derive \p P, \p Q from \p N, \p D, \p E.</li>
+ *                 <li>Derive \p N, \p D from \p P, \p Q, \p E.</li></ul>
+ *                 Alternative implementations need not support these.
  *
- *                   The default implementation supports the following:
- *                     - Derive P, Q from N, D, E
- *                     - Derive N, D from P, Q, E.
+ *                 If this function runs successfully, it guarantees that
+ *                 the RSA context can be used for RSA operations without
+ *                 the risk of failure or crash.
  *
- *                 - Alternative implementations need not support these
- *                   and may return \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA instead.
+ * \param ctx      The initialized RSA context holding imported parameters.
  *
- * \return
- *                 - 0 if successful. In this case, it is guaranteed
- *                   that the RSA context can be used for RSA operations
- *                   without the risk of failure or crash.
- *                 - \c MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the attempted
- *                   derivations failed.
+ * \return         \c 0 on success, or #MBEDTLS_ERR_RSA_BAD_INPUT_DATA if the
+ *                 attempted derivations failed.
  *
  * \warning        This function need not perform consistency checks
- *                 for the imported parameters! In particular, parameters that
- *                 are not needed by the implementation may be silently discarded
- *                 and left unchecked. For the purpose of checking the consistency
- *                 of the key material, see \c mbedtls_rsa_check_privkey.
+ *                 for the imported parameters. In particular, parameters that
+ *                 are not needed by the implementation might be silently
+ *                 discarded and left unchecked. To check the consistency
+ *                 of the key material, see mbedtls_rsa_check_privkey().
  *
  */
 int mbedtls_rsa_complete( mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Export core parameters of an RSA key
+ * \brief          This function exports the core parameters of an RSA key.
  *
- * \param ctx      Initialized RSA context
- * \param N        MPI to hold the RSA modulus, or NULL
- * \param P        MPI to hold the first prime factor of N, or NULL
- * \param Q        MPI to hold the second prime factor of N, or NULL
- * \param D        MPI to hold the private exponent, or NULL
- * \param E        MPI to hold the public exponent, or NULL
+ *                 If this function runs successfully, the non-NULL buffers
+ *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ *                 written, with additional unused space filled leading by
+ *                 zero Bytes.
  *
- * \return
- *                 - 0 if successful. In this case, the non-NULL buffers
- *                   pointed to by N, P, Q, D, E are fully written, with
- *                   additional unused space filled leading by 0-bytes.
- *                 - Non-zero return code otherwise. In particular, if
- *                   exporting the requested parameters
- *                   cannot be done because of a lack of functionality
- *                   or because of security policies, the error code
- *                   \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- *                   In this case, the RSA context stays intact and can
- *                   be continued to be used.
+ *                 Possible reasons for returning
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ *                 <li>An alternative RSA implementation is in use, which
+ *                 stores the key externally, and either cannot or should
+ *                 not export it into RAM.</li>
+ *                 <li>A SW or HW implementation might not support a certain
+ *                 deduction. For example, \p P, \p Q from \p N, \p D,
+ *                 and \p E if the former are not part of the
+ *                 implementation.</li></ul>
  *
- * \note           Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- *                 would be the following: Firstly, it might be that an
- *                 alternative RSA implementation is in use which stores
- *                 the key externally, and which either cannot or should not
- *                 export it into RAM. Alternatively, an implementation
- *                 (regardless of SW or HW) might not support deducing e.g.
- *                 P, Q from N, D, E if the former are not part of the
- *                 implementation.
+ *                 If the function fails due to an unsupported operation,
+ *                 the RSA context stays intact and remains usable.
+ *
+ * \param ctx      The initialized RSA context.
+ * \param N        The MPI to hold the RSA modulus, or NULL.
+ * \param P        The MPI to hold the first prime factor of \p N, or NULL.
+ * \param Q        The MPI to hold the second prime factor of \p N, or NULL.
+ * \param D        The MPI to hold the private exponent, or NULL.
+ * \param E        The MPI to hold the public exponent, or NULL.
+ *
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ *                 requested parameters cannot be done due to missing
+ *                 functionality or because of security policies,
+ *                 or a non-zero return code on any other failure.
  *
  */
 int mbedtls_rsa_export( const mbedtls_rsa_context *ctx,
@@ -295,46 +304,48 @@
                         mbedtls_mpi *D, mbedtls_mpi *E );
 
 /**
- * \brief          Export core parameters of an RSA key
- *                 in raw big-endian binary format
+ * \brief          This function exports core parameters of an RSA key
+ *                 in raw big-endian binary format.
  *
- * \param ctx      Initialized RSA context
- * \param N        Byte array to store the RSA modulus, or NULL
- * \param N_len    Size of buffer for modulus
- * \param P        Byte array to hold the first prime factor of N, or NULL
- * \param P_len    Size of buffer for first prime factor
- * \param Q        Byte array to hold the second prime factor of N, or NULL
- * \param Q_len    Size of buffer for second prime factor
- * \param D        Byte array to hold the private exponent, or NULL
- * \param D_len    Size of buffer for private exponent
- * \param E        Byte array to hold the public exponent, or NULL
- * \param E_len    Size of buffer for public exponent
+ *                 If this function runs successfully, the non-NULL buffers
+ *                 pointed to by \p N, \p P, \p Q, \p D, and \p E are fully
+ *                 written, with additional unused space filled leading by
+ *                 zero Bytes.
+ *
+ *                 Possible reasons for returning
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION:<ul>
+ *                 <li>An alternative RSA implementation is in use, which
+ *                 stores the key externally, and either cannot or should
+ *                 not export it into RAM.</li>
+ *                 <li>A SW or HW implementation might not support a certain
+ *                 deduction. For example, \p P, \p Q from \p N, \p D,
+ *                 and \p E if the former are not part of the
+ *                 implementation.</li></ul>
+ *                 If the function fails due to an unsupported operation,
+ *                 the RSA context stays intact and remains usable.
+ *
+ * \param ctx      The initialized RSA context.
+ * \param N        The Byte array to store the RSA modulus, or NULL.
+ * \param N_len    The size of the buffer for the modulus.
+ * \param P        The Byte array to hold the first prime factor of \p N, or
+ *                 NULL.
+ * \param P_len    The size of the buffer for the first prime factor.
+ * \param Q        The Byte array to hold the second prime factor of \p N, or
+                   NULL.
+ * \param Q_len    The size of the buffer for the second prime factor.
+ * \param D        The Byte array to hold the private exponent, or NULL.
+ * \param D_len    The size of the buffer for the private exponent.
+ * \param E        The Byte array to hold the public exponent, or NULL.
+ * \param E_len    The size of the buffer for the public exponent.
  *
  * \note           The length fields are ignored if the corresponding
  *                 buffer pointers are NULL.
  *
- * \return
- *                 - 0 if successful. In this case, the non-NULL buffers
- *                   pointed to by N, P, Q, D, E are fully written, with
- *                   additional unused space filled leading by 0-bytes.
- *                 - Non-zero return code otherwise. In particular, if
- *                   exporting the requested parameters
- *                   cannot be done because of a lack of functionality
- *                   or because of security policies, the error code
- *                   \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION is returned.
- *                   In this case, the RSA context stays intact and can
- *                   be continued to be used.
- *
- * \note           Reasons for returning \c MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION
- *                 would be the following: Firstly, it might be that an
- *                 alternative RSA implementation is in use which stores
- *                 the key externally, and which either cannot or should not
- *                 export it into RAM. Alternatively, an implementation
- *                 (regardless of SW or HW) might not support deducing e.g.
- *                 P, Q from N, D, E if the former are not part of the
- *                 implementation.
- *
- *
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION if exporting the
+ *                 requested parameters cannot be done due to missing
+ *                 functionality or because of security policies,
+ *                 or a non-zero return code on any other failure.
  */
 int mbedtls_rsa_export_raw( const mbedtls_rsa_context *ctx,
                             unsigned char *N, size_t N_len,
@@ -344,57 +355,59 @@
                             unsigned char *E, size_t E_len );
 
 /**
- * \brief          Export CRT parameters of a private RSA key
+ * \brief          This function exports CRT parameters of a private RSA key.
  *
- * \param ctx      Initialized RSA context
- * \param DP       MPI to hold D modulo P-1, or NULL
- * \param DQ       MPI to hold D modulo Q-1, or NULL
- * \param QP       MPI to hold modular inverse of Q modulo P, or NULL
+ * \param ctx      The initialized RSA context.
+ * \param DP       The MPI to hold D modulo P-1, or NULL.
+ * \param DQ       The MPI to hold D modulo Q-1, or NULL.
+ * \param QP       The MPI to hold modular inverse of Q modulo P, or NULL.
  *
- * \return         0 if successful, non-zero error code otherwise.
+ * \return         \c 0 on success, non-zero error code otherwise.
  *
  * \note           Alternative RSA implementations not using CRT-parameters
- *                 internally can implement this function using based on
- *                 \c mbedtls_rsa_deduce_opt.
+ *                 internally can implement this function based on
+ *                 mbedtls_rsa_deduce_opt().
  *
  */
 int mbedtls_rsa_export_crt( const mbedtls_rsa_context *ctx,
                             mbedtls_mpi *DP, mbedtls_mpi *DQ, mbedtls_mpi *QP );
 
 /**
- * \brief          Set padding for an already initialized RSA context
- *                 See \c mbedtls_rsa_init() for details.
+ * \brief          This function sets padding for an already initialized RSA
+ *                 context. See mbedtls_rsa_init() for details.
  *
- * \param ctx      RSA context to be set
- * \param padding  \c MBEDTLS_RSA_PKCS_V15 or \c MBEDTLS_RSA_PKCS_V21
- * \param hash_id  \c MBEDTLS_RSA_PKCS_V21 hash identifier
+ * \param ctx      The RSA context to be set.
+ * \param padding  Selects padding mode: #MBEDTLS_RSA_PKCS_V15 or
+ *                 #MBEDTLS_RSA_PKCS_V21.
+ * \param hash_id  The #MBEDTLS_RSA_PKCS_V21 hash identifier.
  */
 void mbedtls_rsa_set_padding( mbedtls_rsa_context *ctx, int padding,
                               int hash_id);
 
 /**
- * \brief          Get length of RSA modulus in bytes
+ * \brief          This function retrieves the length of RSA modulus in Bytes.
  *
- * \param ctx      Initialized RSA context
+ * \param ctx      The initialized RSA context.
  *
- * \return         Length of RSA modulus, in bytes.
+ * \return         The length of the RSA modulus in Bytes.
  *
  */
 size_t mbedtls_rsa_get_len( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Generate an RSA keypair
+ * \brief          This function generates an RSA keypair.
  *
- * \param ctx      RSA context that will hold the key
- * \param f_rng    RNG function
- * \param p_rng    RNG parameter
- * \param nbits    size of the public key in bits
- * \param exponent public exponent (e.g., 65537)
+ * \param ctx      The RSA context used to hold the key.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG parameter.
+ * \param nbits    The size of the public key in bits.
+ * \param exponent The public exponent. For example, 65537.
  *
- * \note           mbedtls_rsa_init() must be called beforehand to setup
- *                 the RSA context.
+ * \note           mbedtls_rsa_init() must be called before this function,
+ *                 to set up the RSA context.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+                   on failure.
  */
 int mbedtls_rsa_gen_key( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -402,101 +415,109 @@
                          unsigned int nbits, int exponent );
 
 /**
- * \brief          Check if a context contains (at least) an RSA public key
+ * \brief          This function checks if a context contains at least an RSA
+ *                 public key.
  *
- * \param ctx      RSA context to be checked
+ *                 If the function runs successfully, it is guaranteed that
+ *                 enough information is present to perform an RSA public key
+ *                 operation using mbedtls_rsa_public().
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
- *                 On success, it is guaranteed that enough information is
- *                 present to perform an RSA public key operation
- *                 \c mbedtls_rsa_public.
+ * \param ctx      The RSA context to check.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  */
 int mbedtls_rsa_check_pubkey( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief      Check if a context contains an RSA private key
+ * \brief      This function checks if a context contains an RSA private key
  *             and perform basic consistency checks.
  *
- * \param ctx  RSA context to be checked
+ * \param ctx  The RSA context to check.
  *
- * \return     0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code.
+ * \return     \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code on
+ *             failure.
  *
  * \note       The consistency checks performed by this function not only
- *             ensure that \c mbedtls_rsa_private can be called successfully
+ *             ensure that mbedtls_rsa_private() can be called successfully
  *             on the given context, but that the various parameters are
  *             mutually consistent with high probability, in the sense that
- *             \c mbedtls_rsa_public and \c mbedtls_rsa_private are inverses.
+ *             mbedtls_rsa_public() and mbedtls_rsa_private() are inverses.
  *
  * \warning    This function should catch accidental misconfigurations
  *             like swapping of parameters, but it cannot establish full
  *             trust in neither the quality nor the consistency of the key
  *             material that was used to setup the given RSA context:
- *             - Regarding consistency, note (see \c mbedtls_rsa_complete)
- *               that imported parameters irrelevant for the implementation
- *               might be silently dropped, in which case the present
- *               function doesn't have access to and hence cannot check them.
- *               If you want to check the consistency of the entire
- *               content of, say, an PKCS1-encoded RSA private key, you
- *               should use \c mbedtls_rsa_validate_params before setting
- *               up the RSA context.
- *               Further, if the implementation performs empirical checks,
- *               these checks will substantiate but not guarantee consistency.
- *             - Regarding quality, this function is not expected to perform
- *               extended quality assessments like checking that the prime
- *               factors are safe. Further, it is the user's responsibility to
- *               ensure trustworthiness of the source of his RSA parameters,
- *               a question going beyond what's effectively checkable
- *               by the library.
- *
+ *             <ul><li>Consistency: Imported parameters that are irrelevant
+ *             for the implementation might be silently dropped. If dropped,
+ *             the current function does not have access to them,
+ *             and therefore cannot check them. See mbedtls_rsa_complete().
+ *             If you want to check the consistency of the entire
+ *             content of an PKCS1-encoded RSA private key, for example, you
+ *             should use mbedtls_rsa_validate_params() before setting
+ *             up the RSA context.
+ *             Additionally, if the implementation performs empirical checks,
+ *             these checks substantiate but do not guarantee consistency.</li>
+ *             <li>Quality: This function is not expected to perform
+ *             extended quality assessments like checking that the prime
+ *             factors are safe. Additionally, it is the responsibility of the
+ *             user to ensure the trustworthiness of the source of his RSA
+ *             parameters, which goes beyond what is effectively checkable
+ *             by the library.</li></ul>
  */
 int mbedtls_rsa_check_privkey( const mbedtls_rsa_context *ctx );
 
 /**
- * \brief          Check a public-private RSA key pair.
- *                 Check each of the contexts, and make sure they match.
+ * \brief          This function checks a public-private RSA key pair.
  *
- * \param pub      RSA context holding the public key
- * \param prv      RSA context holding the private key
+ *                 It checks each of the contexts, and makes sure they match.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \param pub      The RSA context holding the public key.
+ * \param prv      The RSA context holding the private key.
+ *
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  */
 int mbedtls_rsa_check_pub_priv( const mbedtls_rsa_context *pub,
                                 const mbedtls_rsa_context *prv );
 
 /**
- * \brief          Do an RSA public key operation
+ * \brief          This function performs an RSA public key operation.
  *
- * \param ctx      RSA context
- * \param input    input buffer
- * \param output   output buffer
+ * \param ctx      The RSA context.
+ * \param input    The input buffer.
+ * \param output   The output buffer.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           This function does NOT take care of message
- *                 padding. Also, be sure to set input[0] = 0 or ensure that
- *                 input is smaller than N.
+ * \note           This function does not handle message padding.
+ *
+ * \note           Make sure to set \p input[0] = 0 or ensure that
+ *                 input is smaller than \p N.
  *
  * \note           The input and output buffers must be large
- *                 enough (eg. 128 bytes if RSA-1024 is used).
+ *                 enough. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_public( mbedtls_rsa_context *ctx,
                 const unsigned char *input,
                 unsigned char *output );
 
 /**
- * \brief          Do an RSA private key operation
+ * \brief          This function performs an RSA private key operation.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for blinding)
- * \param p_rng    RNG parameter
- * \param input    input buffer
- * \param output   output buffer
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for blinding.
+ * \param p_rng    The RNG parameter.
+ * \param input    The input buffer.
+ * \param output   The output buffer.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The input and output buffers must be large
- *                 enough (eg. 128 bytes if RSA-1024 is used).
+ *                 enough. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_private( mbedtls_rsa_context *ctx,
                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -505,32 +526,36 @@
                  unsigned char *output );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 encryption using the
- *                 mode from the context. Add the message padding, then do an
- *                 RSA operation.
+ * \brief          This function adds the message padding, then performs an RSA
+ *                 operation.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and PKCS#1 v2.1 encoding
- *                               and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ *                 It is the generic wrapper for performing a PKCS#1 encryption
+ *                 operation using the \p mode from the context.
+ *
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding, PKCS#1 v2.1
+ *                 encoding, and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The input and output buffers must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_pkcs1_encrypt( mbedtls_rsa_context *ctx,
                        int (*f_rng)(void *, unsigned char *, size_t),
@@ -540,29 +565,32 @@
                        unsigned char *output );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 encryption (RSAES-PKCS1-v1_5-ENCRYPT)
+ * \brief          This function performs a PKCS#1 v1.5 encryption operation
+ *                 (RSAES-PKCS1-v1_5-ENCRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for padding and
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param ilen     The length of the plaintext.
+ * \param input    The buffer holding the data to encrypt.
+ * \param output   The buffer used to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_encrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -572,32 +600,34 @@
                                  unsigned char *output );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 OAEP encryption (RSAES-OAEP-ENCRYPT)
+ * \brief            This function performs a PKCS#1 v2.1 OAEP encryption
+ *                   operation (RSAES-OAEP-ENCRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for padding and PKCS#1 v2.1 encoding
- *                               and \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label    buffer holding the custom label to use
- * \param label_len contains the label length
- * \param ilen     contains the plaintext length
- * \param input    buffer holding the data to be encrypted
- * \param output   buffer that will hold the ciphertext
+ * \param ctx        The RSA context.
+ * \param f_rng      The RNG function. Needed for padding and PKCS#1 v2.1
+ *                   encoding and #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng      The RNG parameter.
+ * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param label      The buffer holding the custom label to use.
+ * \param label_len  The length of the label.
+ * \param ilen       The length of the plaintext.
+ * \param input      The buffer holding the data to encrypt.
+ * \param output     The buffer used to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer must be as large as the size
- *                 of ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_oaep_encrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -609,39 +639,42 @@
                             unsigned char *output );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 decryption using the
- *                 mode from the context. Do an RSA operation, then remove
- *                 the message padding
+ * \brief          This function performs an RSA operation, then removes the
+ *                 message padding.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ *                 It is the generic wrapper for performing a PKCS#1 decryption
+ *                 operation using the \p mode from the context.
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer used to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N (for example,
+ *                 128 Bytes if RSA-1024 is used) to be able to hold an
+ *                 arbitrary decrypted message. If it is not large enough to
+ *                 hold the decryption of the particular ciphertext provided,
+ *                 the function returns \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_pkcs1_decrypt( mbedtls_rsa_context *ctx,
                        int (*f_rng)(void *, unsigned char *, size_t),
@@ -652,37 +685,39 @@
                        size_t output_max_len );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 decryption (RSAES-PKCS1-v1_5-DECRYPT)
+ * \brief          This function performs a PKCS#1 v1.5 decryption
+ *                 operation (RSAES-PKCS1-v1_5-DECRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param olen     The length of the plaintext.
+ * \param input    The buffer holding the encrypted data.
+ * \param output   The buffer to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N, for example,
+ *                 128 Bytes if RSA-1024 is used, to be able to hold an
+ *                 arbitrary decrypted message. If it is not large enough to
+ *                 hold the decryption of the particular ciphertext provided,
+ *                 the function returns #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_pkcs1_v15_decrypt( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -693,40 +728,42 @@
                                  size_t output_max_len );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 OAEP decryption (RSAES-OAEP-DECRYPT)
+ * \brief          This function performs a PKCS#1 v2.1 OAEP decryption
+ *                 operation (RSAES-OAEP-DECRYPT).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param label    buffer holding the custom label to use
- * \param label_len contains the label length
- * \param olen     will contain the plaintext length
- * \param input    buffer holding the encrypted data
- * \param output   buffer that will hold the plaintext
- * \param output_max_len    maximum length of the output buffer
+ * \param ctx        The RSA context.
+ * \param f_rng      The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng      The RNG parameter.
+ * \param mode       #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param label      The buffer holding the custom label to use.
+ * \param label_len  The length of the label.
+ * \param olen       The length of the plaintext.
+ * \param input      The buffer holding the encrypted data.
+ * \param output     The buffer to hold the plaintext.
+ * \param output_max_len    The maximum length of the output buffer.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if successful, or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 on success, or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
  * \note           The output buffer length \c output_max_len should be
- *                 as large as the size \c ctx->len of \c ctx->N (eg. 128 bytes
- *                 if RSA-1024 is used) to be able to hold an arbitrary
- *                 decrypted message. If it is not large enough to hold
- *                 the decryption of the particular ciphertext provided,
- *                 the function will return \c MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
+ *                 as large as the size \p ctx->len of \p ctx->N, for
+ *                 example, 128 Bytes if RSA-1024 is used, to be able to
+ *                 hold an arbitrary decrypted message. If it is not
+ *                 large enough to hold the decryption of the particular
+ *                 ciphertext provided, the function returns
+ *                 #MBEDTLS_ERR_RSA_OUTPUT_TOO_LARGE.
  *
  * \note           The input buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
- *
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsaes_oaep_decrypt( mbedtls_rsa_context *ctx,
                             int (*f_rng)(void *, unsigned char *, size_t),
@@ -739,39 +776,41 @@
                             size_t output_max_len );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 signature using the
- *                 mode from the context. Do a private RSA operation to sign
- *                 a message digest
+ * \brief          This function performs a private RSA operation to sign
+ *                 a message digest using PKCS#1.
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for PKCS#1 v2.1 encoding and for
- *                               \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for
- *                 signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ *                 It is the generic wrapper for performing a PKCS#1
+ *                 signature using the \p mode from the context.
+ *
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
- *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ * \return         \c 0 if the signing operation was successful,
+ *                 or an \c MBEDTLS_ERR_RSA_XXX error code on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \note           In case of PKCS#1 v2.1 encoding, see comments on
- *                 \c mbedtls_rsa_rsassa_pss_sign() for details on
- *                 \c md_alg and \c hash_id.
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_sign() for details on
+ *                 \p md_alg and \p hash_id.
  */
 int mbedtls_rsa_pkcs1_sign( mbedtls_rsa_context *ctx,
                     int (*f_rng)(void *, unsigned char *, size_t),
@@ -783,32 +822,34 @@
                     unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 signature (RSASSA-PKCS1-v1_5-SIGN)
+ * \brief          This function performs a PKCS#1 v1.5 signature
+ *                 operation (RSASSA-PKCS1-v1_5-SIGN).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
+ * \return         \c 0 if the signing operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_sign( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -820,38 +861,42 @@
                                unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS signature (RSASSA-PSS-SIGN)
+ * \brief          This function performs a PKCS#1 v2.1 PSS signature
+ *                 operation (RSASSA-PSS-SIGN).
  *
- * \param ctx      RSA context
- * \param f_rng    RNG function (Needed for PKCS#1 v2.1 encoding and for
- *                               \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer that will hold the ciphertext
+ * \param ctx      The RSA context.
+ * \param f_rng    The RNG function. Needed for PKCS#1 v2.1 encoding and for
+ *                 #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer to hold the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PUBLIC. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PRIVATE.
+ *                 in #MBEDTLS_RSA_PUBLIC mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PRIVATE.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PUBLIC and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PUBLIC and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the signing operation was successful,
+ * \return         \c 0 if the signing operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \note           The \c hash_id in the RSA context is the one used for the
- *                 encoding. \c md_alg in the function call is the type of hash
- *                 that is encoded. According to RFC 3447 it is advised to
- *                 keep both hashes the same.
+ * \note           The \p hash_id in the RSA context is the one used for the
+ *                 encoding. \p md_alg in the function call is the type of hash
+ *                 that is encoded. According to <em>RFC-3447: Public-Key
+ *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ *                 Specifications</em> it is advised to keep both hashes the
+ *                 same.
  */
 int mbedtls_rsa_rsassa_pss_sign( mbedtls_rsa_context *ctx,
                          int (*f_rng)(void *, unsigned char *, size_t),
@@ -863,36 +908,41 @@
                          unsigned char *sig );
 
 /**
- * \brief          Generic wrapper to perform a PKCS#1 verification using the
- *                 mode from the context. Do a public RSA operation and check
- *                 the message digest
+ * \brief          This function performs a public RSA operation and checks
+ *                 the message digest.
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ *                 This is the generic wrapper for performing a PKCS#1
+ *                 verification using the mode from the context.
+ *
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \note           In case of PKCS#1 v2.1 encoding, see comments on
- *                 \c mbedtls_rsa_rsassa_pss_verify() about md_alg and hash_id.
+ * \note           For PKCS#1 v2.1 encoding, see comments on
+ *                 mbedtls_rsa_rsassa_pss_verify() about \p md_alg and
+ *                 \p hash_id.
  */
 int mbedtls_rsa_pkcs1_verify( mbedtls_rsa_context *ctx,
                       int (*f_rng)(void *, unsigned char *, size_t),
@@ -904,32 +954,34 @@
                       const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v1.5 verification (RSASSA-PKCS1-v1_5-VERIFY)
+ * \brief          This function performs a PKCS#1 v1.5 verification
+ *                 operation (RSASSA-PKCS1-v1_5-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE
- *                 for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  */
 int mbedtls_rsa_rsassa_pkcs1_v15_verify( mbedtls_rsa_context *ctx,
                                  int (*f_rng)(void *, unsigned char *, size_t),
@@ -941,38 +993,45 @@
                                  const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- *                 (This is the "simple" version.)
+ * \brief          This function performs a PKCS#1 v2.1 PSS verification
+ *                 operation (RSASSA-PSS-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param sig      buffer holding the ciphertext
+ *                 The hash function for the MGF mask generating function
+ *                 is that specified in the RSA context.
+ *
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param sig      The buffer holding the ciphertext.
  *
  * \deprecated     It is deprecated and discouraged to call this function
- *                 in mode MBEDTLS_RSA_PRIVATE. Future versions of the libary
- *                 are likely to remove the mode argument and have it implicitly
- *                 set to MBEDTLS_RSA_PUBLIC.
+ *                 in #MBEDTLS_RSA_PRIVATE mode. Future versions of the library
+ *                 are likely to remove the \p mode argument and have it
+ *                 implicitly set to #MBEDTLS_RSA_PUBLIC.
  *
  * \note           Alternative implementations of RSA need not support
- *                 mode being set to MBEDTLS_RSA_PRIVATE and may instead
- *                 return MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
+ *                 mode being set to #MBEDTLS_RSA_PRIVATE and might instead
+ *                 return #MBEDTLS_ERR_RSA_UNSUPPORTED_OPERATION.
  *
- * \return         0 if the verify operation was successful,
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \note           The \c hash_id in the RSA context is the one used for the
- *                 verification. \c md_alg in the function call is the type of
- *                 hash that is verified. According to RFC 3447 it is advised to
- *                 keep both hashes the same. If \c hash_id in the RSA context is
- *                 unset, the \c md_alg from the function call is used.
+ * \note           The \p hash_id in the RSA context is the one used for the
+ *                 verification. \p md_alg in the function call is the type of
+ *                 hash that is verified. According to <em>RFC-3447: Public-Key
+ *                 Cryptography Standards (PKCS) #1 v2.1: RSA Cryptography
+ *                 Specifications</em> it is advised to keep both hashes the
+ *                 same. If \p hash_id in the RSA context is unset,
+ *                 the \p md_alg from the function call is used.
  */
 int mbedtls_rsa_rsassa_pss_verify( mbedtls_rsa_context *ctx,
                            int (*f_rng)(void *, unsigned char *, size_t),
@@ -984,28 +1043,33 @@
                            const unsigned char *sig );
 
 /**
- * \brief          Perform a PKCS#1 v2.1 PSS verification (RSASSA-PSS-VERIFY)
- *                 (This is the version with "full" options.)
+ * \brief          This function performs a PKCS#1 v2.1 PSS verification
+ *                 operation (RSASSA-PSS-VERIFY).
  *
- * \param ctx      points to an RSA public key
- * \param f_rng    RNG function (Only needed for \c MBEDTLS_RSA_PRIVATE)
- * \param p_rng    RNG parameter
- * \param mode     \c MBEDTLS_RSA_PUBLIC or \c MBEDTLS_RSA_PRIVATE
- * \param md_alg   a \c MBEDTLS_MD_XXX (use \c MBEDTLS_MD_NONE for signing raw data)
- * \param hashlen  message digest length (for \c MBEDTLS_MD_NONE only)
- * \param hash     buffer holding the message digest
- * \param mgf1_hash_id message digest used for mask generation
- * \param expected_salt_len Length of the salt used in padding, use
- *                 \c MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length
- * \param sig      buffer holding the ciphertext
+ *                 The hash function for the MGF mask generating function
+ *                 is that specified in \p mgf1_hash_id.
  *
- * \return         0 if the verify operation was successful,
+ * \param ctx      The RSA public key context.
+ * \param f_rng    The RNG function. Only needed for #MBEDTLS_RSA_PRIVATE.
+ * \param p_rng    The RNG parameter.
+ * \param mode     #MBEDTLS_RSA_PUBLIC or #MBEDTLS_RSA_PRIVATE.
+ * \param md_alg   The message-digest algorithm used to hash the original data.
+ *                 Use #MBEDTLS_MD_NONE for signing raw data.
+ * \param hashlen  The length of the message digest. Only used if \p md_alg is #MBEDTLS_MD_NONE.
+ * \param hash     The buffer holding the message digest.
+ * \param mgf1_hash_id The message digest used for mask generation.
+ * \param expected_salt_len The length of the salt used in padding. Use
+ *                 #MBEDTLS_RSA_SALT_LEN_ANY to accept any salt length.
+ * \param sig      The buffer holding the ciphertext.
+ *
+ * \return         \c 0 if the verify operation was successful,
  *                 or an \c MBEDTLS_ERR_RSA_XXX error code
+ *                 on failure.
  *
- * \note           The \c sig buffer must be as large as the size
- *                 of \c ctx->N (eg. 128 bytes if RSA-1024 is used).
+ * \note           The \p sig buffer must be as large as the size
+ *                 of \p ctx->N. For example, 128 Bytes if RSA-1024 is used.
  *
- * \note           The \c hash_id in the RSA context is ignored.
+ * \note           The \p hash_id in the RSA context is ignored.
  */
 int mbedtls_rsa_rsassa_pss_verify_ext( mbedtls_rsa_context *ctx,
                                int (*f_rng)(void *, unsigned char *, size_t),
@@ -1019,20 +1083,20 @@
                                const unsigned char *sig );
 
 /**
- * \brief          Copy the components of an RSA context
+ * \brief          This function copies the components of an RSA context.
  *
- * \param dst      Destination context
- * \param src      Source context
+ * \param dst      The destination context.
+ * \param src      The source context.
  *
- * \return         0 on success,
- *                 \c MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure
+ * \return         \c 0 on success,
+ *                 #MBEDTLS_ERR_MPI_ALLOC_FAILED on memory allocation failure.
  */
 int mbedtls_rsa_copy( mbedtls_rsa_context *dst, const mbedtls_rsa_context *src );
 
 /**
- * \brief          Free the components of an RSA key
+ * \brief          This function frees the components of an RSA key.
  *
- * \param ctx      RSA Context to free
+ * \param ctx      The RSA Context to free.
  */
 void mbedtls_rsa_free( mbedtls_rsa_context *ctx );
 
@@ -1049,9 +1113,9 @@
 #endif
 
 /**
- * \brief          Checkup routine
+ * \brief          The RSA checkup routine.
  *
- * \return         0 if successful, or 1 if the test failed
+ * \return         \c 0 on success, or \c 1 on failure.
  */
 int mbedtls_rsa_self_test( int verbose );