diff --git a/include/mbedtls/dhm.h b/include/mbedtls/dhm.h
index 00fafd8..2829ffc 100644
--- a/include/mbedtls/dhm.h
+++ b/include/mbedtls/dhm.h
@@ -1,7 +1,12 @@
 /**
  * \file dhm.h
  *
- * \brief Diffie-Hellman-Merkle key exchange.
+ * \brief This file contains DHM definitions and functions.
+ *
+ * Diffie-Hellman-Merkle (DHM) key exchange is defined in
+ * <em>RFC-2631: Diffie-Hellman Key Agreement Method</em> and 
+ * <em>Public-Key Cryptography Standards (PKCS) #3: Diffie 
+ * Hellman Key Agreement Standard</em>.
  *
  * <em>RFC-3526: More Modular Exponential (MODP) Diffie-Hellman groups for
  * Internet Key Exchange (IKE)</em> defines a number of standardized
@@ -125,8 +130,8 @@
  *                 failures.
  * \param end      The end of the input buffer.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_read_params( mbedtls_dhm_context *ctx,
                      unsigned char **p,
@@ -136,13 +141,6 @@
  * \brief          This function sets up and writes the ServerKeyExchange
  *                 parameters.
  *
- * \param ctx      The DHM context.
- * \param x_size   The private value size in Bytes.
- * \param olen     The number of characters written.
- * \param output   The destination buffer.
- * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
- *
  * \note           The destination buffer must be large enough to hold
  *                 the reduced binary presentation of the modulus, the generator
  *                 and the public key, each wrapped with a 2-byte length field.
@@ -155,8 +153,15 @@
  *                 mbedtls_dhm_set_group() below in conjunction with
  *                 mbedtls_mpi_read_binary() and mbedtls_mpi_read_string().
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \param ctx      The DHM context.
+ * \param x_size   The private key size in Bytes.
+ * \param olen     The number of characters written.
+ * \param output   The destination buffer.
+ * \param f_rng    The RNG function.
+ * \param p_rng    The RNG context.
+ *
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_make_params( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t *olen,
@@ -164,54 +169,54 @@
                      void *p_rng );
 
 /**
- * \brief          Set prime modulus and generator
+ * \brief          This function sets the prime modulus and generator.
+ *
+ * \note           This function can be used to set \p P, \p G
+ *                 in preparation for mbedtls_dhm_make_params().
  *
  * \param ctx      The DHM context.
- * \param P        The MPI holding DHM prime modulus.
- * \param G        The MPI holding DHM generator.
+ * \param P        The MPI holding the DHM prime modulus.
+ * \param G        The MPI holding the DHM generator.
  *
- * \note           This function can be used to set P, G
- *                 in preparation for \c mbedtls_dhm_make_params.
- *
- * \return         \c 0 if successful, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 if successful.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_set_group( mbedtls_dhm_context *ctx,
                            const mbedtls_mpi *P,
                            const mbedtls_mpi *G );
 
 /**
- * \brief          This function imports the public value G^Y of the peer.
+ * \brief          This function imports the G^Y public value of the peer.
  *
  * \param ctx      The DHM context.
- * \param input    The input buffer.
+ * \param input    The input buffer containing the G^Y value of the peer.
  * \param ilen     The size of the input buffer.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_read_public( mbedtls_dhm_context *ctx,
                      const unsigned char *input, size_t ilen );
 
 /**
- * \brief          This function creates its own private value \c X and
+ * \brief          This function creates its own \c X private key and
  *                 exports \c G^X.
  *
+ * \note           The destination buffer is always fully written
+ *                 so as to contain a big-endian representation of G^X mod P.
+ *                 If it is larger than ctx->len, it is padded accordingly
+ *                 with zero-bytes at the beginning.
+ *
  * \param ctx      The DHM context.
- * \param x_size   The private value size in Bytes.
+ * \param x_size   The private key size in Bytes.
  * \param output   The destination buffer.
  * \param olen     The length of the destination buffer. Must be at least
-                   equal to ctx->len (the size of \c P).
+ *                  equal to ctx->len (the size of \c P).
  * \param f_rng    The RNG function.
- * \param p_rng    The RNG parameter.
+ * \param p_rng    The RNG context.
  *
- * \note           The destination buffer will always be fully written
- *                 so as to contain a big-endian presentation of G^X mod P.
- *                 If it is larger than ctx->len, it will accordingly be
- *                 padded with zero-bytes in the beginning.
- *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_make_public( mbedtls_dhm_context *ctx, int x_size,
                      unsigned char *output, size_t olen,
@@ -222,22 +227,22 @@
  * \brief               This function derives and exports the shared secret
  *                      \c (G^Y)^X mod \c P.
  *
+ * \note                If \p f_rng is not NULL, it is used to blind the input as
+ *                      a countermeasure against timing attacks. Blinding is used
+ *                      only if our private key \c X is re-used, and not used
+ *                      otherwise. We recommend always passing a non-NULL
+ *                      \p f_rng argument.
+ *
  * \param ctx           The DHM context.
  * \param output        The destination buffer.
  * \param output_size   The size of the destination buffer. Must be at least
- *                      the size of ctx->len.
+ *                      the size of ctx->len (the size of \c P).
  * \param olen          On exit, holds the actual number of Bytes written.
  * \param f_rng         The RNG function, for blinding purposes.
- * \param p_rng         The RNG parameter.
+ * \param p_rng         The RNG context.
  *
- * \return         \c 0 on success, or an \c MBEDTLS_ERR_DHM_XXX error code
- *                 on failure.
- *
- * \note           If non-NULL, \p f_rng is used to blind the input as
- *                 a countermeasure against timing attacks. Blinding is used
- *                 only if our secret value \p X is re-used and omitted
- *                 otherwise. Therefore, we recommend always passing a
- *                 non-NULL \p f_rng argument.
+ * \return              \c 0 on success.
+ * \return              An \c MBEDTLS_ERR_DHM_XXX error code on failure.
  */
 int mbedtls_dhm_calc_secret( mbedtls_dhm_context *ctx,
                      unsigned char *output, size_t output_size, size_t *olen,
@@ -245,7 +250,7 @@
                      void *p_rng );
 
 /**
- * \brief          This function frees and clears the components of a DHM key.
+ * \brief          This function frees and clears the components of a DHM context.
  *
  * \param ctx      The DHM context to free and clear.
  */
@@ -261,8 +266,8 @@
  * \param dhminlen    The size of the buffer, including the terminating null
  *                    Byte for PEM data.
  *
- * \return            \c 0 on success, or a specific DHM or PEM error code
- *                    on failure.
+ * \return            \c 0 on success.
+ * \return            A specific DHM or PEM error code on failure.
  */
 int mbedtls_dhm_parse_dhm( mbedtls_dhm_context *dhm, const unsigned char *dhmin,
                    size_t dhminlen );
@@ -275,8 +280,8 @@
  * \param dhm      The DHM context to load the parameters to.
  * \param path     The filename to read the DHM parameters from.
  *
- * \return         \c 0 on success, or a specific DHM or PEM error code
- *                 on failure.
+ * \return         \c 0 on success.
+ * \return         A specific DHM or PEM error code on failure.
  */
 int mbedtls_dhm_parse_dhmfile( mbedtls_dhm_context *dhm, const char *path );
 #endif /* MBEDTLS_FS_IO */
@@ -297,7 +302,8 @@
 /**
  * \brief          The DMH checkup routine.
  *
- * \return         \c 0 on success, or \c 1 on failure.
+ * \return         \c 0 on success.
+ * \return         \c 1 on failure.
  */
 int mbedtls_dhm_self_test( int verbose );