diff options
Diffstat (limited to 'docs/dev')
| -rw-r--r-- | docs/dev/pages/abouts/ci.md | 29 | ||||
| -rw-r--r-- | docs/dev/pages/issues/0.5.0-roadmap.md | 25 |
2 files changed, 44 insertions, 10 deletions
diff --git a/docs/dev/pages/abouts/ci.md b/docs/dev/pages/abouts/ci.md index a9be500..9f638d7 100644 --- a/docs/dev/pages/abouts/ci.md +++ b/docs/dev/pages/abouts/ci.md @@ -26,16 +26,16 @@ cargo ci Every CI step is an independent switch (`--check-*`). Running `cargo ci` with no options executes **all** steps in the order below; pass one or more `--check-*` flags to run only the selected steps. -| Step | Flag | What it does | -| --------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| Build | `--check-build` | Recursively finds all `Cargo.toml` files and runs `cargo build` for each crate in parallel (workspace members build with all documented features). | -| Clippy | `--check-clippy` | Runs `cargo clippy ... -- -D warnings` for every crate in parallel; any warning fails the check. | -| Test | `--check-test` | Runs `cargo test` for every crate in parallel (workspace tests run with all documented features; `arg-picker` is excluded). | -| Arg picker | `--check-arg-picker` | Runs `cargo test -p arg-picker` with its default features. | -| Markdown code | `--check-markdown-code` | Runs the `test-all-markdown-code` tool to verify code blocks in all `*.md` files compile. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md). | -| Examples | `--check-examples` | Runs the `test-examples` tool to verify all examples behave as expected. | -| Docs up to date | `--check-docs-refresh` | Runs the documentation refresh tools and `cargo fmt`, then fails if the working tree is no longer clean (i.e. the docs were stale). | -| API docs | `--check-api-docs` | Builds API docs with the `[package.metadata.docs.rs]` features and fails if `docs/api-docs/` is out of date. | +| Step | Flag | What it does | +| --------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Build | `--check-build` | Recursively finds all `Cargo.toml` files and runs `cargo build` for each crate in parallel (workspace members build with all documented features). | +| Clippy | `--check-clippy` | Runs `cargo clippy ... -- -D warnings` for every crate in parallel; any warning fails the check. | +| Test | `--check-test` | Runs `cargo test` for every crate in parallel (workspace tests run with all documented features; `arg-picker` is excluded). | +| Arg picker | `--check-arg-picker` | Runs `cargo test -p arg-picker` with its default features. | +| Markdown code | `--check-markdown-code` | Runs the `test-all-markdown-code` tool to verify code blocks in all `*.md` files compile. See [ABOUT_CODE_VERIFY](docs/_ABOUT_CODE_VERIFY.md). | +| Examples | `--check-examples` | Runs the `test-examples` tool to verify all examples behave as expected. Each example declares its expected output tests in `examples/<example>/test.toml`. | +| Docs up to date | `--check-docs-refresh` | Runs the documentation refresh tools and `cargo fmt`, then fails if the working tree is no longer clean (i.e. the docs were stale). | +| API docs | `--check-api-docs` | Builds API docs with the `[package.metadata.docs.rs]` features and fails if `docs/api-docs/` is out of date. | ### Docs up to date in detail @@ -49,6 +49,15 @@ Every CI step is an independent switch (`--check-*`). Running `cargo ci` with no Finally, it runs `cargo fmt` to unify code formatting. Because the refresh tools regenerate derived files, running this check against stale documentation modifies the working tree — and `ci.rs` fails the run in that case. (Using `--dirty` skips the cleanliness check, which makes this flag behave like a plain "refresh docs" command.) +### Examples in detail + +`--check-examples` runs the `test-examples` tool in two phases: + +1. **Build** — every example that has a `test.toml` is built in parallel (one `cargo build` task per example, reusing the shared `.temp/target` cache). +2. **Test** — each `[[runs]]` entry in `examples/*/test.toml` is executed serially against the pre-built binary, asserting the CLI arguments (`input`) and the expected `exit-code` / `result`. + +An example that changes its behavior only needs its own `test.toml` updated. + ### Combining steps When several `--check-*` flags are combined, the steps run in the order listed above. In "run all" mode (no flags given), the documentation steps all execute even if one of them fails, so every problem is reported in a single run. diff --git a/docs/dev/pages/issues/0.5.0-roadmap.md b/docs/dev/pages/issues/0.5.0-roadmap.md index 0312193..5238cae 100644 --- a/docs/dev/pages/issues/0.5.0-roadmap.md +++ b/docs/dev/pages/issues/0.5.0-roadmap.md @@ -108,6 +108,31 @@ version = "0.4.0" features = [ "build", "pathf" ] # No `dispatch_tree` feature; `pathf` no longer needs to consider its branches ``` +8. **Feature:** A new macro designed for `pathf`: `#[pathf_export(type::TypePath)]` + +`pathf` has been around since 0.2.0 and has worked well for a long time, with many edge cases resolved. However, it still lacks an escape hatch — "when certain indirect expansions cannot be recognized by `pathf`, how can we assist its inference?" + +I plan to introduce a new attribute macro to supplement `pathf`'s path inference. + +```rust +#[macro_export] +macro_rules! repack { + ($name:ident) => { + // Ignored! This section cannot be parsed by pathf. + #[mingling::macros::pathf_ignore] + #[derive(mingling::Grouped)] + pub struct $name; + }; +} + +// The expansion contains macros that need to be parsed by pathf +#[pathf_export(MyType)] // Explicitly specified to assist pathf's inference +repack!(MyType); +``` + +> [!Note] +> Haha, hopefully we'll never have to use it. + <p align="center" style="font-size: 0.85em; color: gray;"> Written by @Weicao-CatilGrass </p> |