microsoft / microsoft/TypeScript

JSDoc unexpected leading whitespace behaviour with `@example` and `<caption>`

Aperta
#43,955 6 commenti 24 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Bug Domain: JSDoc
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.

image

🙂 Expected behavior

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

image

Guida per i contributori

Apri la guida per i contributori

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.

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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.