diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 56bf397..59e80e5 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -24,20 +24,20 @@
 #define MBEDTLS_ECJPAKE_H
 
 /*
- * Implementation based on Chapter 7.4 of the Thread v1.0 Specification,
- * available from the Thread Group http://threadgroup.org/
- *
  * J-PAKE is a password-authenticated key exchange that allows deriving a
  * strong shared secret from a (potentially low entropy) pre-shared
  * passphrase, with forward secrecy and mutual authentication.
  * https://en.wikipedia.org/wiki/Password_Authenticated_Key_Exchange_by_Juggling
  *
- * This file implements the EC J-PAKE algorithm with payload serializations
- * suitable for use in TLS, but the result could be used outside TLS.
+ * This file implements the Elliptic Curve variant of J-PAKE,
+ * as defined in Chapter 7.4 of the Thread v1.0 Specification,
+ * available to members of the Thread Group http://threadgroup.org/
  *
  * As the J-PAKE algorithm is inherently symmetric, so is our API.
  * Each party needs to send its first round message, in any order, to the
  * other party, then each sends its second round message, in any order.
+ * The payloads are serialized in a way suitable for use in TLS, but could
+ * also be use outside TLS.
  */
 
 #include "ecp.h"
@@ -84,7 +84,7 @@
     mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
 } mbedtls_ecjpake_context;
 
-/*
+/**
  * \brief           Initialize a context
  *                  (just makes it ready for setup() or free()).
  *
@@ -92,7 +92,7 @@
  */
 void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
 
-/*
+/**
  * \brief           Set up a context for use
  *
  * \note            Currently the only values for hash/curve allowed by the
@@ -115,7 +115,7 @@
                            const unsigned char *secret,
                            size_t len );
 
-/*
+/**
  * \brief           Generate and write the first round message
  *                  (TLS: contents of the Client/ServerHello extension,
  *                  excluding extension type and length bytes)
@@ -134,8 +134,9 @@
                             unsigned char *buf, size_t len, size_t *olen,
                             int (*f_rng)(void *, unsigned char *, size_t),
                             void *p_rng );
-/*
- * \brief           Generate and write the first round message
+
+/**
+ * \brief           Read and process the first round message
  *                  (TLS: contents of the Client/ServerHello extension,
  *                  excluding extension type and length bytes)
  *
@@ -150,9 +151,9 @@
                                     const unsigned char *buf,
                                     size_t len );
 
-/*
- * \brief           Generate and write ClientECJPAKEParams
- *                  (the contents for the ClientKeyExchange)
+/**
+ * \brief           Generate and write the second round message
+ *                  (TLS: contents of the Client/ServerKeyExchange)
  *
  * \param ctx       Context to use
  * \param buf       Buffer to write the contents to
@@ -169,9 +170,9 @@
                             int (*f_rng)(void *, unsigned char *, size_t),
                             void *p_rng );
 
-/*
- * \brief           Read and process ClientECJPAKEParams
- *                  (the contents for the ClientKeyExchange)
+/**
+ * \brief           Read and process the second round message
+ *                  (TLS: contents of the Client/ServerKeyExchange)
  *
  * \param ctx       Context to use
  * \param buf       Pointer to the message
@@ -181,11 +182,12 @@
  *                  a negative error code otherwise
  */
 int mbedtls_ecjpake_read_round_two( mbedtls_ecjpake_context *ctx,
-                                            const unsigned char *buf,
-                                            size_t len );
+                                    const unsigned char *buf,
+                                    size_t len );
 
-/*
- * \brief           Derive the Pre-Master Secret used by TLS
+/**
+ * \brief           Derive the shared secret
+ *                  (TLS: Pre-Master Secret)
  *
  * \param ctx
  * \param buf       Buffer to write the contents to
@@ -197,12 +199,12 @@
  * \return          0 if successfull,
  *                  a negative error code otherwise
  */
-int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx,
+int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
                             unsigned char *buf, size_t len, size_t *olen,
                             int (*f_rng)(void *, unsigned char *, size_t),
                             void *p_rng );
 
-/*
+/**
  * \brief           Free a context's content
  *
  * \param ctx       context to free
diff --git a/library/ecjpake.c b/library/ecjpake.c
index e09d742..b0fda20 100644
--- a/library/ecjpake.c
+++ b/library/ecjpake.c
@@ -647,7 +647,7 @@
 /*
  * Derive PMS (7.4.2.7 / 7.4.2.8)
  */
-int mbedtls_ecjpake_tls_derive_pms( mbedtls_ecjpake_context *ctx,
+int mbedtls_ecjpake_derive_secret( mbedtls_ecjpake_context *ctx,
                             unsigned char *buf, size_t len, size_t *olen,
                             int (*f_rng)(void *, unsigned char *, size_t),
                             void *p_rng )
@@ -946,7 +946,7 @@
 
     TEST_ASSERT( mbedtls_ecjpake_read_round_two( &cli, buf, len ) == 0 );
 
-    TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli,
+    TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli,
                  pms, sizeof( pms ), &pmslen, ecjpake_lgc, NULL ) == 0 );
 
     TEST_ASSERT( mbedtls_ecjpake_write_round_two( &cli,
@@ -954,7 +954,7 @@
 
     TEST_ASSERT( mbedtls_ecjpake_read_round_two( &srv, buf, len ) == 0 );
 
-    TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv,
+    TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv,
                  buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
 
     TEST_ASSERT( len == pmslen );
@@ -996,7 +996,7 @@
                             sizeof( ecjpake_test_cli_kx ) ) == 0 );
 
     /* Server derives PMS */
-    TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &srv,
+    TEST_ASSERT( mbedtls_ecjpake_derive_secret( &srv,
                  buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
 
     TEST_ASSERT( len == sizeof( ecjpake_test_pms ) );
@@ -1005,7 +1005,7 @@
     memset( buf, 0, len ); /* Avoid interferences with next step */
 
     /* Client derives PMS */
-    TEST_ASSERT( mbedtls_ecjpake_tls_derive_pms( &cli,
+    TEST_ASSERT( mbedtls_ecjpake_derive_secret( &cli,
                  buf, sizeof( buf ), &len, ecjpake_lgc, NULL ) == 0 );
 
     TEST_ASSERT( len == sizeof( ecjpake_test_pms ) );