Skip to content

docs-gen: 模块 JSDoc 按行拆成段落,跨行的行内代码跨度被切断 —— 5 张参考页正文露出裸反引号和 \{ 转义痕迹 #5553

Closed
#6224
Closed
docs-gen: 模块 JSDoc 按行拆成段落,跨行的行内代码跨度被切断 —— 5 张参考页正文露出裸反引号和 \{ 转义痕迹#5553
#6224
Assignees
os-zhuang
Labels
pm:dispatchedpm:queue

Description

@os-zhuang
os-zhuang
opened on Aug 5, 2026

在实施 #5452(.describe() 的花括号转义)时,给生成语料做配平扫描顺带发现的另一条独立缺陷。不同函数、不同根因,故单独立单:#5452 改的是 escapeMdxDescription 的定界符配对,本单在 getFileDescription。

现象(origin/main @ 5acb93add,#5452 的 PR #5550 重生成后依然如此)

packages/spec/scripts/build-docs.ts 的 getFileDescription 把模块级 JSDoc 的每一行用 \n\n 连接:

.map(line => line.replace(/^\s*\*\s?/, '').trim())
.filter(line => line)
.map(line => line.replace(/^@see\s+/, 'See also: '))
.join('\n\n')                                   // ← 每个源码行 = 一个段落

于是任何跨源码行的 Markdown 构造都被段落边界切断。行内代码跨度不能跨空行,所以两边的反引号都当字面量渲染出来。

扫描生成语料(排除围栏代码块,统计反引号数为奇数的行)得 10 行 / 5 张页面 = 5 个被切断的跨度:

content/docs/references/automation/flow-function.mdx:22,24
content/docs/references/security/explain.mdx:8,10
content/docs/references/shared/expression.mdx:16,18
content/docs/references/system/doc.mdx:24,26
content/docs/references/system/settings-client.mdx:10,12

最直观的一处,automation/flow-function.mdx:22-24:

variable so a later DECLARATIVE node persists it (`update_record fields: \{

ai_category: '\{aiResult.ai_category\}' \}`). Data I/O stays on the flow graph.

读者看到的是两个段落,中间一个孤立的反引号开头、另一个反引号结尾 —— 而源码里它本是一个完整的行内代码例子:

// packages/spec/src/automation/flow-function.zod.ts:13-15
 * variable so a later DECLARATIVE node persists it (`update_record fields: {
 *   ai_category: '{aiResult.ai_category}' }`). Data I/O stays on the flow graph.

security/explain.mdx:8 同理把 `explain(principal, object, operation)` 从中间劈开。

为什么 \{ 会露出来(次生现象)

同一函数末尾对花括号做无差别反斜杠转义:

.replace(/\{/g, '\\{').replace(/\}/g, '\\}')   // Escape { } for MDX

它不区分「在代码跨度里」还是「在正文里」。跨度没被切断时,\{ 落在行内代码内部,而代码跨度里反斜杠不是转义符,读者就会看到字面的 \{。上面 5 处因为跨度已经断了,\{ 反而当正文转义正常渲染成 { —— 两个缺陷互相掩盖,所以肉眼扫过去只觉得「反引号有点怪」。

注意这条转义路径和 #5452 修的是两条不同的路径:.describe() 走 escapeMdxDescription(包进行内代码),模块 JSDoc 走这里(反斜杠转义)。#5452 的修复不触及本单。

修法方向(未验证)

两点都在 getFileDescription 里:

  1. 段落切分应按 JSDoc 的空行切,而不是按每个源码行切 —— 即连续非空行合并为一段(用空格连接),空行才开新段。这同时修好跨行的链接、粗体等其它构造。
  2. 花括号转义应像 escapeMdxDescription 那样感知反引号:已在行内代码里的花括号不需要任何转义(代码跨度天然不被 MDX 当表达式解析),不在代码里的才需要处理。

改完重跑 pnpm --filter @objectstack/spec gen:docs,验收:上面的奇数反引号扫描归零,且 flow-function.mdx 那句恢复成单个完整的行内代码例子、不含 \{。

影响面

5 张已发布参考页的正文段落,读者今天访问就能看到。纯展示层,无运行时/协议语义。

Activity

  1. os-zhuang
    added
    pm:queue
    domain:spec
    on Aug 5, 2026

  2. os-zhuang commented on Aug 5, 2026

    @os-zhuang
    os-zhuang
    on Aug 5, 2026 – with Claude
    ContributorAuthor

    分诊:pm:queue + domain:spec。

    本评论来自分诊座位 Routine(#5474 试点),不构成认领。

    Generated by Claude Code

  3. os-zhuang commented on Aug 6, 2026

    @os-zhuang
    os-zhuang
    on Aug 6, 2026 – with Claude
    ContributorAuthor

    疑似域误标：本单落点在 docs-gen 生成器（packages/spec/scripts/**，C 包 #5163 文件面），不触 packages/spec/src/**/*.zod.ts，建议改标 domain:spec-tooling ——交分诊座位定夺。背景：维护者 2026-08-06 拍板 spec 车道缩盘方案，见 #5837。

    Generated by Claude Code

  4. os-zhuang
    added
    domain:spec-tooling
    and removed
    domain:spec
    on Aug 6, 2026

  5. os-zhuang commented on Aug 6, 2026

    @os-zhuang
    os-zhuang
    on Aug 6, 2026 – with Claude
    ContributorAuthor

    标签落实（维护者 2026-08-06 指示，session_01LeEfA7CFwbJb7JJmXm2KM3）：按 08-06 转席建议执行 domain:spec → domain:spec-tooling（缩盘方案 #5837 已拍板，落点 docs-gen 生成器）。

    Generated by Claude Code

  6. os-zhuang
    added
    pm:dispatched
    on Aug 7, 2026
  7. os-zhuang
    self-assigned this
    on Aug 7, 2026

  8. os-zhuang commented on Aug 7, 2026

    @os-zhuang
    os-zhuang
    on Aug 7, 2026 – with Claude
    ContributorAuthor

    认领:PM 循环第 5 轮(spec-tooling 车道,座位登记 #6018)
    会话:session_014wsZeReNTqiceBfLb5Pyf5
    分支:claude/issue-5553-file-description-rendering
    Worktree:objectstack-issue-5553
    域:domain:spec-tooling

    与 #6136 打包为同一次派发(一个 PR,双 Fixes):落点核实后两单同落 packages/spec/scripts/lib/file-description.ts(#6134 今日新建的描述提取/渲染模块),且同属一条渲染链上的两个独立缺陷。分开派会各付一次 content/docs/references/** 重生成并互相埋 diff——打包成本更低,duplicate-fix-guard 只拦「两个 PR 声明同一 issue」,一个 PR 声明两个 issue 合规。

    文件面:packages/spec/scripts/lib/file-description.ts + packages/spec/scripts/file-description.test.ts + content/docs/references/** 重生成 + .changeset/*.md。⛔ 不碰 build-docs.ts(#5853 下轮)、lib/format-type.ts(#5340 本轮并行)、build-schemas.ts(#5371 本轮并行)、zod 文件。(越界即停,报告说明)

    Generated by Claude Code

  9. os-zhuang
    added a commit that references this issue on Aug 7, 2026

    chore(docs): 合入 main 后整体重跑 gen:schema && gen:docs (#5553, #6136)

    201ab12
  10. os-zhuang
    closed this as completedin #6224on Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

pm:dispatchedpm:queue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions