microsoft / microsoft/TypeScript

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

Đang mở
#43,955 6 bình luận 24 reaction 0 người được giao Xem trên GitHub

Chưa có ai nhận issue này.

Bug Domain: JSDoc
Ngôn ngữ chính
Go
Star
111k
Fork
14.3k
Merge trung bình
1 ngày 19 giờ
Pull request đã merge (30 ngày)
117

Mô tả

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

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Hướng nghiên cứu

Bắt đầu với TypeScript Playground được liên kết và so sánh các ví dụ JSDoc được cung cấp có sử dụng , đặc biệt là sự khác biệt về thụt lề trong sum và sum2. Theo dõi cách nội dung @example và văn bản caption được xử lý; hoàn thành khi ví dụ được tạo ra giữ nguyên nhất quán thụt lề của comment và có kiểm thử hồi quy cho cả hai trường hợp.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
typescript
Lĩnh vực
compilers
Loại issue
Lỗi
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.