Use 'Examples' for the examples section.

  - See #480.

24 files changed, 88 insertions, 88 deletions

diff --git a/core/src/lib.rs b/core/src/lib.rs
index b1b39d2e..904facc1 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -4,7 +4,7 @@
 //! Therefore, we need you to provide a little information about the
 //! context you are using Sequoia in.
 //!
-/// # Example
+/// # Examples
 ///
 /// A context with reasonable defaults can be created using
 /// `Context::new`:
@@ -27,7 +27,7 @@ use std::path::{Path, PathBuf};
 
 /// A `Context` for Sequoia.
 ///
-/// # Example
+/// # Examples
 ///
 /// A context with reasonable defaults can be created using
 /// `Context::new`:
diff --git a/ffi-macros/src/lib.rs b/ffi-macros/src/lib.rs
index 6a3d2386..1500a721 100644
--- a/ffi-macros/src/lib.rs
+++ b/ffi-macros/src/lib.rs
@@ -106,7 +106,7 @@ fn doc(s: &str, ts: &mut TokenStream2) {
 /// [undefined behavior]: https://doc.rust-lang.org/nomicon/unwinding.html
 /// [catch_unwind]: https://doc.rust-lang.org/std/panic/fn.catch_unwind.html
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,ignore
 /// #[ffi_catch_abort]
@@ -175,7 +175,7 @@ pub fn ffi_catch_abort(_attr: TokenStream, item: TokenStream) -> TokenStream {
 
 /// Derives FFI functions for a wrapper type.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```rust,ignore
 /// /// Holds a fingerprint.
diff --git a/ffi/src/core.rs b/ffi/src/core.rs
index 111ae19f..3051b133 100644
--- a/ffi/src/core.rs
+++ b/ffi/src/core.rs
@@ -4,7 +4,7 @@
 //! Therefore, we need you to provide a little information about the
 //! context you are using Sequoia in.
 //!
-//! # Example
+//! # Examples
 //!
 //! A context with reasonable defaults can be created using
 //! `sq_context_new`:
diff --git a/ffi/src/lib.rs b/ffi/src/lib.rs
index 45844ded..745ca6c8 100644
--- a/ffi/src/lib.rs
+++ b/ffi/src/lib.rs
@@ -89,7 +89,7 @@
 //! `Context` return complex errors.  Complex errors are stored in the
 //! `Context`, and can be retrieved using `sq_last_strerror`.
 //!
-//! # Example
+//! # Examples
 //!
 //! ```c
 //! #include <sequoia.h>
diff --git a/ffi/src/net.rs b/ffi/src/net.rs
index d386e92d..01263870 100644
--- a/ffi/src/net.rs
+++ b/ffi/src/net.rs
@@ -4,7 +4,7 @@
 //!
 //! [HKP]: https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00
 //!
-//! # Example
+//! # Examples
 //!
 //! We provide a very reasonable default key server backed by
 //! `hkps.pool.sks-keyservers.net`, the subset of the [SKS keyserver]
diff --git a/ffi/src/store.rs b/ffi/src/store.rs
index 408b02a5..482f0dec 100644
--- a/ffi/src/store.rs
+++ b/ffi/src/store.rs
@@ -16,7 +16,7 @@
 //!
 //! [network policy]: ../../sequoia_core/enum.NetworkPolicy.html
 //!
-//! # Example
+//! # Examples
 //!
 //! ```c, ignore
 //! XXX
diff --git a/ipc/src/lib.rs b/ipc/src/lib.rs
index 50ab9e9a..1a5a58b7 100644
--- a/ipc/src/lib.rs
+++ b/ipc/src/lib.rs
@@ -355,7 +355,7 @@ impl Server {
     /// On Windows this expects `SOCKET` env var to be set to a listening socket
     /// of the Windows Sockets API `SOCKET` value.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```compile_fail
     /// // We cannot run this because sequoia-store is not built yet.
diff --git a/net/src/lib.rs b/net/src/lib.rs
index 64b3e3e0..cdd05cc1 100644
--- a/net/src/lib.rs
+++ b/net/src/lib.rs
@@ -4,7 +4,7 @@
 //!
 //! [HKP]: https://tools.ietf.org/html/draft-shaw-openpgp-hkp-00
 //!
-//! # Example
+//! # Examples
 //!
 //! We provide a very reasonable default key server backed by
 //! `hkps.pool.sks-keyservers.net`, the subset of the [SKS keyserver]
diff --git a/net/src/wkd.rs b/net/src/wkd.rs
index 53ecdfb5..759f17cd 100644
--- a/net/src/wkd.rs
+++ b/net/src/wkd.rs
@@ -261,7 +261,7 @@ fn parse_body<S: AsRef<str>>(body: &[u8], email_address: S)
 /// ```
 ///
 /// [draft-koch]: https://datatracker.ietf.org/doc/html/draft-koch-openpgp-webkey-service/#section-3.1
-/// # Example
+/// # Examples
 ///
 /// ```no_run
 /// use tokio_core::reactor::Core;
diff --git a/openpgp-ffi/src/armor.rs b/openpgp-ffi/src/armor.rs
index 9421e783..71ee8539 100644
--- a/openpgp-ffi/src/armor.rs
+++ b/openpgp-ffi/src/armor.rs
@@ -68,7 +68,7 @@ fn int_to_reader_mode(mode: c_int) -> armor::ReaderMode {
 ///
 /// A filter that strips ASCII Armor from a stream of data.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
@@ -149,7 +149,7 @@ pub extern "C" fn pgp_armor_reader_from_file(errp: Option<&mut *mut crate::error
 
 /// Creates a `Reader` from a buffer.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
@@ -220,7 +220,7 @@ fn pgp_armor_reader_from_bytes(b: *const u8, len: size_t,
 /// has not been encountered yet (try reading some data first!), this
 /// function returns PGP_ARMOR_KIND_ANY.
 ///
-/// # Example
+/// # Examples
 ///
 /// See [this] example.
 ///
@@ -250,7 +250,7 @@ pub extern "C" fn pgp_armor_reader_kind(reader: *const Reader)
 /// allocated with `malloc`, and the caller is responsible for freeing
 /// both the array and the strings.
 ///
-/// # Example
+/// # Examples
 ///
 /// See [this] example.
 ///
@@ -306,7 +306,7 @@ pub extern "C" fn pgp_armor_reader_headers(errp: Option<&mut *mut crate::error::
 /// Note: You must call `pgp_armor_writer_finalize` to deallocate this
 /// writer.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #define _GNU_SOURCE
diff --git a/openpgp-ffi/src/cert.rs b/openpgp-ffi/src/cert.rs
index c3893399..84fd520d 100644
--- a/openpgp-ffi/src/cert.rs
+++ b/openpgp-ffi/src/cert.rs
@@ -186,7 +186,7 @@ fn int_to_reason_for_revocation(code: c_int) -> ReasonForRevocation {
 ///
 /// This function does *not* consume `cert`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
@@ -881,7 +881,7 @@ pub extern "C" fn pgp_cert_parser_free(parser: Option<&mut CertParserWrapper>)
 
 /// Creates a default `pgp_cert_builder_t`.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
diff --git a/openpgp-ffi/src/fingerprint.rs b/openpgp-ffi/src/fingerprint.rs
index 76303631..716d2d23 100644
--- a/openpgp-ffi/src/fingerprint.rs
+++ b/openpgp-ffi/src/fingerprint.rs
@@ -48,7 +48,7 @@ fn pgp_fingerprint_from_bytes(buf: *const u8,
 
 /// Reads a hexadecimal fingerprint.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
diff --git a/openpgp-ffi/src/keyid.rs b/openpgp-ffi/src/keyid.rs
index 1cbd41b8..c5ed5dbe 100644
--- a/openpgp-ffi/src/keyid.rs
+++ b/openpgp-ffi/src/keyid.rs
@@ -36,7 +36,7 @@ pub struct KeyID(openpgp::KeyID);
 
 /// Reads a binary key ID.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
@@ -62,7 +62,7 @@ fn pgp_keyid_from_bytes(id: *const u8) -> *mut KeyID {
 
 /// Reads a hex-encoded Key ID.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
diff --git a/openpgp-ffi/src/packet/key.rs b/openpgp-ffi/src/packet/key.rs
index 1ec3b62a..60d2ae3c 100644
--- a/openpgp-ffi/src/packet/key.rs
+++ b/openpgp-ffi/src/packet/key.rs
@@ -108,7 +108,7 @@ fn pgp_key_has_unencrypted_secret(key: *const Key) -> bool
 /// This function takes ownership of `key`.  On failure, `key` is
 /// deallocated.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #include <assert.h>
diff --git a/openpgp-ffi/src/parse/stream.rs b/openpgp-ffi/src/parse/stream.rs
index d1c2f625..747452a0 100644
--- a/openpgp-ffi/src/parse/stream.rs
+++ b/openpgp-ffi/src/parse/stream.rs
@@ -535,7 +535,7 @@ impl VerificationHelper for VHelper {
 /// No attempt is made to decrypt any encryption packets.  These are
 /// treated as opaque containers.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #define _GNU_SOURCE
@@ -663,7 +663,7 @@ pub struct DetachedVerifier(openpgp::parse::stream::DetachedVerifier<'static, VH
 
 /// Verifies a detached OpenPGP signature.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #define _GNU_SOURCE
@@ -904,7 +904,7 @@ impl DecryptionHelper for DHelper {
 ///
 /// Note: all of the parameters are required; none may be NULL.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```c
 /// #define _GNU_SOURCE
diff --git a/openpgp/src/cert/bindings.rs b/openpgp/src/cert/bindings.rs
index 56ca443e..5da9360d 100644
--- a/openpgp/src/cert/bindings.rs
+++ b/openpgp/src/cert/bindings.rs
@@ -29,7 +29,7 @@ impl<P: key::KeyParts> Key<P, key::SubordinateRole> {
     /// fingerprint subpacket, and a issuer subpacket to the
     /// signature.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to bind this key to a Cert.  Note
     /// that in general, the `CertBuilder` is a better way to add
@@ -91,7 +91,7 @@ impl UserID {
     /// fingerprint subpacket, and a issuer subpacket to the
     /// signature.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to bind this userid to a Cert.
     /// Note that in general, the `CertBuilder` is a better way to add
@@ -146,7 +146,7 @@ impl UserID {
     /// one of `SignatureType::{Generic, Persona, Casual,
     /// Positive}Certificate`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to certify a userid.
     ///
@@ -222,7 +222,7 @@ impl UserAttribute {
     /// fingerprint subpacket, and a issuer subpacket to the
     /// signature.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to bind this user attribute to a
     /// Cert.  Note that in general, the `CertBuilder` is a better way
@@ -282,7 +282,7 @@ impl UserAttribute {
     /// one of `SignatureType::{Generic, Persona, Casual,
     /// Positive}Certificate`
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to certify a userid.
     ///
diff --git a/openpgp/src/cert/parser/mod.rs b/openpgp/src/cert/parser/mod.rs
index 8bd91317..7530345c 100644
--- a/openpgp/src/cert/parser/mod.rs
+++ b/openpgp/src/cert/parser/mod.rs
@@ -424,7 +424,7 @@ impl CertValidator {
 /// [`Cert`]: ../struct.Cert.html
 /// [`Unknown`]: ../enum.Packet.html#variant.Unknown
 ///
-/// # Example
+/// # Examples
 ///
 /// Print information about all certificates in a keyring:
 ///
diff --git a/openpgp/src/fmt.rs b/openpgp/src/fmt.rs
index 586aa922..f7bb8e31 100644
--- a/openpgp/src/fmt.rs
+++ b/openpgp/src/fmt.rs
@@ -37,7 +37,7 @@ pub mod hex {
 
     /// Writes annotated hex dumps, like hd(1).
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     ///  use sequoia_openpgp::fmt::hex;
diff --git a/openpgp/src/packet_pile.rs b/openpgp/src/packet_pile.rs
index a7d3c03c..a623132f 100644
--- a/openpgp/src/packet_pile.rs
+++ b/openpgp/src/packet_pile.rs
@@ -27,7 +27,7 @@ use crate::parse::Cookie;
 /// Normally, you'll want to convert the `PacketPile` to a Cert or a
 /// `Message`.
 ///
-/// # Example
+/// # Examples
 ///
 /// This example shows how to modify packets in PacketPile using [`pathspec`]s.
 ///
@@ -229,7 +229,7 @@ impl PacketPile {
     /// Note: there is no packet at the root.  Thus, the path `[]`
     /// returns None.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// # use sequoia_openpgp as openpgp;
@@ -284,7 +284,7 @@ impl PacketPile {
     ///
     /// See the description of the `path_spec` for more details.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// # use sequoia_openpgp as openpgp;
@@ -345,7 +345,7 @@ impl PacketPile {
     /// If the path was invalid, then `Error::IndexOutOfRange` is
     /// returned instead.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// # use sequoia_openpgp as openpgp;
diff --git a/openpgp/src/serialize/cert.rs b/openpgp/src/serialize/cert.rs
index 177f9b8b..10831123 100644
--- a/openpgp/src/serialize/cert.rs
+++ b/openpgp/src/serialize/cert.rs
@@ -300,7 +300,7 @@ impl Cert {
 /// [`Cert`]: ../cert/struct.Cert.html
 /// [`Cert::as_tsk()`]: ../cert/struct.Cert.html#method.as_tsk
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// # use sequoia_openpgp::{*, cert::*, parse::Parse, serialize::Serialize};
@@ -336,7 +336,7 @@ impl<'a> TSK<'a> {
     ///
     /// Note that the given filter replaces any existing filter.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to create a TSK with a detached
     /// primary secret key.
@@ -393,7 +393,7 @@ impl<'a> TSK<'a> {
     ///   [`S2K`]: ../crypto/enum.S2K.html
     ///   [this test]: https://tests.sequoia-pgp.org/#Detached_primary_key
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This example demonstrates how to create a TSK with a detached
     /// primary secret key, serializing it using secret key stubs.
diff --git a/openpgp/src/serialize/cert_armored.rs b/openpgp/src/serialize/cert_armored.rs
index a7cf6040..58c53dae 100644
--- a/openpgp/src/serialize/cert_armored.rs
+++ b/openpgp/src/serialize/cert_armored.rs
@@ -66,7 +66,7 @@ impl Cert {
     /// the Cert's userids are added as comments, so that it is easier
     /// to identify the Cert when looking at the armored data.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use sequoia_openpgp as openpgp;
diff --git a/openpgp/src/serialize/stream.rs b/openpgp/src/serialize/stream.rs
index 1ad270d7..b5c4cce2 100644
--- a/openpgp/src/serialize/stream.rs
+++ b/openpgp/src/serialize/stream.rs
@@ -209,7 +209,7 @@ pub struct Message<'a>(writer::BoxStack<'a, Cookie>);
 impl<'a> Message<'a> {
     /// Starts streaming an OpenPGP message.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -238,7 +238,7 @@ impl<'a> Message<'a> {
     /// care.  If done improperly, the resulting message may be
     /// malformed.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// This demonstrates how to create a compressed, signed message
     /// from a detached signature.
@@ -296,7 +296,7 @@ impl<'a> Message<'a> {
     /// Failing to finalize the message may result in corrupted
     /// messages.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -537,7 +537,7 @@ pub struct ArbitraryWriter<'a> {
 impl<'a> ArbitraryWriter<'a> {
     /// Creates a new writer with the given tag.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -661,7 +661,7 @@ impl<'a> Signer<'a> {
     ///   [`Signer::detached`]: #method.detached
     ///   [`Signer::with_template`]: #method.with_template
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -750,7 +750,7 @@ impl<'a> Signer<'a> {
     ///   [`Signer::hash_algo`]: #method.hash_algo
     ///   [`Signer::add_intended_recipient`]: #method.add_intended_recipient
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -820,7 +820,7 @@ impl<'a> Signer<'a> {
     ///   [Section 11.4 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-11.4
     ///   [`LiteralWriter`]: ../struct.LiteralWriter.html
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -891,7 +891,7 @@ impl<'a> Signer<'a> {
     ///
     /// Can be used multiple times.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -943,7 +943,7 @@ impl<'a> Signer<'a> {
     ///
     ///   [*Surreptitious Forwarding*]: http://world.std.com/~dtd/sign_encrypt/sign_encrypt7.html
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -985,7 +985,7 @@ impl<'a> Signer<'a> {
 
     /// Sets the hash algorithm to use for the signatures.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -1027,7 +1027,7 @@ impl<'a> Signer<'a> {
     /// Note: it is up to the caller to make sure the signing keys are
     /// actually valid as of `time`.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -1083,7 +1083,7 @@ impl<'a> Signer<'a> {
     ///   [Section 11.3 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-11.3
     ///   [Section 11.4 of RFC 4880]: https://tools.ietf.org/html/rfc4880#section-11.4
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -1280,7 +1280,7 @@ pub struct LiteralWriter<'a> {
 impl<'a> LiteralWriter<'a> {
     /// Creates a new literal writer.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -1311,7 +1311,7 @@ impl<'a> LiteralWriter<'a> {
 
     /// Sets the data format.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// # f().unwrap(); fn f() -> sequoia_openpgp::Result<()> {
@@ -1344,7 +1344,7 @@ impl<'a> LiteralWriter<'a> {
     /// not be longer than 255 bytes.  Returns an error if the given
     /// name is longer than that.
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```