openpgp: Improve documentation for PacketParserEOF.

  - See #471.

1 files changed, 206 insertions, 6 deletions

diff --git a/openpgp/src/parse.rs b/openpgp/src/parse.rs
index eb9e1175..3b4ba821 100644
--- a/openpgp/src/parse.rs
+++ b/openpgp/src/parse.rs
@@ -2984,6 +2984,50 @@ enum ParserResult<'a> {
 
 /// Information about the stream of packets parsed by the
 /// `PacketParser`.
+///
+/// Once the [`PacketParser`] reaches the end of the input stream, it
+/// returns a [`PacketParserResult::EOF`] with a `PacketParserEOF`.
+/// This object provides information about the parsed stream, notably
+/// whether or not the packet stream was a well-formed [`Message`],
+/// [`Cert`] or keyring.
+///
+///   [`PacketParser`]: struct.PacketParser.html
+///   [`PacketParserResult::EOF`]: enum.PacketParserResult.html#variant.EOF
+///   [`Message`]: ../struct.Message.html
+///   [`Cert`]: ../cert/struct.Cert.html
+///
+/// # Examples
+///
+/// Parse some OpenPGP stream using a [`PacketParser`] and detects the
+/// kind of data:
+///
+/// ```rust
+/// # fn main() -> sequoia_openpgp::Result<()> {
+/// use sequoia_openpgp as openpgp;
+/// use openpgp::Packet;
+/// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+///
+/// let openpgp_data: &[u8] = // ...
+/// #    include_bytes!("../tests/data/keys/public-key.gpg");
+/// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+/// while let PacketParserResult::Some(mut pp) = ppr {
+///     // Start parsing the next packet, recursing.
+///     ppr = pp.recurse()?.1;
+/// }
+///
+/// if let PacketParserResult::EOF(eof) = ppr {
+///     if eof.is_message().is_ok() {
+///         // ...
+///     } else if eof.is_cert().is_ok() {
+///         // ...
+///     } else if eof.is_keyring().is_ok() {
+///         // ...
+///     } else {
+///         // ...
+///     }
+/// }
+/// # Ok(()) }
+/// ```
 #[derive(Debug)]
 pub struct PacketParserEOF {
     state: PacketParserState,
@@ -3005,9 +3049,43 @@ impl PacketParserEOF {
         }
     }
 
-    /// Whether the message is an OpenPGP Message.
+    /// Returns whether the stream is an OpenPGP Message.
+    ///
+    /// A [`Message`] has a very specific structure.  Returns `true`
+    /// if the stream is of that form, as opposed to a [`Cert`] or
+    /// just a bunch of packets.
+    ///
+    ///   [`Message`]: ../struct.Message.html
+    ///   [`Cert`]: ../cert/struct.Cert.html
     ///
-    /// As opposed to a Cert or just a bunch of packets.
+    /// # Examples
+    ///
+    /// Parse some OpenPGP stream using a [`PacketParser`] and detects the
+    /// kind of data:
+    ///
+    ///   [`PacketParser`]: struct.PacketParser.html
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// use sequoia_openpgp as openpgp;
+    /// use openpgp::Packet;
+    /// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+    ///
+    /// let openpgp_data: &[u8] = // ...
+    /// #    include_bytes!("../tests/data/keys/public-key.gpg");
+    /// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+    /// while let PacketParserResult::Some(mut pp) = ppr {
+    ///     // Start parsing the next packet, recursing.
+    ///     ppr = pp.recurse()?.1;
+    /// }
+    ///
+    /// if let PacketParserResult::EOF(eof) = ppr {
+    ///     if eof.is_message().is_ok() {
+    ///         // ...
+    ///     }
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn is_message(&self) -> Result<()> {
         use crate::message::MessageValidity;
 
@@ -3018,9 +3096,42 @@ impl PacketParserEOF {
         }
     }
 
-    /// Whether the message is an OpenPGP keyring.
+    /// Returns whether the message is an OpenPGP keyring.
+    ///
+    /// A keyring has a very specific structure.  Returns `true` if
+    /// the stream is of that form, as opposed to a [`Message`] or
+    /// just a bunch of packets.
+    ///
+    ///   [`Message`]: ../struct.Message.html
+    ///
+    /// # Examples
     ///
-    /// As opposed to a Message or just a bunch of packets.
+    /// Parse some OpenPGP stream using a [`PacketParser`] and detects the
+    /// kind of data:
+    ///
+    ///   [`PacketParser`]: struct.PacketParser.html
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// use sequoia_openpgp as openpgp;
+    /// use openpgp::Packet;
+    /// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+    ///
+    /// let openpgp_data: &[u8] = // ...
+    /// #    include_bytes!("../tests/data/keys/public-key.gpg");
+    /// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+    /// while let PacketParserResult::Some(mut pp) = ppr {
+    ///     // Start parsing the next packet, recursing.
+    ///     ppr = pp.recurse()?.1;
+    /// }
+    ///
+    /// if let PacketParserResult::EOF(eof) = ppr {
+    ///     if eof.is_keyring().is_ok() {
+    ///         // ...
+    ///     }
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn is_keyring(&self) -> Result<()> {
         match self.state.keyring_validator.check() {
             KeyringValidity::Keyring => Ok(()),
@@ -3029,9 +3140,43 @@ impl PacketParserEOF {
         }
     }
 
-    /// Whether the message is an OpenPGP Cert.
+    /// Returns whether the message is an OpenPGP Cert.
+    ///
+    /// A [`Cert`] has a very specific structure.  Returns `true` if
+    /// the stream is of that form, as opposed to a [`Message`] or
+    /// just a bunch of packets.
+    ///
+    ///   [`Message`]: ../struct.Message.html
+    ///   [`Cert`]: ../cert/struct.Cert.html
+    ///
+    /// # Examples
+    ///
+    /// Parse some OpenPGP stream using a [`PacketParser`] and detects the
+    /// kind of data:
+    ///
+    ///   [`PacketParser`]: struct.PacketParser.html
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// use sequoia_openpgp as openpgp;
+    /// use openpgp::Packet;
+    /// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+    ///
+    /// let openpgp_data: &[u8] = // ...
+    /// #    include_bytes!("../tests/data/keys/public-key.gpg");
+    /// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+    /// while let PacketParserResult::Some(mut pp) = ppr {
+    ///     // Start parsing the next packet, recursing.
+    ///     ppr = pp.recurse()?.1;
+    /// }
     ///
-    /// As opposed to a Message or just a bunch of packets.
+    /// if let PacketParserResult::EOF(eof) = ppr {
+    ///     if eof.is_cert().is_ok() {
+    ///         // ...
+    ///     }
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn is_cert(&self) -> Result<()> {
         match self.state.cert_validator.check() {
             CertValidity::Cert => Ok(()),
@@ -3041,6 +3186,34 @@ impl PacketParserEOF {
     }
 
     /// Returns the path of the last packet.
+    ///
+    /// # Examples
+    ///
+    /// Parse some OpenPGP stream using a [`PacketParser`] and returns
+    /// the path (see [`PacketPile::path_ref`]) of the last packet:
+    ///
+    ///   [`PacketPile::path_ref`]: ../struct.PacketPile.html#method.path_ref
+    ///   [`PacketParser`]: struct.PacketParser.html
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// use sequoia_openpgp as openpgp;
+    /// use openpgp::Packet;
+    /// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+    ///
+    /// let openpgp_data: &[u8] = // ...
+    /// #    include_bytes!("../tests/data/keys/public-key.gpg");
+    /// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+    /// while let PacketParserResult::Some(mut pp) = ppr {
+    ///     // Start parsing the next packet, recursing.
+    ///     ppr = pp.recurse()?.1;
+    /// }
+    ///
+    /// if let PacketParserResult::EOF(eof) = ppr {
+    ///     let _ = eof.last_path();
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn last_path(&self) -> &[usize] {
         &self.last_path[..]
     }
@@ -3049,6 +3222,33 @@ impl PacketParserEOF {
     ///
     /// A top-level packet has a recursion depth of 0.  Packets in a
     /// top-level container have a recursion depth of 1, etc.
+    ///
+    /// # Examples
+    ///
+    /// Parse some OpenPGP stream using a [`PacketParser`] and returns
+    /// the recursion depth of the last packet:
+    ///
+    ///   [`PacketParser`]: struct.PacketParser.html
+    ///
+    /// ```rust
+    /// # fn main() -> sequoia_openpgp::Result<()> {
+    /// use sequoia_openpgp as openpgp;
+    /// use openpgp::Packet;
+    /// use openpgp::parse::{Parse, PacketParserResult, PacketParser};
+    ///
+    /// let openpgp_data: &[u8] = // ...
+    /// #    include_bytes!("../tests/data/keys/public-key.gpg");
+    /// let mut ppr = PacketParser::from_bytes(openpgp_data)?;
+    /// while let PacketParserResult::Some(mut pp) = ppr {
+    ///     // Start parsing the next packet, recursing.
+    ///     ppr = pp.recurse()?.1;
+    /// }
+    ///
+    /// if let PacketParserResult::EOF(eof) = ppr {
+    ///     let _ = eof.last_recursion_depth();
+    /// }
+    /// # Ok(()) }
+    /// ```
     pub fn last_recursion_depth(&self) -> Option<isize> {
         if self.last_path.len() == 0 {
             None