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

Aperta
  • Qualcosa non va?
#9,181 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Bug
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
javascript, ocaml
Ambito
compilers

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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

Lingua principale
OCaml
Stelle
7.5k
Fork
484
Merge medio
17h 2m
PR unite (30g)
249

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di rescript-lang/rescript

Tutte le issue di rescript-lang/rescript

Issue simili

Altre issue su Compilers

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.