openpgp: Improve documentation.

  - In `Cert::keys`, `Cert::userids` and `Cert::user_attributes`, we
    that `ValidCert:userids`, etc. is better than `Cert::userids`, etc.,
    mention that `Cert::with_policy` can be used to turn a `Cert` into a
    `ValidCert`.

  - Fixes #921.

1 files changed, 6 insertions, 3 deletions

diff --git a/openpgp/src/cert.rs b/openpgp/src/cert.rs
index fcb1e21c..819b9245 100644
--- a/openpgp/src/cert.rs
+++ b/openpgp/src/cert.rs
@@ -1062,7 +1062,8 @@ impl Cert {
     /// **Note:** This returns all User IDs, even those without a
     /// binding signature.  This is not what you want, unless you are
     /// doing a low-level inspection of the certificate.  Use
-    /// [`ValidCert::userids`] instead.
+    /// [`ValidCert::userids`] instead.  (You turn a `Cert` into a
+    /// [`ValidCert`] by using [`Cert::with_policy`].)
     ///
     /// # Examples
     ///
@@ -1096,7 +1097,8 @@ impl Cert {
     /// **Note:** This returns all User Attributes, even those without
     /// a binding signature.  This is not what you want, unless you
     /// are doing a low-level inspection of the certificate.  Use
-    /// [`ValidCert::user_attributes`] instead.
+    /// [`ValidCert::user_attributes`] instead.  (You turn a `Cert`
+    /// into a [`ValidCert`] by using [`Cert::with_policy`].)
     ///
     /// # Examples
     ///
@@ -1127,7 +1129,8 @@ impl Cert {
     /// **Note:** This returns all keys, even those without a binding
     /// signature.  This is not what you want, unless you are doing a
     /// low-level inspection of the certificate.  Use
-    /// [`ValidCert::keys`] instead.
+    /// [`ValidCert::keys`] instead.  (You turn a `Cert` into a
+    /// [`ValidCert`] by using [`Cert::with_policy`].)
     ///
     /// By necessity, this function erases the returned keys' roles.
     /// If you are only interested in the primary key, use