diff --git a/include/mbedtls/ecdsa.h b/include/mbedtls/ecdsa.h
index b1fd884..57f9b48 100644
--- a/include/mbedtls/ecdsa.h
+++ b/include/mbedtls/ecdsa.h
@@ -52,6 +52,8 @@
 /**
  * \brief           Compute ECDSA signature of a previously hashed message
  *
+ * \note            The deterministic version is usually prefered.
+ *
  * \param grp       ECP group
  * \param r         First output integer
  * \param s         Second output integer
@@ -70,8 +72,8 @@
 
 #if defined(POLARSSL_ECDSA_DETERMINISTIC)
 /**
- * \brief           Compute ECDSA signature of a previously hashed message
- *                  (deterministic version)
+ * \brief           Compute ECDSA signature of a previously hashed message,
+ *                  deterministic version (RFC 6979).
  *
  * \param grp       ECP group
  * \param r         First output integer
diff --git a/include/mbedtls/pk.h b/include/mbedtls/pk.h
index 14ac65e..8fda581 100644
--- a/include/mbedtls/pk.h
+++ b/include/mbedtls/pk.h
@@ -377,7 +377,8 @@
  * \note            If hash_len is 0, then the length associated with md_alg
  *                  is used instead, or an error returned if it is invalid.
  *
- * \note            md_alg may be POLARSSL_MD_NONE, only if hash_len != 0
+ * \note            For RSA, md_alg may be POLARSSL_MD_NONE if hash_len != 0.
+ *                  For ECDSA, md_alg may never be POLARSSL_MD_NONE.
  */
 int pk_sign( pk_context *ctx, md_type_t md_alg,
              const unsigned char *hash, size_t hash_len,