microsoft / microsoft/TypeScript
JSDoc unexpected leading whitespace behaviour with `@example` and `<caption>`
Nessuno ha ancora preso questa issue.
- Lingua principale
- Go
- Stelle
- 111k
- Fork
- 14.3k
- Merge medio
- 2g 4h
- PR unite (30g)
- 132
Descrizione
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.

Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Inizia dal TypeScript Playground collegato e confronta gli esempi JSDoc forniti che usano , in particolare la diversa indentazione in sum e sum2. Traccia il modo in cui vengono elaborati il contenuto di @example e il testo di caption; il lavoro è completato quando l'esempio generato conserva in modo coerente l'indentazione del commento e sono presenti test di regressione per entrambi i casi.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- typescript
- Ambito
- compilers
- Tipo di issue
- Bug
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100