docs: purge never-compiled doc examples — compile, delete, or justify (#146)#147
Open
lxsaah wants to merge 1 commit into
Open
docs: purge never-compiled doc examples — compile, delete, or justify (#146)#147lxsaah wants to merge 1 commit into
lxsaah wants to merge 1 commit into
Conversation
…#146) Resolves the ignored-doctest debt from the post-036 scan with the revised policy (maintainer decision on #146): remove `rust,ignore` examples unless there is a good reason to keep one. Result: 108 ignored fences → 24, and every survivor carries an explicit "Illustrative (not compiled: …)" reason. - Converted to compiled doctests (`no_run`/`rust`) where the crate's deps allow it: the crate-level quick starts of aimdb-sync, aimdb-uds-connector, aimdb-websocket-connector, aimdb-mqtt-connector, aimdb-knx-connector, aimdb-persistence(+sqlite); core's producer/consumer module examples, TopicProvider, extensions, AimxConfig, RecordKey Hash-contract; the websocket AuthHandler and MQTT link-ext trait docs. ~30 examples now compile under `make test` (186 doctests passing suite-wide). - Conversion surfaced real rot, now fixed in the surviving examples: key-less `configure()`/`producer()`/`consumer()` calls (API takes a key), builder chains that can't compile (`&mut Self` → by-value `build()`), `with_buffer`/`finish()` on the wrong receiver, a deserializer returning `Box<T>` instead of `T`, sync's `AimDbSyncExt` example calling the async `build()` synchronously, and `DbError::RecordNotFound` vs `RecordKeyNotFound`. - Deleted ~50 method-level fragments that restated the signature (builder key-access helpers, registrar setters, connector constructors, internal SPI sketches) plus duplicates of the crate-level examples. - Kept 24 as `ignore`, each with a written reason: downstream-crate types core cannot depend on (adapter/connector wiring, `.buffer()` ext trait), proc-macro expansion targeting aimdb-core (circular dev-dependency), embedded/wasm-only code (Embassy peripherals, `#[wasm_bindgen]`), and macro grammar sketches with placeholder types. - Dev-deps: aimdb-uds-connector gains serde/serde_json for its quick start; aimdb-sync's example uses its existing aimdb-tokio-adapter dependency. Closes #146. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #146 with the revised policy (maintainer decision mid-work): instead of systematically converting every
rust,ignoreexample, remove them unless there is a good reason to keep one — and where the example is the crate's primary usage documentation and the dependencies allow it, convert it to a compiled doctest instead. Stacked on #145 (retarget down the stack as it merges).Result: 108 ignored fences → 24, every survivor carrying an explicit "Illustrative (not compiled: …)" reason inline. No API or behavior changes;
Cargo.tomlchanges are dev-deps only.Converted to compiled doctests (~30 examples, now CI-checked)
#[tokio::main]" flagship), uds/websocket/mqtt/knx connectors, persistence + sqlite backend.typed_api),TopicProvider, extensions storage,AimxConfig::socket_permissions, theRecordKeyHash/Borrow contract snippet, connector module example.with_qos/with_retainlink ext, websocketAuthHandler(bearer-token example), websocket server/client builder chains, data-contractslog_tap+MigrationStep.Rot the conversion surfaced and fixed
Key-less
configure()/producer()/consumer()calls (the API takes a key), builder chains that cannot compile (register_recordreturns&mut Self,build()takesself),.with_buffer()/.finish()on receivers that don't have them, a deserializer returningBox<T>instead ofT,AimDbSyncExt's example calling the asyncbuild()synchronously,DbError::RecordNotFoundvsRecordKeyNotFound, andsource+link_fromon one record (a build-time conflict) in the MQTT quick start.Deleted (~50 fragments)
Method-level examples that restated the signature: builder key-access helpers (
produce/subscribe/producer/consumer/resolve_key/…), registrar setters (source/tap/link_to/with_*), connector constructors, internal SPI sketches (RouterBuilder,JsonBufferReader, json access), and duplicates of crate-level examples.Kept as
ignore(24, each with a written reason).buffer()registrar ext trait) — e.g.with_connector's three-variant example,remotemodule usage, sans-io connector-author sketches.aimdb-derive: expansion targetsaimdb_core::RecordKey(circular dev-dependency); compiled integration tests live in aimdb-core.#[wasm_bindgen]factory.migration_chain!), pointing at compiled real usage.The three
buffer_sizedrecipe mini-fences in the Embassy adapter were folded into prose bullets — recipes preserved, no uncompiled code.Validation
make fmt-check✅make clippy(all feature combos,-D warnings) ✅make test✅ (186 doctests passing suite-wide)cargo test --docrun for every touched crate during conversion.🤖 Generated with Claude Code