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

Abierto
  • ¿Algo no está bien?
#9,181 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Error
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
javascript, ocaml
Área
compilers

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
OCaml
Estrellas
7.5k
Forks
484
Merge medio
16 h 57 min
PR fusionados (30 d)
258

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de rescript-lang/rescript

Todos los issues de rescript-lang/rescript

Issues similares

Más issues de Compilers

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.