JEP 467: Markdown belge açıklamaları

Amaç

Java'nın belge açıklamalarında Markdown sözdizimini destekleyerek okunabilirliği artırmak ve daha kısa, özlü dokümantasyon yazımını teşvik etmek.

Motivasyon

• Mevcut JavaDoc, HTML etiketlerine bağımlı → fazla ayrıntılı ve okunması zor.
• Geliştiriciler zaten README, GitHub vb. ortamlarda Markdown kullanımına aşina.
• Markdown desteğiyle tutarlı ve özlü dokümantasyon yazımı mümkün.

Açıklama

• JavaDoc yorumları içinde CommonMark tabanlı Markdown sözdizimi desteklenir.
• Mevcut HTML açıklamaları da hâlâ kullanılabilir.
• Mevcut /* ... */ tarzı yorumlar yerine, bunun bir Markdown belge açıklaması olduğunu belirtmek için /// kullanılır.
• Üçüncü taraf JavaDoc araçları, Markdown'ı ayrıştırır ve render eder.

Markdown özellikleri

• CommonMark tabanlıdır.
• Desteklenen sözdizimi:
  • Başlıklar (#, ##, ### vb.)
  • Listeler (sıralı/sırasız)
  • Kod blokları (```)
  • Bağlantılar
  • Tablolar (Github Flavored Markdown biçimi)
  • Alıntı blokları
  • Vurgu (*italik*, **kalın**)

Java'ya özgü etiketler

Markdown ile birlikte mevcut JavaDoc @-etiketleri de kullanılabilir:

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

[devnamho0910]

Harika...

[carnoxen]

Görünüşe göre standarda yansıtılmış.

[click]

JDK23'e eklendi.
Test ettiğimde, projenin JDK sürümü 23'ten düşük olsa bile IDE veya Javadoc EXPORT aracı destekliyorsa sorunsuz çalışıyor.