docs: make the docs.rs reference usable

[JosteinGj]

The rendered API reference opened with about forty lines of raw pub use and no prose at all — nothing saying what the crate is or how to make one call. 19 of 23 modules rendered as a bare name with no description. 34 public types had none either, including DataWrapper, ResponseError, Event, TimeSeries and every service struct.

Judge this by building it rather than by the diff:

cargo doc --no-deps --all-features --open

What changed

A landing page. What the crate is, a runnable create_api_service() example, a table mapping each ApiService field to its module, then the four things a caller hits immediately: the DataWrapper envelope, id-or-externalId, ResponseError and its problem document, and the list/filter/search split.

blocking was absent from docs.rs entirely. With no [package.metadata.docs.rs], docs.rs builds default-features-only — so the README pointed callers at a client the reference never showed. Now all-features = true, and the blocking module doc states up front that it needs the feature, with the Cargo.toml line. (A doc_cfg badge would do the same but needs nightly, so it was left out.)

Every module and every public type described. Service structs get a one-liner pointing at their module doc; entity types carry the fact that is not guessable from the field list — an Event is keyed by UUID and its externalId is deliberately not unique, a TimeSeries value_type is fixed at creation, FileUpload::new panics on an unreadable path.

Plumbing hidden, as one group so no survivor is left referencing a hidden name: ApiServiceProvider, DataWrapperDeserialization, process_response, serde_helper. doc(hidden) rather than pub(crate) — the id-as-string serde adapters are legitimately reusable by a downstream type's own #[serde(with = …)], and hiding does not restrict. GraphNode and Identifiable stay visible on purpose: both appear as bounds in public signatures, where hiding renders them as unclickable bare names.

The 28 remaining service methods documented — datasets.create, events.filter, files.upload_file, timeseries.retrieve_datapoints, the whole units service. Builder setters and field getters are deliberately left alone: a line on set_name saying it sets the name is noise, and there are several hundred.

Four doc comments were contradicting the api

Found while drafting, each checked against the backend source:

• labels::get said a miss returns empty items. It is a 404.
• EdgeProxy claimed it is returned from GET /functions, which answers RelatedNode and never populates it.
• TimeSeries::value_type said graph reads do not carry it. They do now.
• the subscriptions module is not "CRUD" — there is no update and no get.

labels::delete's documented 400 was checked and left alone: it really is a 400 with fields, not the 409 would-strand that resources and edges answer with. Generalising there would have introduced an error.

CI now runs the doctests

cargo test --no-run does not build doctests at all, so the landing-page example was never compile-checked.

The existing crate job now also runs cargo test --doc, and only that — every other test in this crate needs a live backend, which CI cannot reach. The doctests are the documentation's own examples and are pure construction; confirmed passing with BASE_URL pointed at a dead address and no credentials in the environment.

Numbers

Rustdoc coverage 33.8% → 41.8% (+87 items), zero rustdoc warnings, 248 tests and 7 doctests green.

The 644 still-undocumented items are overwhelmingly builder setters and struct fields. A coverage ratchet was considered and deliberately left out.

---

Stack, 5 of 5 — based on #148.

Two things this does not do, both deliberate:

• The three glob re-exports (pub use resources::*, events::*, timeseries::*) stay. They do duplicate items between the crate root and their modules, but removing them breaks use intellistream_datahub_sdk::TimeSeries for every existing caller — that belongs in a release, not a docs pass.
• Nothing here reaches docs.rs until a tag is pushed. v0.2.0 is still the only one, so the published reference predates the filter refactor, the assets service and the Node type.

Unrelated bug found, not fixed here: GraphDataWrapper::set_http_status_code is pub fn set_http_status_code(&mut self, _status_code: u16) {} — argument discarded, empty body. It is called on both parse paths, so a normal 200 from resources.create, update or edges.by_ids comes back with http_status_code: None. DataWrapper's version stores correctly, so the two wrappers disagree. That is a behaviour fix and wants its own PR.

🤖 Generated with Claude Code