Files
marqdo/doc/design/lib-code-as-docs.md

3.4 KiB

标准库 / 扩展库:代码即文档

当前可执行开发规范见库开发指南,其中的真实函数示范叙述内赋值、遮蔽调用、表格数据与返回。本页保留设计背景与历史波次。

状态 Active
日期 2026-09-14
相关 code-as-docs-gaps.md · bracket-call-modifiers.md · collection-access-link.md · stdlib.md · marqdo-dev skill · roadmap

1. 目标

lib/* 与 ext/* 的 .mq.md 应可当说明书读、可当程序跑。薄库用充分且具体的叙述解释短实现;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。

2. 单文件标准库模板

标准库通常是一个 lib/*.mq.md 文件,源码自身承担使用手册、开发说明与 SKILL。 直接阅读、导入或调用此文件,不增加强制 index.mq.md 或平行模块手册。 多文件拓展库才用 index.mq.md 组织模块与开发路线。

每个函数依次提供:标题、参数表(名称、类型、默认值、含义)、返回契约、效应说明、 叙述形参、用途与真实调用例子、简短实现。无参数函数直接放返回表。 参数和返回契约位于第一条执行语句之前;标准库不再保留旧 + 形参清单。

叙述形参使用正文中的反引号名称,默认值紧跟等号;表格说明与实际默认值必须一致。 例如正文写「输入路径 path」,调用时即可提供 path。含标点的文本默认值使用完整引号。 不透明类型保留渐进式 any,并说明其产生途径和限制。

3. 可读性与调用规范

每个函数单元的叙述比例必须超过 50%,同时说明真实用途和边界;不能靠重复套话凑比例。 参数和返回契约表属于文档面,绑定的数据表仍须表达真实数据。

宿主等不透明调用用遮蔽语法表达动作:[] 写做什么,() 写实际执行代码。 返回和赋值仍遵循原有标记;标签不执行,也不替代失败处理。

## read_text

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| path | text | 必填 | 授权根目录内的文件路径 |

| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | UTF-8 文本;无效编码或读取失败产生诊断 |

输入路径 `path`。此操作读取整个文件;大文件应改用分块读取。
文件根目录由调用方授权,不能通过传入路径绕过权限。

读取完成后,我们返回*[读取授权范围内的 UTF-8 文本](> host_read_text path=`path`)*,供调用方继续处理。

集合读取使用 access(collection, key),不使用旧链接取元;循环使用显式遍历。 用 GFM 表和具名助手表达结构化数据,避免 json.set/json.append 链。 说明中的调用示例放在未绑定代码围栏内,不能让示例意外成为函数执行步骤。 中英文源码保持语义、默认值与行为一致;检查叙述比例、契约并执行真实示例。

4. 波次

见 roadmap/lib-ext-code-as-docs.md:先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。

5. 修订历史

日期 说明
2026-09-14 初稿(随括号调用落地)