doc: improved documentation on certificate and DANE verification functions

1 files changed, 13 insertions, 6 deletions

diff --git a/libdane/dane.c b/libdane/dane.c
index 7d9c861875..64682b2983 100644
--- a/libdane/dane.c
+++ b/libdane/dane.c
@@ -750,8 +750,11 @@ verify_ee(const gnutls_datum_t * raw_crt,
  * This function does not perform any resolving, it utilizes
  * cached entries from @r.
  *
- * Returns: On success, %DANE_E_SUCCESS (0) is returned, otherwise a
- *   negative error value.
+ * Returns: a negative error code on error and %DANE_E_SUCCESS (0)
+ * when the DANE entries were successfully parsed, irrespective of
+ * whether they were verified (see @verify for that information). If
+ * no usable entries were encountered %DANE_E_REQUESTED_DATA_NOT_AVAILABLE
+ * will be returned.
  *
  **/
 int
@@ -852,8 +855,11 @@ dane_verify_crt_raw(dane_state_t s,
  * then the function will check whether the key of the peer matches the
  * key advertized in the DANE entry.
  *
- * Returns: On success, %DANE_E_SUCCESS (0) is returned, otherwise a
- *   negative error value.
+ * Returns: a negative error code on error and %DANE_E_SUCCESS (0)
+ * when the DANE entries were successfully parsed, irrespective of
+ * whether they were verified (see @verify for that information). If
+ * no usable entries were encountered %DANE_E_REQUESTED_DATA_NOT_AVAILABLE
+ * will be returned.
  *
  **/
 int
@@ -912,8 +918,9 @@ dane_verify_crt(dane_state_t s,
  * verification is restricted to end certificates, this must be
  * be performed separately using gnutls_certificate_verify_peers3().
  *
- * Returns: On success, %DANE_E_SUCCESS (0) is returned, otherwise a
- *   negative error value.
+ * Returns: a negative error code on error and %DANE_E_SUCCESS (0)
+ * when the DANE entries were successfully parsed, irrespective of
+ * whether they were verified (see @verify for that information).
  *
  **/
 int