microsoft / microsoft/TypeScript
JSDoc unexpected leading whitespace behaviour with `@example` and `<caption>`
未关闭
还没有人认领这个 Issue。
Bug
Domain: JSDoc
- 主要语言
- Go
- 星标
- 111k
- 派生
- 14.3k
- 平均合并
- 1 天 19 小时
- 30 天内合并 PR
- 117
描述
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.

贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
调研方向
从链接的 TypeScript Playground 开始,比较提供的使用 的 JSDoc 示例,尤其关注 sum 和 sum2 中不同的缩进。跟踪 @example 内容和 caption 文本的处理方式;完成标准是生成的示例能够一致地保留注释的缩进,并且为这两种情况提供回归测试覆盖。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- typescript
- 领域
- compilers
- Issue 类型
- 缺陷
- 难度
- 3/5
- 预计耗时
- 1-2 天
- 活跃度
- 停滞
- 描述清晰度
- 基本清楚
- 新手友好度
- 35/100