Skip to content

Commit 48b9660

Browse files
committed
docs(stack-encrypt): address the review of the rustdoc rewrite
The derive crate's attribute reference, pulled into its rustdoc with include_str!, still named the API plan, so the guard now scans every file a doc attribute includes. It also flags an ADR that ends a line, whose number sits on the next one, and matches case-insensitively. The JSON module's docs compared the code with its plan; they now describe the behaviour, and the comparison is a maintainer comment. The query docs said a type answers with one query domain per operator; EQL v4 has one per type family and term, as the code binds it. A few more history phrases go, and the row-binding sentence says what naming the row costs. Refs #1598.
1 parent fb059e7 commit 48b9660

17 files changed

Lines changed: 162 additions & 80 deletions

File tree

‎packages/stack-encrypt-derive/docs/attributes.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,8 @@ field. Only this pair accepts `passthrough`.
1111

1212
`EncryptFrom` and `DecryptInto` are the older pair. They encrypt a borrowed
1313
plaintext, `&user`. The caller keeps the original, and must wipe it. Plans
14-
and the dynamic engine still use them. The API plan removes them once those
15-
have moved to the new pair.
14+
and the dynamic engine still use them. The older pair will be removed once
15+
plans and the dynamic engine use the new pair (#1488).
1616

1717
Derive one pair or the other on a record. `EncryptTarget` and
1818
`DecryptSource` already implement `EncryptFrom` and `DecryptInto` for the

‎packages/stack-encrypt-derive/src/lib.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,9 @@
1010
//!
1111
//! `EncryptFrom<P>` and `DecryptInto<P>` are an older pair of derives over a
1212
//! borrowed plaintext. They take the same attributes. Plans and the dynamic
13-
//! engine still use them, and they will be removed once those have moved to
14-
//! the new pair. See [Owned records](#owned-records).
13+
//! engine still use them. The older pair will be removed once plans and the
14+
//! dynamic engine use the new pair (#1488). See
15+
//! [Owned records](#owned-records).
1516
//!
1617
//! The generated code describes the encryption. Stack Encrypt runs it. The
1718
//! generated code is never given a cipher.

‎packages/stack-encrypt/CHANGELOG.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -343,8 +343,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
343343
- `vitaminc-aead-frame` is now always built, with its `serde` feature.
344344
Before, it was built only with the `dynamic` feature. The `dynamic`
345345
feature now adds no dependency.
346-
- The rustdoc states each rule itself and no longer names a design record
347-
or plan, which are not published with the crate.
346+
- The rustdoc of `stack-encrypt` and `stack-encrypt-derive` states each
347+
rule itself. It no longer names design records or plans, since those are
348+
not published with the crates.
348349

349350
### Deprecated
350351

@@ -360,6 +361,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
360361

361362
### Fixed
362363

364+
- The docs of `dynamic::read` said the engine never calls it. `dynamic::query_term`
365+
does: it reads a query's input as the field's kind.
363366
- **A refused context no longer drops a copy of the plaintext unwiped**
364367
(#1504). `target::ciphertext()` cloned a borrowed plaintext before it
365368
checked the context. When the context was too long for a ZeroKMS

‎packages/stack-encrypt/src/cipher.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -195,7 +195,7 @@ pub enum Error {
195195
/// Which row a value belongs to is not checked: an entry from another
196196
/// row of the same column at the same path, returned with that row's
197197
/// header, opens. A value is bound to its row only when its context
198-
/// names the row.
198+
/// names the row. Its selectors and terms are then that row's alone.
199199
///
200200
/// `expected` names what the read expected, never what the entry held.
201201
#[error("the database returned a JSON index entry other than {expected}")]

‎packages/stack-encrypt/src/dynamic/kind.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,8 +165,9 @@ fn scalar_of(kind: ValueKind) -> Option<(Option<Logical>, Physical<'static>)> {
165165
/// with [`FieldPlan::field_type`](super::FieldPlan::field_type). One that
166166
/// skips it hands `Float64(34.0)` to a `uint64` field, derives a float term
167167
/// where the stored one is the `u64` term, and matches nothing, with no
168-
/// error. [`query_term`](super::query_term) does call it: a query named by
169-
/// operator reads its input as the field's kind.
168+
/// error. [`query_term`](super::query_term) does call it, for a non-null
169+
/// input to any operator but a document's: a query named by operator reads
170+
/// its input as the field's kind.
170171
///
171172
/// ```
172173
/// use stack_encrypt::dynamic::{read, ValueFrame, ValueKind};

‎packages/stack-encrypt/src/dynamic/mod.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -680,7 +680,7 @@ reasons! {
680680
NullPassthrough => "null_passthrough", r#"a passthrough carries a null as it is, and takes no "null""#;
681681
/// A field with `"null": "sealed"` derives a term other than
682682
/// equality's, or names an EQL type that carries one: a null has an
683-
/// equality term and no other (#1298), so its absence would show in
683+
/// equality term and no other, so its absence would show in
684684
/// that term's column.
685685
SealedNullIndex => "sealed_null_index", r#"a null has an equality term and no other, so a field with another index takes "null": "sql""#;
686686
/// A field with `"null": "sealed"` declares no type, or one of no

‎packages/stack-encrypt/src/dynamic/query.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@
5050
//! [`TargetDescriptor::operators`] lists: the operators of a single value
5151
//! whose index the type carries, for a type the engine produces and that
5252
//! has a query twin. The term is the twin, which carries every term of the
53-
//! type; one query domain per operator is EQL v4's.
53+
//! type. It binds as the twin's one query domain
54+
//! ([`TargetDescriptor::query_sql_domain`]), whichever operator it answers:
55+
//! EQL v4 has one query domain per type family and term, not per operator.
5456
//! `matches` is answered through a type whose descriptor carries its match
5557
//! options ([`TargetDescriptor::with_match_options`]), since [`verify`]
5658
//! must cut the query's tokens as the stored filter was cut: `TextMatch`

‎packages/stack-encrypt/src/dynamic/record.rs‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,9 +53,8 @@
5353
//! key is requested. A stored context changed in storage opens nothing
5454
//! either way: every field was sealed under the original. The key
5555
//! `"context_field"` is reserved at the top level of a plan, so no field
56-
//! may be called that. A plan without the key is read exactly as before:
57-
//! the two-segment and shared-prefix rules hold, and it seals the same
58-
//! bytes.
56+
//! may be called that. Without the key, a plan follows the two-segment and
57+
//! shared-prefix rules.
5958
//!
6059
//! # A field that names an EQL type
6160
//!

‎packages/stack-encrypt/src/dynamic/target.rs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
//!
33
//! A data plan field may name an EQL type instead of its outputs
44
//! (`{"target": "TextEq", "context": [...]}`; see [`record::plan`]). The
5-
//! engine knows no EQL type — `eql-bindings` depends on this crate, so this
6-
//! crate cannot depend on it — so the dispatch that resolves the name is in
7-
//! the guest build that holds the EQL types. This module is the seam: a
5+
//! engine knows no EQL type: `eql-bindings` depends on this crate, so this
6+
//! crate cannot depend on it. A host that has the EQL types resolves the
7+
//! name, as the Go guest's EQL build does. This module is the seam: a
88
//! [`TargetResolver`] the host installs, which the lowering calls once per
9-
//! target field, and [`NoTargets`], the
10-
//! resolver of a build without EQL types, which refuses every name.
9+
//! target field, and [`NoTargets`], the resolver of a build without EQL
10+
//! types, which refuses every name.
1111
//!
1212
//! The resolver runs the named type's own plan (its `EncryptFrom` /
1313
//! `DecryptInto`) and hands back the engine's [`Pending`], so a target field

‎packages/stack-encrypt/src/dynamic/term.rs‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,8 @@ use crate::{Encrypt, IntoPrfContext, KeysetCipher, NonEmpty};
9797
///
9898
/// Serialized (it is `Serialize`), an index writes the string whenever the
9999
/// options are the defaults and the object otherwise, with every option but
100-
/// `short_words`, which it writes only when it is on. So a default plan is
101-
/// byte-for-byte what it was before options had a wire form, and a plan with
102-
/// other options is what it was before `short_words` existed.
100+
/// `short_words`, which it writes only when it is on. So a plan with
101+
/// default options writes each index as its bare key.
103102
impl IndexSpec {
104103
/// The index a bare key names, under default options, or `None` for a
105104
/// string that is not an index key.

0 commit comments

Comments
 (0)