openpgp: Improve documentation.

6 files changed, 24 insertions, 6 deletions

diff --git a/openpgp/src/packet/aed.rs b/openpgp/src/packet/aed.rs
index a84fcd01..32b49572 100644
--- a/openpgp/src/packet/aed.rs
+++ b/openpgp/src/packet/aed.rs
@@ -17,6 +17,12 @@ use crate::Result;
 /// [Section 5.16 of RFC 4880bis]: https://tools.ietf.org/html/draft-ietf-openpgp-rfc4880bis-05#section-5.16
 ///
 /// This feature is [experimental](../../index.html#experimental-features).
+///
+/// # A note on equality
+///
+/// An unprocessed (encrypted) `SEIP` packet is never considered equal
+/// to a processed (decrypted) one.  Likewise, a processed (decrypted)
+/// packet is never considered equal to a structured (parsed) one.
 // IMPORTANT: If you add fields to this struct, you need to explicitly
 // IMPORTANT: implement PartialEq, Eq, and Hash.
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
diff --git a/openpgp/src/packet/mdc.rs b/openpgp/src/packet/mdc.rs
index 704e1c0a..68a4e9ae 100644
--- a/openpgp/src/packet/mdc.rs
+++ b/openpgp/src/packet/mdc.rs
@@ -11,8 +11,8 @@ use crate::Packet;
 ///
 /// # A note on equality
 ///
-/// Two `Signature` packets are considered equal if their serialized
-/// form is equal.  This excludes the computed digest.
+/// Two `MDC` packets are considered equal if their serialized form is
+/// equal.  This excludes the computed digest.
 #[derive(Clone, Debug)]
 pub struct MDC {
     /// CTB packet header fields.
diff --git a/openpgp/src/packet/mod.rs b/openpgp/src/packet/mod.rs
index 976d6ecc..657d46b5 100644
--- a/openpgp/src/packet/mod.rs
+++ b/openpgp/src/packet/mod.rs
@@ -355,8 +355,9 @@ fn packet_path_iter() {
 /// # A note on equality
 ///
 /// Two `Signature` packets are considered equal if their serialized
-/// form is equal.  Notably this includes the unhashed subpacket area,
-/// but excludes the computed digest and signature level.
+/// form is equal.  Notably this includes the unhashed subpacket area
+/// and the order of subpackets and notations, but excludes the
+/// computed digest and signature level.
 ///
 /// A consequence of considering packets in the unhashed subpacket
 /// area is that an adversary can take a valid signature and create
diff --git a/openpgp/src/packet/one_pass_sig.rs b/openpgp/src/packet/one_pass_sig.rs
index 0fdad6e2..d3ff5fa8 100644
--- a/openpgp/src/packet/one_pass_sig.rs
+++ b/openpgp/src/packet/one_pass_sig.rs
@@ -22,6 +22,11 @@ use crate::SignatureType;
 /// See [Section 5.4 of RFC 4880] for details.
 ///
 ///   [Section 5.4 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5.4
+///
+/// # A note on equality
+///
+/// The `last` flag is represented as a `u8` and is compared
+/// literally, not semantically.
 // IMPORTANT: If you add fields to this struct, you need to explicitly
 // IMPORTANT: implement PartialEq, Eq, and Hash.
 #[derive(Clone, PartialEq, Eq, Hash)]
diff --git a/openpgp/src/packet/seip.rs b/openpgp/src/packet/seip.rs
index 76487bef..b71937ae 100644
--- a/openpgp/src/packet/seip.rs
+++ b/openpgp/src/packet/seip.rs
@@ -14,6 +14,12 @@ use crate::Packet;
 /// 4880] for details.
 ///
 /// [Section 5.13 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-5.13
+///
+/// # A note on equality
+///
+/// An unprocessed (encrypted) `SEIP` packet is never considered equal
+/// to a processed (decrypted) one.  Likewise, a processed (decrypted)
+/// packet is never considered equal to a structured (parsed) one.
 // IMPORTANT: If you add fields to this struct, you need to explicitly
 // IMPORTANT: implement PartialEq, Eq, and Hash.
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
diff --git a/openpgp/src/packet/unknown.rs b/openpgp/src/packet/unknown.rs
index 4cd876ee..1deab130 100644
--- a/openpgp/src/packet/unknown.rs
+++ b/openpgp/src/packet/unknown.rs
@@ -14,8 +14,8 @@ use crate::Packet;
 ///
 /// # A note on equality
 ///
-/// Two `Unknown` packets are considered equal if their tag and their
-/// body is equal.
+/// Two `Unknown` packets are considered equal if their tags and their
+/// bodies are equal.
 #[derive(Debug)]
 pub struct Unknown {
     /// CTB packet header fields.