docs(stack-encrypt): rewrite the ExpectedContext docs in plain language

The docs that this change added now say who passes what, and what the
record checks, in short sentences. The JSON document's decrypt docs
list the two cases a caller has.

Author: coderdan

packages/eql/crates/eql-bindings/src/v4/json_tree.rs

@@ -514,10 +514,13 @@ impl EncryptFrom<Value> for JsonTreeDocument {
     }
 }
 
-/// Opens to the plaintext document, under the stored identifier. A caller
-/// that passes the column it expects, as a `NonEmpty<Identifier>`, has the
-/// stored identifier checked against it before any key is requested. A
-/// caller that passes nothing opens under the stored identifier unchecked.
+/// Decrypts to the plaintext document, under the stored identifier.
+///
+/// - If you pass the column you expect, as a `NonEmpty<Identifier>`, the
+///   stored identifier must equal it. The check runs before any key is
+///   requested.
+/// - If you pass nothing, the document decrypts under the stored
+///   identifier, without that check.
 impl DecryptInto<Value> for JsonTreeDocument {
     type Context = ExpectedContext<Identifier>;
     fn decryption<K: 'static>(self, context: Self::Context) -> Decryption<Value, K> {

packages/stack-encrypt/src/target/context.rs

@@ -861,10 +861,11 @@ impl DeclaredContext {
 /// descriptor is HMAC'd into the tag, so altering a stored identifier makes
 /// the retrieve fail rather than succeed, and nobody reaches a key they are
 /// not entitled to. See ADR-0004.
-// Hidden here, on the definition, and not only on the re-export. rustc
-// reads this attribute when it lists the types that implement a trait in a
-// compile error, and rustdoc reads it when another crate's docs name the
-// type. On the re-export alone, the type still showed in both.
+// `#[doc(hidden)]` must be on this definition, and not only on the
+// re-export. rustc reads the attribute here when a compile error lists the
+// types that implement a trait. rustdoc reads it here when the docs of
+// another crate name the type. With the attribute on the re-export alone,
+// both still showed the type.
 #[doc(hidden)]
 #[derive(Clone, Debug)]
 pub struct ExpectedContext<T>(Option<NonEmpty<T>>);

packages/stack-encrypt/src/target/mod.rs

@@ -184,10 +184,12 @@ pub mod transcode;
 mod tuples;
 
 pub(crate) use self::core::{bind_pending, seal_pending};
-/// The check a `#[stash(context_field)]` record runs on decrypt. It is not
-/// part of the API: the derives and the EQL types name it, and a caller
-/// passes a `NonEmpty<T>` or nothing. It is public only so that code the
-/// derives emit in another crate can name it. The definition is hidden too.
+/// The check that a `#[stash(context_field)]` record runs on decrypt.
+///
+/// `ExpectedContext` is not part of the API. Only the derives and the EQL
+/// types name it, and a caller passes a `NonEmpty<T>` or nothing. The type
+/// is public only because the derives emit code in other crates that
+/// names it. The definition is hidden too.
 #[doc(hidden)]
 pub use context::ExpectedContext;
 pub use context::{

packages/stack-encrypt/src/target/operations.rs

@@ -66,9 +66,9 @@ pub trait EncryptFrom<S>: Sized + 'static {
 /// ciphertext and its context, and [`open`] describes the rest. A query-only
 /// target (terms alone) has no implementation.
 pub trait DecryptInto<P>: Sized {
-    /// What a caller supplies to open the target. A record that stores its
-    /// context converts from `()` or from the `NonEmpty<T>` the caller
-    /// believes it is opening.
+    /// The context that a caller passes to decrypt the target. For a
+    /// record that stores its context, the caller passes `()`, or the
+    /// `NonEmpty<T>` that the caller expects the record to store.
     type Context;
     /// The description the cipher executes to recover `P`.
     fn decryption<K: 'static>(self, context: Self::Context) -> Decryption<P, K>;