From d8bc9ff75e76992592b065c41d2e433c0de9b72c Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Tue, 23 Jun 2026 21:19:01 +0800
Subject: Rename internal docs

---
 docs/_ABOUT_CODE_VERIFY.md | 195 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 195 insertions(+)
 create mode 100644 docs/_ABOUT_CODE_VERIFY.md

(limited to 'docs/_ABOUT_CODE_VERIFY.md')

diff --git a/docs/_ABOUT_CODE_VERIFY.md b/docs/_ABOUT_CODE_VERIFY.md
new file mode 100644
index 0000000..e28f59d
--- /dev/null
+++ b/docs/_ABOUT_CODE_VERIFY.md
@@ -0,0 +1,195 @@
+# Doc Code Block Verification System
+
+This system automatically extracts and compiles Rust code blocks from docs, ensuring all example code stays usable in CI.
+
+## Config
+
+Specify which Markdown files to verify via [`verified-docs.toml`](https://github.com/mingling-rs/mingling/blob/main/verified-docs.toml) in the project root.
+
+You can also test a single file via command-line arg:
+
+```sh
+./run-tools.sh test-all-markdown-code docs/pages/1-getting-started.md
+```
+ 
+```powershell
+.\run-tools.ps1 test-all-markdown-code docs/pages/1-getting-started.md
+```
+ 
+## Default Rules
+
+Every verified ` ```rust ` code block gets the following injected automatically at compile time — no need to write them explicitly in the block:
+
+### 1. `#![allow(dead_code)]` and `#![allow(unused)]`
+
+Added at the top of the generated `main.rs` to suppress dead-code warnings from partial code snippets.
+
+### 2. `use mingling::prelude::*;`
+
+If the block already has `use mingling::prelude::*;`, it won't be inserted again.
+
+Otherwise it's inserted automatically (with `#[allow(unused_imports)]`).
+
+### 3. `fn main() {}`
+
+If the block **does not contain** a `fn main` definition, an empty `fn main() {}` is appended,
+
+so the block can compile as a standalone binary project.
+
+### 4. `mingling::macros::gen_program!();`
+
+If the block **does not contain** a `gen_program!()` call,
+
+`mingling::macros::gen_program!();` is appended automatically.
+
+This call is required by the mingling framework.
+
+### 5. Build Cache Dedup — Shared Dep Hash
+
+Code blocks with the same `Features` and `Dependencies` are automatically grouped into the same compile group, sharing one `Cargo.toml` and build artifacts, avoiding redundant compilations.
+
+> [!NOTE]
+>
+> Hash input (all sorted):
+>
+> 1. Feature list
+> 2. External dep name list
+> 3. External dep version list
+> 4. `name=version` pairs
+>
+> Uses FNV-1a 64-bit hash, stable across runs.
+
+## Verification Steps
+
+After the **default rules** are applied, each block goes through:
+
+### 1. Block Extraction
+
+- Only ` ```rust ` fenced code blocks are extracted.
+- Empty blocks (no code lines) are skipped.
+- Blocks with `// NOT VERIFIED` alone are skipped.
+
+### 2. Temp Project Generation
+
+Each block (or each dedup-hash group) gets its own Cargo project:
+
+```
+.temp/doc-test/<hash>/
+├── Cargo.toml
+└── src/
+    └── main.rs
+```
+ 
+### 3. Build Verification
+
+Compiled with `cargo build --release`, stderr inherited to the terminal for real-time progress.
+
+- **Build OK** → **PASS**
+- **Build FAIL** → **FAIL**, last 20 lines of error captured.
+
+### 4. Report
+
+After all tests, a report is written to `.temp/DOCS-TEST-RESULT.md`, containing:
+
+- Total tests, passed, failed
+- Table of results per block (block #, file, line, status)
+- Detailed errors for failed blocks
+
+### 5. Exit Code
+
+- Any block fails → non-zero exit code (blocks CI pipeline).
+- All pass → zero exit code.
+
+---
+
+## Metadata Tag Rules
+
+At the start of a ` ```rust ` block (before code content), use these comment headers to declare metadata. Headers are parsed in order; everything after them is treated as code:
+
+### `// NOT VERIFIED`
+
+Marks the block **not to be compiled**. Use for illustrative snippets that can't compile on their own.
+
+```rust
+// NOT VERIFIED
+// This block is illustrative only, won't be compiled
+fn placeholder() {}
+```
+ 
+### `// Features: [...]`
+
+Declares the mingling crate features needed by this block, as a JSON string array. These features are written into `Cargo.toml`'s `[dependencies]`.
+
+```rust
+// Features: ["full", "serde"]
+```
+ 
+### `// Dependencies:`
+
+Declares external crate deps needed by the block. After `// Dependencies:`, each dep goes on one line: `// crate_name = "version"`.
+
+```rust
+// Dependencies:
+// serde = "1"
+// clap = "4"
+```
+ 
+> [!TIP]
+>
+> **Special handling**:
+>
+> For deps named `serde` or `clap` with a plain string version,
+>
+> `features = ["derive"]` is auto-added.
+>
+> If the version uses a TOML inline table (e.g. `{ version = "1", features = ["derive"] }`),
+>
+> it's kept as-is.
+
+---
+
+## Structure Overview
+
+| Module                                        | Responsibility                                                                      |
+| --------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `dev_tools/src/verify.rs`                     | Block parsing, Cargo.toml/main.rs generation, build exec, hash dedup, report output |
+| `dev_tools/src/bin/test-all-markdown-code.rs` | Entry point: read config, collect files, orchestrate tests, aggregate results       |
+| `verified-docs.toml`                          | Specifies which doc files to verify                                                 |
+
+---
+
+## Full Example
+
+````markdown
+```rust
+// Features: ["parser"]
+// Dependencies:
+// serde = "1"
+
+// Example code ...
+```
+````
+ 
+The above block compiles equivalently to:
+
+```rust
+#![allow(dead_code)]
+#![allow(unused)]
+ 
+#[allow(unused_imports)]
+use mingling::prelude::*;
+ 
+// Example code ...
+ 
+fn main() {}
+ 
+mingling::macros::gen_program!();
+```
+ 
+`Cargo.toml` will contain:
+
+```toml
+[dependencies]
+mingling = { path = "../../mingling", features = ["parser"] }
+serde = { version = "1", features = ["derive"] }
+```
-- 
cgit