Skip to content

net-api polish: self-contained docs + compose lock-in tests + must_use on wrap() #122

Description

@NotAProfDev

Summary

Follow-up polish to oath-adapter-net-api after the #121 vocabulary rename. Three
related improvements, all in the kernel crate. No behaviour change.

1. Self-contained public docs (no ADR citations)

Public rustdoc should explain the API on its own, not send the reader to an internal
ADR. Remove the (ADR-0029 §N) citations from the crate's docs and inline any reasoning
they carried:

  • compose.rs module doc (§3)
  • lib.rs module doc (the "cut is clean" signal; §2)
  • timer.rs (§4)

2. Lock-in tests for compose.rs

The module's central promise — the ordering invariant ("first .layer() is outermost")
— is currently only compile-checked by assert-nothing doctests. Add a #[cfg(test)]
module that executes and asserts:

  • outermost-first execution order (layers record their invocation order observably)
  • Identity passes the value through unchanged
  • Default == new()
  • the zero-cost property (size_of::<LayerBuilder<Identity>>() == 0; a stack of ZST
    layers is still a ZST)

3. #[must_use] on LayerBuilder::wrap()

Discarding the composed value (builder.wrap(leaf);) means assembling a stack and
throwing it away — a bug. Matches the existing #[must_use] on layer() / new().

Scope

oath-adapter-net-api only. Pre-release, workspace-internal.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions