akiomik / akiomik/tears

subscription::http is compiled in a configuration where its own API is not

Aperta
#401 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
documentation
Lingua principale
Rust
Stelle
9
Fork
1
Merge medio
11h 46m
PR unite (30g)
62

Descrizione

## What

`subscription::http` is compiled in a configuration where the API its own
documentation demonstrates does not exist.

The module is declared `#[cfg(any(feature = "http", all(feature = "loom-core",
test)))]` (#398). The second arm is there because `loom-core` reaches into the
module for one submodule, `cell_core`, the loom mirror of `http::cell`. Every
other item in the module — and everything the module's `# Example` imports:
`Query`, `QueryClient`, `Mutation`, `QueryResult`, `QueryError` — is
`#[cfg(feature = "http")]`.

So in the `loom-core` arm the module's documentation is present and the API it
shows is not.

## Why it does not bite today, and why that is not a guarantee

The arm is reached by `cargo test --lib --features loom-core`, which the three
loom recipes run and which collects no doctests. The doctest pass under
`--features loom-core` does not collect the module at all — measured, and #398
relies on that measurement rather than on an explanation, because there is
none: `signal`'s gate is built on the same `all(feature = "loom-core", test)`
sub-expression and reads the other way in the same run (#298).

A defect resting on an unexplained behaviour is a defect waiting for that
behaviour to change. Before #398 the same module was reached with `http` off in
a run that *did* collect its example, and the result was the `E0432` that commit
fixes.

## Why it is filed rather than fixed

Three shapes, each with a cost that is more than this observation settles:

- **Wrap the example in `#![cfg_attr(feature = "http", doc = "…")]`.** Correct
by construction, and `CONTRIBUTING.md` names the pair for exactly this. It is
one `doc = "…"` per line for a whole `Application`, so the crate's principal
HTTP example becomes seventy string literals in the source.
- **Narrow the gate to `feature = "http"` and declare `cell_core` elsewhere.**
Removes the arm and the question with it. `cell_core`'s own documentation
links `super::cell::Cell` and `super::query`, so it would have to be declared
through a `#[path]` from another module and have those links rewritten to a
private path that does not exist in the configuration it is compiled in;
`ci.yml` names `subscription::http::cell_core` in two comments.
- **Move the example onto a gated item.** `query.rs` and `mutation.rs` are
`#[cfg(feature = "http")]`, so an example there is compiled exactly when the
API is. It costs the module page its overview, which is the page a reader
arriving at `subscription::http` lands on.

Raised in review of #398, which narrowed the gate as far as it could without
answering this.

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.