From 160dc30e0c897bc822e19f0acc5d972941de98d4 Mon Sep 17 00:00:00 2001
From: "Neal H. Walfield" <neal@pep.foundation>
Date: Fri, 13 Oct 2023 12:56:49 +0200
Subject: openpgp: Improve documentation.

  - `Cert::from_str`, `Cert::from_reader`, `Cert::from_file`, and
    `Cert::from_bytes` return an error if the input contains multiple
    certificates.

  - Improve the documentation to make that clearer, and suggest the
    use of `CertParser` to parse keyrings.
---
 openpgp/src/cert.rs | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

(limited to 'openpgp/src/cert.rs')

diff --git a/openpgp/src/cert.rs b/openpgp/src/cert.rs
index e1ba1b6a..9c8a1869 100644
--- a/openpgp/src/cert.rs
+++ b/openpgp/src/cert.rs
@@ -757,25 +757,44 @@ assert_send_and_sync!(Cert);
 impl std::str::FromStr for Cert {
     type Err = anyhow::Error;
 
+    /// Parses and returns a certificate.
+    ///
+    /// `s` must return an OpenPGP-encoded certificate.
+    ///
+    /// If `s` contains multiple certificates, this returns an error.
+    /// Use [`CertParser`] if you want to parse a keyring.
     fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
         Self::from_bytes(s.as_bytes())
     }
 }
 
 impl<'a> Parse<'a, Cert> for Cert {
-    /// Returns the first Cert encountered in the reader.
+    /// Parses and returns a certificate.
+    ///
+    /// The reader must return an OpenPGP-encoded certificate.
+    ///
+    /// If `reader` contains multiple certificates, this returns an
+    /// error.  Use [`CertParser`] if you want to parse a keyring.
     fn from_reader<R: io::Read + Send + Sync>(reader: R) -> Result<Self> {
         Cert::try_from(PacketParser::from_reader(reader)?)
     }
 
-    /// Returns the first Cert encountered in the file.
+    /// Parses and returns a certificate.
+    ///
+    /// The file must contain an OpenPGP-encoded certificate.
+    ///
+    /// If the file contains multiple certificates, this returns an
+    /// error.  Use [`CertParser`] if you want to parse a keyring.
     fn from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
         Cert::try_from(PacketParser::from_file(path)?)
     }
 
-    /// Returns the first Cert found in `buf`.
+    /// Parses and returns a certificate.
+    ///
+    /// `buf` must contain an OpenPGP-encoded certificate.
     ///
-    /// `buf` must be an OpenPGP-encoded message.
+    /// If `buf` contains multiple certificates, this returns an
+    /// error.  Use [`CertParser`] if you want to parse a keyring.
     fn from_bytes<D: AsRef<[u8]> + ?Sized + Send + Sync>(data: &'a D) -> Result<Self> {
         Cert::try_from(PacketParser::from_bytes(data)?)
     }
-- 
cgit v1.2.3