diff --git a/ChangeLog b/ChangeLog
index 9ec9d4d..e7a2f4d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -3,12 +3,16 @@
 = mbed TLS x.x.x branch released xxxx-xx-xx
 
 Features
-   * Add support for restartable ECC operations, enabled by
-     MBEDTLS_ECP_RESTARTABLE (disabled by default) at compile time and
-     mbedtls_ecp_set_max_ops() at runtime, using new xxx_restartable functions
-     in ECP, ECDSA, PK and X509 (CRL not supported yet), and using existing
-     functions in ECDH and SSL (currently only implemented client-side, for
-     ECDHE-ECDSA ciphersuites with TLS 1.2, including client authentication).
+   * Add support for temporarily suspending expensive ECC computations after
+     some configurable amount of operations, to be used in single-threaded
+     constrained systems where ECC is time consuming and blocking until
+     completion cannot be tolerated. This is enabled by
+     MBEDTLS_ECP_RESTARTABLE at compile time (disabled by default) and
+     configured by mbedtls_ecp_set_max_ops() at runtime. It applies to new
+     xxx_restartable functions in ECP, ECDSA, PK and X.509 (CRL not supported
+     yet), and to existing functions in ECDH and SSL (currently only
+     implemented client-side, for ECDHE-ECDSA ciphersuites in TLS 1.2,
+     including client authentication).
 
 Bugfix
    * Fix a bug in the update function for SSL ticket keys which previously
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 3f248d5..92f024a 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -682,14 +682,16 @@
  *
  * Enable "non-blocking" ECC operations that can return early and be resumed.
  *
- * This enables \c mbedtls_ecp_set_max_ops() and allows various functions
- * to return #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL
- * module, #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) when needed, and then be
- * called again later with the same arguments in order to further progress and
- * eventually complete the operation, see \c mbedtls_ecp_set_max_ops().
+ * This allows various functions to pause by returning
+ * #MBEDTLS_ERR_ECP_IN_PROGRESS (or, for functions in the SSL module,
+ * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS) and then be called later again in
+ * order to further progress and eventually complete their operation. This is
+ * controlled through mbedtls_ecp_set_max_ops() which limits the maximum
+ * number of ECC operations a function may perform before pausing; see
+ * mbedtls_ecp_set_max_ops() for more information.
  *
  * This is useful in non-threaded environments if you want to avoid blocking
- * for too long on ECC (hence, X509 or SSL/TLS) operations.
+ * for too long on ECC (and, hence, X.509 or SSL/TLS) operations.
  *
  * Uncomment this macro to enable restartable ECC computations.
  */
diff --git a/include/mbedtls/ecdh.h b/include/mbedtls/ecdh.h
index ed3e8df..8b75b93 100644
--- a/include/mbedtls/ecdh.h
+++ b/include/mbedtls/ecdh.h
@@ -91,10 +91,10 @@
  * \param p_rng     The RNG context.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX or
- *                  \c MBEDTLS_MPI_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX or
+ *                  \c MBEDTLS_MPI_XXX error code on failure.
  */
 int mbedtls_ecdh_gen_public( mbedtls_ecp_group *grp, mbedtls_mpi *d, mbedtls_ecp_point *Q,
                      int (*f_rng)(void *, unsigned char *, size_t),
@@ -121,10 +121,10 @@
  * \param p_rng     The RNG context.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX or
- *                  \c MBEDTLS_MPI_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX or
+ *                  \c MBEDTLS_MPI_XXX error code on failure.
  */
 int mbedtls_ecdh_compute_shared( mbedtls_ecp_group *grp, mbedtls_mpi *z,
                          const mbedtls_ecp_point *Q, const mbedtls_mpi *d,
@@ -166,9 +166,9 @@
  * \param p_rng     The RNG context.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_make_params( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -210,9 +210,9 @@
  *                  0: The key of the peer.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  *
  */
 int mbedtls_ecdh_get_params( mbedtls_ecdh_context *ctx, const mbedtls_ecp_keypair *key,
@@ -235,9 +235,9 @@
  * \param p_rng     The RNG context.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_make_public( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
@@ -283,9 +283,9 @@
  * \param p_rng     The RNG context.
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX error code on failure.
  */
 int mbedtls_ecdh_calc_secret( mbedtls_ecdh_context *ctx, size_t *olen,
                       unsigned char *buf, size_t blen,
diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index d5f7985..4057828 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -73,7 +73,7 @@
 /**
  * \brief           Internal restart context for ecdsa_verify()
  *
- * \note            Opaque struct
+ * \note            Opaque struct, defined in ecdsa.c
  */
 typedef struct mbedtls_ecdsa_restart_ver mbedtls_ecdsa_restart_ver_ctx;
 
@@ -273,13 +273,13 @@
  * \param slen      The length of the signature written.
  * \param f_rng     The RNG function.
  * \param p_rng     The RNG context.
- * \param rs_ctx    The restart context.
+ * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
- * \return          An \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
- *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX, \c MBEDTLS_ERR_MPI_XXX or
+ *                  \c MBEDTLS_ERR_ASN1_XXX error code on failure.
  */
 int mbedtls_ecdsa_write_signature_restartable( mbedtls_ecdsa_context *ctx,
                            mbedtls_md_type_t md_alg,
@@ -387,16 +387,16 @@
  * \param hlen      The size of the hash.
  * \param sig       The signature to read and verify.
  * \param slen      The size of \p sig.
- * \param rs_ctx    The restart context
+ * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_BAD_INPUT_DATA if signature is invalid.
  * \return          #MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH if there is a valid
  *                  signature in \p sig, but its length is less than \p siglen.
- * \return          An \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
- *                  error code on failure for any other reason.
  * \return          #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
  *                  operations was reached: see \c mbedtls_ecp_set_max_ops().
+ * \return          Another \c MBEDTLS_ERR_ECP_XXX or \c MBEDTLS_ERR_MPI_XXX
+ *                  error code on failure for any other reason.
  */
 int mbedtls_ecdsa_read_signature_restartable( mbedtls_ecdsa_context *ctx,
                           const unsigned char *hash, size_t hlen,
diff --git a/include/mbedtls/ecp.h b/include/mbedtls/ecp.h
index 15aee04..d13f3ba 100644
--- a/include/mbedtls/ecp.h
+++ b/include/mbedtls/ecp.h
@@ -50,7 +50,7 @@
 #define MBEDTLS_ERR_ECP_INVALID_KEY                       -0x4C80  /**< Invalid private or public key. */
 #define MBEDTLS_ERR_ECP_SIG_LEN_MISMATCH                  -0x4C00  /**< The buffer contains a valid signature followed by more data. */
 #define MBEDTLS_ERR_ECP_HW_ACCEL_FAILED                   -0x4B80  /**< The ECP hardware accelerator failed. */
-#define MBEDTLS_ERR_ECP_IN_PROGRESS                       -0x4B00  /**< Operation in progress, try again with the same parameters. */
+#define MBEDTLS_ERR_ECP_IN_PROGRESS                       -0x4B00  /**< Operation in progress, call again with the same parameters to continue. */
 
 #ifdef __cplusplus
 extern "C" {
@@ -747,7 +747,7 @@
  * \param P         The point to multiply.
  * \param f_rng     The RNG function.
  * \param p_rng     The RNG context.
- * \param rs_ctx    The restart context.
+ * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m is not a valid private
@@ -804,7 +804,7 @@
  * \param P         The point to multiply by \p m.
  * \param n         The integer by which to multiply \p Q.
  * \param Q         The point to be multiplied by \p n.
- * \param rs_ctx    The restart context.
+ * \param rs_ctx    The restart context (NULL disables restart).
  *
  * \return          \c 0 on success.
  * \return          #MBEDTLS_ERR_ECP_INVALID_KEY if \p m or \p n are not
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 3b486cf..9ec33da 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -127,7 +127,7 @@
  */
 typedef struct mbedtls_pk_context
 {
-    const mbedtls_pk_info_t *   pk_info; /**< Public key informations        */
+    const mbedtls_pk_info_t *   pk_info; /**< Public key information         */
     void *                      pk_ctx;  /**< Underlying public key context  */
 } mbedtls_pk_context;
 
@@ -137,7 +137,7 @@
  */
 typedef struct
 {
-    const mbedtls_pk_info_t *   pk_info; /**< Public key informations        */
+    const mbedtls_pk_info_t *   pk_info; /**< Public key information         */
     void *                      rs_ctx;  /**< Underlying restart context     */
 } mbedtls_pk_restart_ctx;
 #else /* MBEDTLS_ECDSA_C && MBEDTLS_ECP_RESTARTABLE */
diff --git a/include/mbedtls/x509_crt.h b/include/mbedtls/x509_crt.h
index 961db98..afeefca 100644
--- a/include/mbedtls/x509_crt.h
+++ b/include/mbedtls/x509_crt.h
@@ -426,7 +426,7 @@
  * \param flags    result of the verification
  * \param f_vrfy   verification function
  * \param p_vrfy   verification parameter
- * \param rs_ctx   restart context
+ * \param rs_ctx   restart context (NULL to disable restart)
  *
  * \return         See \c mbedtls_crt_verify_with_profile(), or
  * \return         #MBEDTLS_ERR_ECP_IN_PROGRESS if maximum number of
diff --git a/library/error.c b/library/error.c
index d48ba8f..3345481 100644
--- a/library/error.c
+++ b/library/error.c
@@ -290,7 +290,7 @@
         if( use_ret == -(MBEDTLS_ERR_ECP_HW_ACCEL_FAILED) )
             mbedtls_snprintf( buf, buflen, "ECP - The ECP hardware accelerator failed" );
         if( use_ret == -(MBEDTLS_ERR_ECP_IN_PROGRESS) )
-            mbedtls_snprintf( buf, buflen, "ECP - Operation in progress, try again with the same parameters" );
+            mbedtls_snprintf( buf, buflen, "ECP - Operation in progress, call again with the same parameters to continue" );
 #endif /* MBEDTLS_ECP_C */
 
 #if defined(MBEDTLS_MD_C)