microsoft / microsoft/TypeScript
JSDoc unexpected leading whitespace behaviour with `@example` and `<caption>`
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Go
- Estrellas
- 111k
- Forks
- 14.3k
- Merge medio
- 2 d 4 h
- PR fusionados (30 d)
- 132
Descripción
Bug Report
🔎 Search Terms
#15749 matches, but was last updated in June 2020 -- was informed to make a new issue
🕗 Version & Regression Information
- This is the behavior in every version I tried, and I reviewed the FAQ for entries about JSDoc and leading whitespace
⏯ Playground Link
Playground link with relevant code
💻 Code
// In the code block below, `sum(answer, 5)` is NOT indented, but it should be.
// `sum2(answer, 5)` is indented.
/**
* Adds two numbers
*
* @param a number one
* @param b number two
* @returns sum of number one and number two
*
* @example <caption>Add 1 and 3. If answer is >0, sums result and 5.</caption>
* ```
* const answer = sum(1, 3); // returns 4
*
* if (answer > 0) {
* sum(answer, 5)
* }
* ```
*/
function sum(a: number, b: number): number {
return a + b
}
/**
* Adds two numbers
*
* @param a number one
* @param b number two
* @returns sum of number one and number two
*
* @example <caption>Add 1 and 3. If answer is >0, sums result and 5.</caption>
* ```
* const answer = sum2(1, 3); // returns 4
*
* if (answer > 0) {
* sum2(answer, 5)
* }
* ```
*/
function sum2(a: number, b: number): number {
return a + b
}
🙁 Actual behavior
The JSDoc produced for sum() has the example without any indentation, despite there being preceding whitespace.
This only happens when there is a <caption> tag present.

🙂 Expected behavior
The result should have the same indentation as present in the comment, preferably determined from the indentation of the code block backticks.

Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Comienza con el TypeScript Playground enlazado y compara los ejemplos de JSDoc proporcionados que usan , especialmente la indentación diferente en sum y sum2. Sigue cómo se procesan el contenido de @example y el texto de caption; se considera terminado cuando el ejemplo generado conserva de forma coherente la indentación del comentario y existe cobertura de regresión para ambos casos.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- typescript
- Área
- compilers
- Tipo de issue
- Error
- Dificultad
- 3/5
- Tiempo estimado
- 1-2 días
- Estado de actividad
- Estancado
- Claridad
- Bastante claro
- Aptitud para principiantes
- 35/100