JEP 467: คอมเมนต์เอกสารแบบ Markdown

เป้าหมาย

รองรับ ไวยากรณ์ Markdown ในคอมเมนต์เอกสารของ Java เพื่อเพิ่มความอ่านง่ายและช่วยให้เขียนเอกสารได้กระชับขึ้น

แรงจูงใจ

• JavaDoc แบบเดิมพึ่งพา แท็ก HTML → ยืดยาวเกินไปและอ่านยาก
• นักพัฒนาคุ้นเคยกับ Markdown อยู่แล้วจาก README, GitHub ฯลฯ
• การรองรับ Markdown ทำให้สามารถเขียนเอกสารได้อย่าง สม่ำเสมอ และ กระชับ

คำอธิบาย

• รองรับ ไวยากรณ์ Markdown ที่อิงตาม CommonMark ภายในคอมเมนต์ JavaDoc
• คอมเมนต์ HTML แบบเดิมก็ยังคงใช้งานได้
• ใช้ /// แทนคอมเมนต์รูปแบบเดิม /* ... */ เพื่อระบุว่าเป็นคอมเมนต์เอกสารแบบ Markdown
• เครื่องมือ JavaDoc ของบุคคลที่สาม จะจัดการ การ parse และ การ render Markdown

สเปก Markdown

• อิงตาม CommonMark
• ไวยากรณ์ที่รองรับ:
  • หัวข้อ (#, ##, ### เป็นต้น)
  • รายการ (มีลำดับ/ไม่มีลำดับ)
  • โค้ดบล็อก (```)
  • ลิงก์
  • ตาราง (Github Flavored Markdown แบบ)
  • บล็อกคำอ้างอิง
  • การเน้น (*ตัวเอียง*, **ตัวหนา**)

แท็กเฉพาะของ Java

สามารถใช้ แท็ก @ ของ JavaDoc แบบเดิมร่วมกับ Markdown ได้:

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

[devnamho0910]

ยอดเยี่ยมมาก...

[carnoxen]

ดูเหมือนว่าจะถูกรวมเข้าไปในมาตรฐานแล้วนะ

[click]

รวมอยู่ใน JDK23 แล้ว
ลองทดสอบดูแล้ว แม้เวอร์ชัน JDK ของโปรเจ็กต์จะต่ำกว่า 23 ก็ยังทำงานได้ตามปกติ หาก IDE หรือเครื่องมือ export ของ Javadoc รองรับ