Files
marqdo/doc/design/lib-code-as-docs.md
T
cflmyandCursor 53bc3538da docs(lib): narrate table/text/json as code-as-docs pilot
Add purpose lines and bracket-call examples in EN/ZH libs and public/stdlib
demos; keep explicit + params so function-body prose cannot be mistaken for
link-index or bold code.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 11:38:24 +08:00

56 lines
2.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 标准库 / 扩展库:代码即文档
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [code-as-docs-gaps.md](code-as-docs-gaps.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [stdlib.md](stdlib.md) · [marqdo-dev skill](../../.cursor/skills/marqdo-dev/SKILL.md) · [roadmap](../roadmap/lib-ext-code-as-docs.md) |
---
## 1. 目标
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
## 2. 薄库模板(默认)
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
1. **目的句**(一句人话,无标记即可)。
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
3. **一例**:粗体或 `>` 调用;优先可读表面。
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
```markdown
**出 = [put] 入=`表` 键="a" 值=1**
**出 = put 入=`表` 键="a" 值=1**
> put 入=`表` 键="a" 值=1
```
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
## 3. 硬约束
| 要 | 不要 |
|----|------|
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
## 4. 波次
见 [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md):先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿(随括号调用落地) |