improve wording

3 files changed, 74 insertions, 20 deletions

diff --git a/openpgp/src/fingerprint.rs b/openpgp/src/fingerprint.rs
index 7f26f0fe..07996f8a 100644
--- a/openpgp/src/fingerprint.rs
+++ b/openpgp/src/fingerprint.rs
@@ -7,14 +7,22 @@ use quickcheck::{Arbitrary, Gen};
 /// about how a fingerprint is generated, see [Section 12.2 of RFC
 /// 4880].
 ///
+/// See also [`Fingerprint`], [`KeyHandle`].
+///
 ///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
+///
+///   [`Fingerprint`]: ./Enum.Fingerprint.html
+///   [`KeyHandle`]: ./Enum.KeyHandle.html
+///
+/// # Example
+/// TODO: signature.issuer
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
 pub enum Fingerprint {
-    /// 20 byte SHA-1 hash.
+    /// A 20 byte SHA-1 hash of the public key packet as defined in the RFC.
     V4([u8;20]),
-    /// Used for holding fingerprints that we don't understand.  For
-    /// instance, we don't grok v3 fingerprints.  And, it is possible
-    /// that the Issuer subpacket contains the wrong number of bytes.
+    /// Used for holding fingerprint data that does not conform to
+    /// the specification of a V4 fingerprint, e.g. a V3 fingerprint
+    /// (deprecated) or otherwise wrong-length data.
     Invalid(Box<[u8]>)
 }
 
@@ -60,7 +68,7 @@ impl Fingerprint {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
+    /// # use sequoia_openpgp as openpgp;
     /// # use openpgp::Result;
     /// use openpgp::Fingerprint;
     ///
@@ -88,7 +96,7 @@ impl Fingerprint {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
+    /// # use sequoia_openpgp as openpgp;
     /// # use openpgp::Result;
     /// use openpgp::Fingerprint;
     ///
@@ -211,7 +219,7 @@ impl Fingerprint {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
+    /// # use sequoia_openpgp as openpgp;
     /// # use openpgp::Result;
     /// use openpgp::Fingerprint;
     ///
diff --git a/openpgp/src/keyhandle.rs b/openpgp/src/keyhandle.rs
index c9b613c1..16ab2cbf 100644
--- a/openpgp/src/keyhandle.rs
+++ b/openpgp/src/keyhandle.rs
@@ -12,7 +12,43 @@ use crate::{
 
 /// Identifies certificates and keys.
 ///
-/// A `KeyHandle` is either a `Fingerprint` or a `KeyID`.
+/// A `KeyHandle` is either a [`Fingerprint`] or a [`KeyHandle`].
+///
+///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
+///
+///   [`Fingerprint`]: ./Enum.Fingerprint.html
+///   [`KeyHandle`]: ./Enum.KeyHandle.html
+/// # Examples
+///
+/// ```ignore
+/// # use sequoia_openpgp as openpgp;
+/// # use openpgp::Result;
+/// # use openpgp::{Fingerprint, KeyHandle};
+/// # use openpgp::crypto::KeyPair;
+/// # use openpgp::types::{Curve, SignatureType};
+/// # use openpgp::packet::signature::Builder;
+/// #
+/// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
+/// # fn load_certs() -> Vec<openpgp::Cert> {
+/// #   Vec::new()
+/// # }
+/// # fn load_signature() -> openpgp::packet::Signature {
+/// # panic!()
+/// # }
+///
+/// let key: Fingerprint = "0123 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;
+///
+/// let signature = load_signature();
+/// let certs: Vec<openpgp::Cert> = load_certs();
+///
+/// let issuers = signature.get_issuers();
+///
+/// let foo = certs
+///   .iter()
+///   .filter(|cert| issuers.iter().any(|issuer_kh| issuer_kh.aliases(&cert.key_handle())));
+/// # return Ok(());
+/// # }
+/// ```
 #[derive(Debug, Clone, Hash)]
 pub enum KeyHandle {
     /// A Fingerprint.
@@ -146,7 +182,7 @@ impl PartialEq for KeyHandle {
 }
 
 impl KeyHandle {
-    /// Returns a reference to the raw identifier.
+    /// Returns the raw identifier as a byte slice.
     pub fn as_bytes(&self) -> &[u8] {
         match self {
             KeyHandle::Fingerprint(i) => i.as_bytes(),
diff --git a/openpgp/src/keyid.rs b/openpgp/src/keyid.rs
index 3333052d..47ddb110 100644
--- a/openpgp/src/keyid.rs
+++ b/openpgp/src/keyid.rs
@@ -11,7 +11,12 @@ use crate::Result;
 /// but is easy to forge.  For more details about how a `KeyID` is
 /// generated, see [Section 12.2 of RFC 4880].
 ///
+/// See also [`Fingerprint`], [`KeyHandle`].
+///
 ///   [Section 12.2 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-12.2
+///
+///   [`Fingerprint`]: ./Enum.Fingerprint.html
+///   [`KeyHandle`]: ./Enum.KeyHandle.html
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Hash)]
 pub enum KeyID {
     /// Lower 8 byte SHA-1 hash.
@@ -138,9 +143,9 @@ impl KeyID {
     /// # extern crate sequoia_openpgp as openpgp;
     /// use openpgp::KeyID;
     ///
-    /// let keyid = KeyID::new(0x123456789ABCDEF1);
+    /// let keyid = KeyID::new(0x0123456789ABCDEF);
     ///
-    /// assert_eq!(keyid.as_u64().unwrap(), 0x123456789ABCDEF1);
+    /// assert_eq!(keyid.as_u64().unwrap(), 0x0123456789ABCDEF);
     /// ```
     pub fn as_u64(&self) -> Result<u64> {
         match &self {
@@ -159,10 +164,13 @@ impl KeyID {
     /// # extern crate sequoia_openpgp as openpgp;
     /// use openpgp::KeyID;
     ///
-    /// let bytes = [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF1];
-    /// let keyid = KeyID::from_bytes(&bytes);
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// let keyid: KeyID = "0123 4567 89AB CDEF".parse()?;
     ///
-    /// assert_eq!(keyid, KeyID::new(0x123456789ABCDEF1u64));
+    /// let bytes = [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF];
+    /// assert_eq!(KeyID::from_bytes(&bytes), keyid);
+    /// # Ok(())
+    /// # }
     /// ```
     pub fn from_bytes(raw: &[u8]) -> KeyID {
         if raw.len() == 8 {
@@ -180,13 +188,15 @@ impl KeyID {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
-    /// # use openpgp::Result;
+    /// # use sequoia_openpgp as openpgp;
     /// use openpgp::KeyID;
     ///
-    /// let keyid = KeyID::new(0x123456789ABCDEF1);
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// let keyid: KeyID = "0123 4567 89AB CDEF".parse()?;
     ///
-    /// assert_eq!(keyid.as_bytes(), [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF1]);
+    /// assert_eq!(keyid.as_bytes(), [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF]);
+    /// # Ok(())
+    /// # }
     /// ```
     pub fn as_bytes(&self) -> &[u8] {
         match self {
@@ -204,7 +214,7 @@ impl KeyID {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
+    /// # use sequoia_openpgp as openpgp;
     /// # use openpgp::Result;
     /// use openpgp::KeyID;
     ///
@@ -225,7 +235,7 @@ impl KeyID {
     /// # Examples
     ///
     /// ```rust
-    /// # extern crate sequoia_openpgp as openpgp;
+    /// # use sequoia_openpgp as openpgp;
     /// # use openpgp::Result;
     /// use openpgp::KeyID;
     ///