openpgp: Improve documentation.

1 files changed, 12 insertions, 7 deletions

diff --git a/openpgp/src/serialize/cert.rs b/openpgp/src/serialize/cert.rs
index 263b875d..f45bfb91 100644
--- a/openpgp/src/serialize/cert.rs
+++ b/openpgp/src/serialize/cert.rs
@@ -290,7 +290,7 @@ impl Cert {
     }
 }
 
-/// A reference to a Cert that allows serialization of secret keys.
+/// A reference to a `Cert` that allows serialization of secret keys.
 ///
 /// To avoid accidental leakage, secret keys are not serialized when a
 /// serializing a [`Cert`].  To serialize [`Cert`]s with secret keys,
@@ -301,10 +301,10 @@ impl Cert {
 /// [`Cert::as_tsk()`]: ../cert/struct.Cert.html#method.as_tsk
 ///
 /// # Example
+///
 /// ```
 /// # use sequoia_openpgp::{*, cert::*, parse::Parse, serialize::Serialize};
-/// # f().unwrap();
-/// # fn f() -> Result<()> {
+/// # fn main() -> Result<()> {
 /// let (cert, _) = CertBuilder::new().generate()?;
 /// assert!(cert.is_tsk());
 ///
@@ -315,6 +315,7 @@ impl Cert {
 /// assert!(cert_.is_tsk());
 /// assert_eq!(cert, cert_);
 /// # Ok(()) }
+/// ```
 pub struct TSK<'a> {
     cert: &'a Cert,
     filter: Option<Box<dyn Fn(&'a key::UnspecifiedSecret) -> bool + 'a>>,
@@ -334,12 +335,15 @@ impl<'a> TSK<'a> {
     /// Note that the given filter replaces any existing filter.
     ///
     /// # Example
+    ///
+    /// This example demonstrates how to create a TSK with a detached
+    /// primary secret key.
+    ///
     /// ```
     /// # use sequoia_openpgp::{*, cert::*, parse::Parse, serialize::Serialize};
     /// use sequoia_openpgp::policy::StandardPolicy;
     ///
-    /// # f().unwrap();
-    /// # fn f() -> Result<()> {
+    /// # fn main() -> Result<()> {
     /// let p = &StandardPolicy::new();
     ///
     /// let (cert, _) = CertBuilder::new().add_signing_subkey().generate()?;
@@ -348,13 +352,14 @@ impl<'a> TSK<'a> {
     /// // Only write out the primary key's secret.
     /// let mut buf = Vec::new();
     /// cert.as_tsk()
-    ///     .set_filter(|k| k.fingerprint() == cert.fingerprint())
+    ///     .set_filter(|k| k.fingerprint() != cert.fingerprint())
     ///     .serialize(&mut buf)?;
     ///
     /// let cert_ = Cert::from_bytes(&buf)?;
+    /// assert!(! cert_.primary_key().has_secret());
     /// assert_eq!(cert_.keys().with_policy(p, None).alive().revoked(false).secret().count(), 1);
-    /// assert!(cert_.primary_key().has_secret());
     /// # Ok(()) }
+    /// ```
     pub fn set_filter<P>(mut self, predicate: P) -> Self
         where P: 'a + Fn(&'a key::UnspecifiedSecret) -> bool
     {