From 6b798b9dae0c2690f4dd74d9a52f81addf861f02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= <mpg2@elzevir.fr>
Date: Fri, 14 Aug 2015 11:18:30 +0200
Subject: [PATCH] Tune up some comments

---
 include/mbedtls/ecjpake.h | 22 ++++++++++++++++++----
 library/ecjpake.c         |  4 ++--
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/include/mbedtls/ecjpake.h b/include/mbedtls/ecjpake.h
index 2f1a8abca..e3efe0a26 100644
--- a/include/mbedtls/ecjpake.h
+++ b/include/mbedtls/ecjpake.h
@@ -23,6 +23,14 @@
 #ifndef MBEDTLS_ECJPAKE_H
 #define MBEDTLS_ECJPAKE_H
 
+/*
+ * Implementation based on Chapter 7.4 of the Thread v1.0 Specification,
+ * available from the Thread Group http://threadgroup.org/
+ *
+ * This file implements the EC J-PAKE algorithm, with payload serializations
+ * suitable for use in TLS, but the result could be used outside TLS.
+ */
+
 #include "ecp.h"
 #include "md.h"
 
@@ -30,11 +38,17 @@
 extern "C" {
 #endif
 
+/**
+ * Roles in the EC J-PAKE exchange
+ */
 typedef enum {
-    MBEDTLS_ECJPAKE_CLIENT = 0,
-    MBEDTLS_ECJPAKE_SERVER,
+    MBEDTLS_ECJPAKE_CLIENT = 0,         /**< Client                         */
+    MBEDTLS_ECJPAKE_SERVER,             /**< Server                         */
 } mbedtls_ecjpake_role;
 
+/**
+ * EC J-PAKE context structure
+ */
 typedef struct
 {
     const mbedtls_md_info_t *md_info;   /**< Hash to use                    */
@@ -50,7 +64,7 @@ typedef struct
     mbedtls_mpi xa;                     /**< Our first secret (x1 or x3)    */
     mbedtls_mpi xb;                     /**< Our second secret (x2 or x4)   */
 
-    mbedtls_mpi s;                      /**< Pre-shared secret              */
+    mbedtls_mpi s;                      /**< Pre-shared secret (passphrase) */
 } mbedtls_ecjpake_context;
 
 /*
@@ -71,7 +85,7 @@ void mbedtls_ecjpake_init( mbedtls_ecjpake_context *ctx );
  * \param role      Our role: client or server
  * \param hash      hash function to use (MBEDTLS_MD_XXX)
  * \param curve     elliptic curve identifier (MBEDTLS_ECP_DP_XXX)
- * \param secret    shared secret
+ * \param secret    pre-shared secret (passphrase)
  * \param len       length of the shared secret
  *
  * \return          0 if successfull,
diff --git a/library/ecjpake.c b/library/ecjpake.c
index 84dce0457..987c7e396 100644
--- a/library/ecjpake.c
+++ b/library/ecjpake.c
@@ -20,8 +20,8 @@
  */
 
 /*
- * We implement EC-JPAKE as defined in Chapter 7.4 of the Thread v1.0
- * Specification. References below are to this document.
+ * References in the code are to the Thread v1.0 Specification,
+ * available from the Thread Group http://threadgroup.org/
  */
 
 #if !defined(MBEDTLS_CONFIG_FILE)