#4001 正文「踩过的坑」第 1 条早就写明:scripts/build-docs.ts 的 getFileDescription() 取模块里第一个 /** */ 块原样做参考页描述,所以在 schema 的文件级 JSDoc 之前插入辅助代码块,会把公开文档页的内容换成内部注释。
这件事已经落到 main 上两次了,check:docs 抓不到 —— 它只比对生成物与源码是否一致,而这里两者是一致的:源码里第一个 doc block 确实就是那段内部注释。
现状
content/docs/references/data/mapping.mdx 第 8 行(页面正文首句):
Shared history for this file (#4001).
content/docs/references/system/translation.mdx 第 8 行:
Shared history sentence for every shape in this file (#4001).
Translation data has the most literal version of the silent-strip failure in
the whole spec: a misspelled group or key is dropped, the bundle saves or
即:Translation 协议参考页开篇讲的是本仓收紧战役的历史沿革,而不是 translation 是什么。对着这页学写 *.translation.ts 的人(尤其是 AI 作者)拿到的第一段是完全无关的内部叙事。
成因
两个文件都把 const *_HISTORY = '…'(带 /** */ 文档注释)放在了文件里第一个 schema 的 JSDoc 之前:
packages/spec/src/system/translation.zod.ts —— /** Shared history sentence for every shape in this file (#4001). … */ 在 LocaleSchema 之后、任何带 JSDoc 的 schema 之前,成了全模块第一个 doc block。packages/spec/src/data/mapping.zod.ts —— 同形状。
修法
把这两个 history 常量的 /** */ 换成 // 行注释(或整体挪到文件第一个 schema 的 JSDoc 之后),然后 pnpm --filter @objectstack/spec gen:schema && gen:docs 重新生成这两页。批 15 已经对 chart.zod.ts 做过一模一样的修正(「把 #3746 陷阱的警告本身移出 doc block」),照抄即可。
顺带:能不能让它有门禁
check:docs 结构上看不见这一类。可行的机械判据是:参考页正文首句命中 #\d{3,} / Shared history / Until # 这类只可能出自内部注释的模式就失败 —— 窄、无假阳,且正好覆盖这个战役会持续制造的形状(每个批次都在往文件里加 history 常量)。若认可,可并入这件一起做。
由 #4001 批 16 在检查自己会不会踩同一个坑时扫出(批 16 自己按批 15 的做法用 // 规避了)。范围外,故单开,不在批 16 的 PR 里改。
#4001 正文「踩过的坑」第 1 条早就写明:
scripts/build-docs.ts的getFileDescription()取模块里第一个/** */块原样做参考页描述,所以在 schema 的文件级 JSDoc 之前插入辅助代码块,会把公开文档页的内容换成内部注释。这件事已经落到 main 上两次了,
check:docs抓不到 —— 它只比对生成物与源码是否一致,而这里两者是一致的:源码里第一个 doc block 确实就是那段内部注释。现状
content/docs/references/data/mapping.mdx第 8 行(页面正文首句):content/docs/references/system/translation.mdx第 8 行:即:Translation 协议参考页开篇讲的是本仓收紧战役的历史沿革,而不是 translation 是什么。对着这页学写
*.translation.ts的人(尤其是 AI 作者)拿到的第一段是完全无关的内部叙事。成因
两个文件都把
const *_HISTORY = '…'(带/** */文档注释)放在了文件里第一个 schema 的 JSDoc 之前:packages/spec/src/system/translation.zod.ts——/** Shared history sentence for every shape in this file (#4001). … */在LocaleSchema之后、任何带 JSDoc 的 schema 之前,成了全模块第一个 doc block。packages/spec/src/data/mapping.zod.ts—— 同形状。修法
把这两个 history 常量的
/** */换成//行注释(或整体挪到文件第一个 schema 的 JSDoc 之后),然后pnpm --filter @objectstack/spec gen:schema && gen:docs重新生成这两页。批 15 已经对chart.zod.ts做过一模一样的修正(「把 #3746 陷阱的警告本身移出 doc block」),照抄即可。顺带:能不能让它有门禁
check:docs结构上看不见这一类。可行的机械判据是:参考页正文首句命中#\d{3,}/Shared history/Until #这类只可能出自内部注释的模式就失败 —— 窄、无假阳,且正好覆盖这个战役会持续制造的形状(每个批次都在往文件里加 history 常量)。若认可,可并入这件一起做。由 #4001 批 16 在检查自己会不会踩同一个坑时扫出(批 16 自己按批 15 的做法用
//规避了)。范围外,故单开,不在批 16 的 PR 里改。