JEP 467: Chú thích tài liệu Markdown

Mục tiêu

Hỗ trợ cú pháp Markdown trong chú thích tài liệu của Java để cải thiện khả năng đọc và khuyến khích viết tài liệu ngắn gọn hơn.

Động lực

• JavaDoc hiện tại phụ thuộc vào thẻ HTML → quá dài dòng và khó đọc.
• Các nhà phát triển đã quen với Markdown trên README, GitHub, v.v.
• Hỗ trợ Markdown giúp việc viết tài liệu nhất quán và ngắn gọn hơn.

Mô tả

• Hỗ trợ cú pháp Markdown dựa trên CommonMark bên trong chú thích JavaDoc.
• Các chú thích HTML hiện có vẫn tiếp tục dùng được.
• Thay vì kiểu chú thích /* ... */ hiện có, sử dụng /// để biểu thị đây là chú thích tài liệu Markdown.
• Công cụ JavaDoc của bên thứ ba sẽ phân tích cú pháp và kết xuất Markdown.

Đặc tả Markdown

• Dựa trên CommonMark.
• Các cú pháp được hỗ trợ:
  • Tiêu đề (#, ##, ###, v.v.)
  • Danh sách (có thứ tự/không thứ tự)
  • Khối mã (```)
  • Liên kết
  • Bảng (theo kiểu Github Flavored Markdown)
  • Trích dẫn
  • Nhấn mạnh (*nghiêng*, **đậm**)

Thẻ dành riêng cho Java

Có thể dùng các thẻ @ hiện có của JavaDoc cùng với Markdown:

• @param
• @return
• @throws
• @see
• @since
• @deprecated

[devnamho0910]

Tuyệt vời...

[carnoxen]

Có vẻ như đã được đưa vào tiêu chuẩn rồi.

[click]

Đã được đưa vào JDK 23.
Khi thử nghiệm, tôi thấy ngay cả khi phiên bản JDK của dự án thấp hơn 23, nếu IDE hoặc công cụ EXPORT JavaDoc hỗ trợ thì vẫn hoạt động bình thường.