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

Aberta
  • Algo errado?
#9,181 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
4/5
Tempo estimado
3-5 dias
Facilidade para iniciantes
35/100
Tipo de issue
Bug
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
javascript, ocaml
Domínio
compilers

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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

Linguagem predominante
OCaml
Estrelas
7.5k
Forks
484
Merge médio
16h 57min
PRs com merge (30d)
258

Preparar o ambiente

Abrir no Codespaces

Inicia o contêiner de desenvolvimento do projeto no navegador, com a sua própria conta do GitHub.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de rescript-lang/rescript

Todas as issues de rescript-lang/rescript

Issues semelhantes

Mais issues de Compilers

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.