From b6df16e949090470daccded88b1884a439566fa4 Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Fri, 17 Jan 2020 12:35:56 +0100 Subject: openpgp: Improve the MessageLayer documentation. - Fixes #411. --- openpgp/src/parse/stream.rs | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/openpgp/src/parse/stream.rs b/openpgp/src/parse/stream.rs index 8867b332..774e2d2c 100644 --- a/openpgp/src/parse/stream.rs +++ b/openpgp/src/parse/stream.rs @@ -234,6 +234,15 @@ impl<'a> VerificationResult<'a> { } /// Communicates the message structure to the VerificationHelper. +/// +/// A valid OpenPGP message contains one literal data packet with +/// optional [encryption, signing, and compression layers] on top. +/// This structure is passed to [`VerificationHelper::check`] for +/// verification. This method must check whether the structure is +/// compatible with your policy. +/// +/// [encryption, signing, and compression layers]: enum.MessageLayer.html +/// [`VerificationHelper::check`]: trait.VerificationHelper.html#tymethod.check #[derive(Debug)] pub struct MessageStructure<'a>(Vec>); @@ -304,6 +313,9 @@ impl<'a> Iterator for MessageStructureIntoIter<'a> { } /// Represents a layer of the message structure. +/// +/// A valid OpenPGP message contains one literal data packet with +/// optional encryption, signing, and compression layers on top. #[derive(Debug)] pub enum MessageLayer<'a> { /// Represents an compression container. @@ -319,6 +331,17 @@ pub enum MessageLayer<'a> { aead_algo: Option, }, /// Represents a signature group. + /// + /// A signature group consists of all signatures with the same + /// [level]. Each [`VerificationResult`] represents the result of + /// a single signature verification. In your + /// [`VerificationHelper::check`] method, iterate over the + /// verification results, see if it meets your policies' demands, + /// and communicate it to the user, if applicable. + /// + /// [level]: enum.VerificationResult.html#method.level + /// [`VerificationResult`]: enum.VerificationResult.html + /// [`VerificationHelper::check`]: trait.VerificationHelper.html#tymethod.check SignatureGroup { /// The results of the signature verifications. results: Vec>, -- cgit v1.2.3