openpgp: Improve documentation for packet::prelude

  - Improve documentation for the `packet::prelude` module.

  - Sort the imports.

  - Also import packet::signature::SignatureBuilder.

  - See #470.

1 files changed, 47 insertions, 25 deletions

diff --git a/openpgp/src/packet/prelude.rs b/openpgp/src/packet/prelude.rs
index 7f4d3b14..c0df4d78 100644
--- a/openpgp/src/packet/prelude.rs
+++ b/openpgp/src/packet/prelude.rs
@@ -1,36 +1,58 @@
-//! Conveniently re-exports everything below openpgp::packet.
+//! Brings the most relevant types and traits into scope for working
+//! with packets.
+//!
+//! Less often used types and types that are more likely to lead to a
+//! naming conflict are not brought into scope.  For instance, the
+//! markers [`PublicParts`], etc. are not imported to avoid potential
+//! naming conflicts.  Instead, they should be accessed as
+//! [`key::PublicParts`].  And, [`user_attribute::Subpacket`] is not
+//! imported, because it is rarely used.  If required, it should be
+//! imported explicitly.
+//!
+//! [`PublicParts`]: ../key/struct.PublicParts.html
+//! [`key::PublicParts`]: ../key/struct.PublicParts.html
+//! [`user_attribute::Subpacket`]: ../user_attribute/struct.Subpacket.html
+//!
+//! # Examples
+//!
+//! ```
+//! # #![allow(unused_imports)]
+//! # extern crate sequoia_openpgp as openpgp;
+//! use openpgp::packet::prelude::*;
+//! ```
 
-pub use crate::Packet;
 pub use crate::packet::{
-    Tag,
-    Header,
-    Container,
+    AED,
     Body,
-    Unknown,
-    Signature,
-    signature,
-    signature::Signature4,
-    OnePassSig,
-    one_pass_sig::OnePassSig3,
+    CompressedData,
+    Container,
+    Header,
     Key,
-    key,
-    key::Key4,
-    key::SecretKeyMaterial,
+    Literal,
+    MDC,
     Marker,
+    OnePassSig,
+    PKESK,
+    Packet,
+    SEIP,
+    SKESK,
+    Signature,
+    Tag,
     Trust,
-    UserID,
-    user_attribute,
+    Unknown,
     UserAttribute,
-    Literal,
-    CompressedData,
-    PKESK,
+    UserID,
+    aed::AED1,
+    key,
+    key::Key4,
+    key::SecretKeyMaterial,
+    one_pass_sig::OnePassSig3,
     pkesk::PKESK3,
-    SKESK,
+    seip::SEIP1,
+    signature,
+    signature::Signature4,
+    signature::SignatureBuilder,
     skesk::SKESK4,
     skesk::SKESK5,
-    SEIP,
-    seip::SEIP1,
-    MDC,
-    AED,
-    aed::AED1,
+    user_attribute,
 };