Update comments for high-level helpers

src/lib.rs

@@ -56,11 +56,10 @@ use pki_types::{
 use std::io;
 use std::iter;
 
-/// Extract all the certificates from `rd`, and return a vec of byte vecs
-/// containing the der-format contents.
+/// Return an iterator over certificates from `rd`.
 ///
-/// This function does not fail if there are no certificates in the file --
-/// it returns an empty vector.
+/// Filters out any PEM sections that are not certificates and yields errors if a problem
+/// occurs while trying to extract a certificate.
 pub fn certs(
     rd: &mut dyn io::BufRead,
 ) -> impl Iterator<Item = Result<CertificateDer<'static>, io::Error>> + '_ {
@@ -71,11 +70,10 @@ pub fn certs(
     })
 }
 
-/// Extract all the certificate revocation lists (CRLs) from `rd`, and return a vec of byte vecs
-/// containing the der-format contents.
+/// Return an iterator certificate revocation lists (CRLs) from `rd`.
 ///
-/// This function does not fail if there are no CRLs in the file --
-/// it returns an empty vector.
+/// Filters out any PEM sections that are not CRLs and yields errors if a problem occurs
+/// while trying to extract a CRL.
 pub fn crls(
     rd: &mut dyn io::BufRead,
 ) -> impl Iterator<Item = Result<CertificateRevocationListDer<'static>, io::Error>> + '_ {
@@ -86,11 +84,10 @@ pub fn crls(
     })
 }
 
-/// Extract all RSA private keys from `rd`, and return a vec of byte vecs
-/// containing the der-format contents.
+/// Return an iterator over RSA private keys from `rd`.
 ///
-/// This function does not fail if there are no keys in the file -- it returns an
-/// empty vector.
+/// Filters out any PEM sections that are not RSA private keys and yields errors if a problem
+/// occurs while trying to extract an RSA private key.
 pub fn rsa_private_keys(
     rd: &mut dyn io::BufRead,
 ) -> impl Iterator<Item = Result<PrivatePkcs1KeyDer<'static>, io::Error>> + '_ {
@@ -101,11 +98,10 @@ pub fn rsa_private_keys(
     })
 }
 
-/// Extract all PKCS8-encoded private keys from `rd`, and return a vec of
-/// byte vecs containing the der-format contents.
+/// Return an iterator over PKCS8-encoded private keys from `rd`.
 ///
-/// This function does not fail if there are no keys in the file -- it returns an
-/// empty vector.
+/// Filters out any PEM sections that are not PKCS8-encoded private keys and yields errors if a
+/// problem occurs while trying to extract an RSA private key.
 pub fn pkcs8_private_keys(
     rd: &mut dyn io::BufRead,
 ) -> impl Iterator<Item = Result<PrivatePkcs8KeyDer<'static>, io::Error>> + '_ {
@@ -116,11 +112,10 @@ pub fn pkcs8_private_keys(
     })
 }
 
-/// Extract all SEC1-encoded EC private keys from `rd`, and return a vec of
-/// byte vecs containing the der-format contents.
+/// Return an iterator over SEC1-encoded EC private keys from `rd`.
 ///
-/// This function does not fail if there are no keys in the file -- it returns an
-/// empty vector.
+/// Filters out any PEM sections that are not SEC1-encoded EC private keys and yields errors if a
+/// problem occurs while trying to extract a SEC1-encoded EC private key.
 pub fn ec_private_keys(
     rd: &mut dyn io::BufRead,
 ) -> impl Iterator<Item = Result<PrivateSec1KeyDer<'static>, io::Error>> + '_ {