doctest-conventions

Doctest Conventions

Philosophy: documentation that cannot rot

Every rustdoc example is compile-checked on every cargo test --doc (pre-commit and CI). Browser automation can't execute in a doctest harness, so examples are compiled but not run — same contract as the agent-doc snippets (verify-agent-docs) and landing-page snippets (verify-site-snippets).

The annotation: no_run

no_run  — compiled every time, never executed.  ← use this
ignore  — never compiled, never executed; rustdoc only highlights it.
(none)  — compiled AND executed; only for pure, browser-free examples.

Use ```no_run for anything that would launch a browser or talk to the Playwright server. Plain ```rust is fine for pure logic (selector builders, option construction) that can really execute.

Never use ```ignore except when the code genuinely cannot compile in this crate — the only sanctioned case is the macros/trace crates' module docs showing downstream playwright-rs usage, which would need a cyclic dev-dependency to compile.

History. Until 2026-06, the convention was ignore + a CI step running cargo test --doc -- --ignored, believed to execute them. It never did: rustdoc surfaces ignore blocks as empty always-pass stubs (83 "passed" in 0.00s). The examples had zero protection and ~10 had silently rotted. no_run is what the convention always intended.

Structure

Prefer one comprehensive module-level doctest (//!) per protocol file, demonstrating related APIs in a realistic scenario. Per-function examples are allowed where they pull their weight — they must compile like everything else.

Use hidden scaffolding lines (# -prefixed) so the rendered docs show only the instructive lines while the compiler sees a complete program:

/// # Example
///
/// ```no_run
/// # use playwright_rs::Playwright;
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// # let pw = Playwright::launch().await?;
/// # let page = pw.chromium().launch().await?.new_page().await?;
/// page.goto("https://example.com", None).await?;
/// let title = page.title().await?;
/// # Ok(())
/// # }
/// ```