[ci] Run doctests too.

See rust-lang/cargo#6669

.cargo/config.toml

@@ -18,13 +18,15 @@ watch --clear
     -x ofl-fmt-project
     -x clippy-core
     -x test-core
+    -x test-core-doc
     -x docs-clean
     -x docs-all
 """
 
 bench-core = "bench --all-targets --package illicit --package moxie --package topo"
 clippy-core = "clippy --package illicit --package moxie --package topo --package topo-macro"
 test-core = "test --all-targets --package illicit --package moxie --package topo --package topo-macro"
+test-core-doc = "test --doc --package illicit --package moxie --package topo --package topo-macro"
 
 docs-all = "doc --workspace --no-deps --all-features"
 docs-clean = "clean --doc"
@@ -37,6 +39,7 @@ build-times = "build --workspace --all-targets --all-features -Z timings"
 dom-flow = """
 watch --clear
     -x test-dom
+    -x test-dom-doc
     -x test-augdom
     -x test-dom-lib-browser
     -x test-dom-drivertest
@@ -64,6 +67,7 @@ test-dom-todo = "wa-test dom/examples/todo"
 
 # standalones
 test-dom = "test --package moxie-dom --package ssr-poc --all-targets"
+test-dom-doc = "test --package moxie-dom --package ssr-poc --doc"
 
 # dom utilities
 clippy-dom = """clippy

.github/workflows/main.yml

@@ -68,7 +68,9 @@ jobs:
       env:
         CARGO_TARGET_DIR: target/
     - run: bin/ofl coverage collect test-core
+    - run: bin/ofl coverage collect test-core-doc
     - run: bin/ofl coverage collect test-dom
+    - run: bin/ofl coverage collect test-dom-doc
     - run: bin/ofl coverage report
 
     - uses: codecov/codecov-action@v1

illicit/Cargo.toml

@@ -13,6 +13,7 @@ owning_ref = "0.4"
 scopeguard = "1"
 
 [dev-dependencies]
+assert-panic = "1.0.1"
 criterion = "0.3"
 
 [[bench]]

illicit/src/lib.rs

@@ -13,23 +13,35 @@
 //!     num + 1
 //! }
 //!
-//! illicit::Layer::new().with(1u8).enter(|| {
+//! illicit::Layer::new().offer(1u8).enter(|| {
 //!     assert_eq!(env_num_plus_one(), 2u8);
+//!
+//!     illicit::Layer::new().offer(7u8).enter(|| {
+//!         assert_eq!(env_num_plus_one(), 8u8);
+//!     });
 //! });
 //! ```
 //!
-//! This provides convenient sugar for values stored in the current `Env` as an
-//! alternative to thread-locals or a manually propagated context object.
+//! Here, both calls see a `u8` in their environment.
+//!
+//! # Caution
+//!
+//! This provides convenient sugar for values stored in the current environment
+//! as an alternative to thread-locals or a manually propagated context object.
 //! However this approach incurs a significant cost in that the following code
 //! will panic without the right type having been added to the environment:
 //!
-//! ```should_panic
+//! ```
+//! # use assert_panic::assert_panic;
 //! # #[illicit::from_env(num: &u8)]
 //! # fn env_num_plus_one() -> u8 {
 //! #    num + 1
 //! # }
-//! // thread 'main' panicked at 'expected a value from the environment, found none'
-//! env_num_plus_one();
+//! assert_panic!(
+//!     { env_num_plus_one(); },
+//!     String,
+//!     starts with "expected a `u8` from the environment",
+//! );
 //! ```
 //!
 //! See the attribute's documentation for more details, and please consider
@@ -118,13 +130,12 @@ pub fn hide<E: 'static>() {
     })
 }
 
-/// Immutable environment container for the current scope. Environment values
-/// can be provided by parent environments, but child functions can only mutate
-/// their environment through interior mutability.
+/// A pending addition to the local environment.
 ///
-/// The environment is type-indexed, and each `Scope` holds 0-1 references to
-/// every `[std::any::Any] + 'static` type. Access is provided through read-only
-/// references.
+/// The environment is type-indexed, and access is provided through read-only
+/// references. Call [`Layer::offer`] to include new values in the environment
+/// for called functions and [`get`] or [`expect`] to retrieve references to the
+/// offered values.
 ///
 /// Aside: one interesting implication of the above is the ability to define
 /// "private scoped global values" which are private to functions which are
@@ -189,7 +200,7 @@ impl Layer {
         (self.location.file(), self.location.line(), self.location.column())
     }
 
-    /// Call `child_fn` with this environment as the current scope.
+    /// Call `child_fn` with this layer added to the environment.
     pub fn enter<R>(self, child_fn: impl FnOnce() -> R) -> R {
         let _reset_when_done_please = CURRENT_SCOPE.with(|parent| {
             let mut parent = parent.borrow_mut();

src/runtime.rs

@@ -60,7 +60,7 @@ impl std::fmt::Debug for Revision {
 /// state variables which might require mutation wakeups.
 ///
 /// ```
-/// # use moxie::embed::{Revision, Runtime};
+/// # use moxie::runtime::{Revision, Runtime};
 /// let mut rt = Runtime::new();
 /// assert_eq!(rt.revision().0, 0);
 /// for i in 1..10 {

topo/src/lib.rs

@@ -96,12 +96,12 @@ where
 /// ```
 /// // a call to root() here ensures the child is always treated as the same tree
 /// // no matter from where the function is called
-/// let independent = || root(Id::current);
-/// assert_eq!(call(independent), call(independent));
+/// let independent = || topo::root(topo::Id::current);
+/// assert_eq!(topo::call(independent), topo::call(independent));
 ///
 /// // this is a normal topo call, it returns `Id`s based on the parent state
-/// let dependent = || call(Id::current);
-/// assert_ne!(call(dependent), call(dependent));
+/// let dependent = || topo::call(topo::Id::current);
+/// assert_ne!(topo::call(dependent), topo::call(dependent));
 /// ```
 pub fn root<F, R>(op: F) -> R
 where