Turn ignored doctests on Database into real doctests #29

Open
opened 2026-10-26 15:49:19 +00:00 by NoctisWolfshadow · 0 comments
Owner

Problem

The examples on Database::connect, transaction, execute and execute_batch in src/database/connection.rs are marked ```ignore, so rustdoc never compiles them. If the API changes, the docs can silently go stale.

Proposal

Replace ignore with real doctests. Build the database from Config::memory() and hide the setup lines with #, so the rendered docs only show the example itself.

/// ```
/// # use tessera_orm::{Config, Database};
/// # let mut db = Database::connect(Config::memory())?;
/// # db.execute_batch("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")?;
/// # db.execute("INSERT INTO users (id, name) VALUES (1, 'Alice')", [])?;
/// let changed = db.execute(
///     "UPDATE users SET name = ?1 WHERE id = ?2",
///     ("Bob", 1),
/// )?;
/// assert_eq!(changed, 1);
/// # Ok::<(), tessera_orm::Error>(())
/// ```

Tasks

  • Database::connect
  • Database::transaction
  • Database::execute
  • Database::execute_batch

Done when

  • cargo test --doc runs all four examples with 0 ignored.
  • Rendered docs show no # setup lines.
## Problem The examples on `Database::connect`, `transaction`, `execute` and `execute_batch` in `src/database/connection.rs` are marked ```` ```ignore ````, so rustdoc never compiles them. If the API changes, the docs can silently go stale. ## Proposal Replace `ignore` with real doctests. Build the database from `Config::memory()` and hide the setup lines with `#`, so the rendered docs only show the example itself. ```rust /// ``` /// # use tessera_orm::{Config, Database}; /// # let mut db = Database::connect(Config::memory())?; /// # db.execute_batch("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")?; /// # db.execute("INSERT INTO users (id, name) VALUES (1, 'Alice')", [])?; /// let changed = db.execute( /// "UPDATE users SET name = ?1 WHERE id = ?2", /// ("Bob", 1), /// )?; /// assert_eq!(changed, 1); /// # Ok::<(), tessera_orm::Error>(()) /// ``` ``` ## Tasks - [ ] `Database::connect` - [ ] `Database::transaction` - [ ] `Database::execute` - [ ] `Database::execute_batch` ## Done when - `cargo test --doc` runs all four examples with 0 ignored. - Rendered docs show no `#` setup lines.
Sign in to join this conversation.
No description provided.