doc: improved documentation on certificate and DANE verification functions

2 files changed, 17 insertions, 10 deletions

diff --git a/lib/gnutls_cert.c b/lib/gnutls_cert.c
index 15508b493c..446e9888ab 100644
--- a/lib/gnutls_cert.c
+++ b/lib/gnutls_cert.c
@@ -597,7 +597,7 @@ _gnutls_openpgp_crt_verify_peers(gnutls_session_t session,
  * or use gnutls_certificate_verify_peers3().
  *
  * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0)
- * when the peer's certificate was successfully parsed, whether or not
+ * when the peer's certificate was successfully parsed, irrespective of whether
  * it was verified.
  **/
 int
@@ -630,8 +630,8 @@ gnutls_certificate_verify_peers2(gnutls_session_t session,
  * In order to verify the purpose of the end-certificate (by checking the extended
  * key usage), use gnutls_certificate_verify_peers().
  *
- * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0) 
- * when the peer's certificate was successfully parsed, whether or not
+ * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0)
+ * when the peer's certificate was successfully parsed, irrespective of whether
  * it was verified.
  *
  * Since: 3.1.4
@@ -677,7 +677,7 @@ gnutls_typed_vdata_st data;
  * or be marked for any purpose, otherwise verification will fail with %GNUTLS_CERT_SIGNER_CONSTRAINTS_FAILURE status.
  *
  * Returns: a negative error code on error and %GNUTLS_E_SUCCESS (0)
- * when the peer's certificate was successfully parsed, whether or not
+ * when the peer's certificate was successfully parsed, irrespective of whether
  * it was verified.
  *
  * Since: 3.3.0
diff --git a/libdane/dane.c b/libdane/dane.c
index 76a769047e..c46d5e3b8f 100644
--- a/libdane/dane.c
+++ b/libdane/dane.c
@@ -748,8 +748,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
@@ -850,8 +853,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
@@ -910,8 +916,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