| 1 | # Examples |
| 2 | |
| 3 | Examples are optional. Keep or add one only for behavior not evident from the |
| 4 | signature, meaningful composition, or useful inference or narrowing. Replace |
| 5 | or remove examples that are trivial, misleading, contrived, or |
| 6 | scaffolding-heavy. |
| 7 | |
| 8 | Use `**Example** (Unique use-case title)`, optional prose, and exactly one |
| 9 | non-empty `ts` fence. Titles must remain unique after trimming and lowercasing. |
| 10 | |
| 11 | Read `packages/tools/doctest/README.md` for runnable-fence and inline-assertion |
| 12 | syntax. Additionally: |
| 13 | |
| 14 | - Use public imports and arrange nontrivial examples as setup, operation, then |
| 15 | semantic observation. |
| 16 | - The transform does not run Effects or await promises automatically. Prefer |
| 17 | awaited `Effect.runPromise`; use `Effect.runSync` only when synchronous |
| 18 | execution is the documented contract. |
| 19 | - Keep type-level examples marked without tautological runtime assertions. |
| 20 | - Leave examples that register tests and intentionally non-executable examples |
| 21 | as plain `ts` fences. |
| 22 | - Use `Ref`, `Deferred`, or `Queue` rather than mutable probes for concurrency, |
| 23 | interruption, or races. |
| 24 | |
| 25 | If example research suggests an implementation or type bug, report it instead |
| 26 | of changing runtime code during a documentation-only pass. |