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
分支
485
平均合併
16 小時 51 分鐘
30 天內合併 PR
268

環境準備

在 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 摘要。