Create interface: doc comments are reindented, and `@deprecated` and doc comments on values are dropped

未关闭
  • 哪里不对？
#9,181 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

维护者通常 1 天内回复

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
35/100
Issue 类型
缺陷
描述清晰度
基本清楚
活跃度
活跃
技术栈
javascript, ocaml
领域
compilers

调研方向

The reindentation and dropped attributes both come from analysis/src/create_interface.ml: start at literal_lines, which marks only string and template tokens as verbatim, and at the Sig_value case, which prints values from their type. Check whether doc comments and the @deprecated attribute are carried through for let values the way they are for external. Done when a multi-line doc comment in a nested module keeps its original indentation in the generated .resi and let f keeps its doc and deprecation attribute.

由索引模型根据 Issue 内容生成。

描述

Found by differential semantic drift analysis from b123b7c3 to c10223e8.

What is broken

  • Doc comments are reindented (since #9144). In a nested module, the lines of a multi-line doc comment after its first are shifted to the declaration's indentation:

    module A = {
  module B = {
    /** Example:
```rescript
let v: t = 1
```
*/
    type t = int
  }
}

    The generated .resi indents ```rescript, let v: t = 1 and ``` by four spaces. rescript-tools doc then reads "Example:\n ```rescript\n let v: t = 1\n ```" from the .resi and "Example:\n```rescript\nlet v: t = 1\n```" from the .res: the fenced block becomes an indented code block. Relative indentation inside a doc comment also collapses (a line at column 0 inside a type at column 4 moves to column 4). #9144 copies lines inside string and template literals verbatim because reindenting them "would change its value"; a doc comment is the string payload of @res.doc. literal_lines marks only string and template tokens as verbatim.

  • @deprecated and doc comments on let values are dropped (before this range as well). For

    /** Doc of f. */
@deprecated("use g")
let f = x => x + 1
let g = x => x + 1

    the generated interface is let f: int => int and let g: int => int. A module calling Dep.f(1) gets warning 3 without the .resi and none with it. An external keeps both attributes. #9096 covers type declarations; the Sig_value case prints values from their type.

Possible cause (speculation only)

The reindentation added by #9144 protects string and template literals but not comments, although #9096 had already made doc comments part of the copied text.

🤖 Generated with Claude Code

主要语言
OCaml
星标
7.5k
派生
484
平均合并
17 小时 2 分钟
30 天内合并 PR
249

环境准备

在 Codespaces 中打开

在浏览器里用你自己的 GitHub 账号启动这个项目的开发容器。

从这里开始

  1. 先读完整个 Issue，再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库，在一个分支上完成修改。
  4. 提交 Pull Request，并在描述里引用这个 Issue 编号。

rescript-lang/rescript 的其他 Issue

查看 rescript-lang/rescript 的全部 Issue

相似的 Issue

更多 Compilers Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。