Markdown في تعليقات Javadoc
اكتب تعليقات Javadoc بـ Markdown بدلاً من HTML لقراءة أفضل.
مقارنة الكود
✕ Java 8
/**
* Returns the {@code User} with
* the given ID.
*
* <p>Example:
* <pre>{@code
* var user = findUser(123);
* }</pre>
*
* @param id the user ID
* @return the user
*/
public User findUser(int id) { ... }
✓ Java 23+
/// Returns the `User` with
/// the given ID.
///
/// Example:
/// ```java
/// var user = findUser(123);
/// ```
///
/// @param id the user ID
/// @return the user
public User findUser(int id) { ... }
هل ترى مشكلة في هذا الكود؟ أخبرنا.
لماذا يتفوق الأسلوب الحديث
بنية طبيعية
استخدم علامات اقتباس خلفية للكود المضمّن وقُدرات ``` للكتل بدلاً من وسوم HTML.
أسهل في الكتابة
لا حاجة لـ {@code} أو <pre> أو وسوم <p> — اكتب Markdown فقط.
أفضل في المحررات
Markdown يُعرَض بشكل جميل في IDEs الحديثة ومحررات النصوص.
الأسلوب القديم
Javadoc قائم على HTML
الأسلوب الحديث
Javadoc بـ Markdown
منذ JDK
23
الصعوبة
مبتدئ
دعم JDK
Markdown في تعليقات Javadoc
متاح
متاح منذ JDK 23 (سبتمبر 2024)
كيف يعمل
يقدّم Java 23 تعليقات Javadoc بنمط /// Markdown كبديل لصيغة /** */ HTML التقليدية. بناء Markdown أكثر طبيعيةً في الكتابة والقراءة مع دعم لكتل الكود والتأكيد والقوائم والروابط. يحوّل المترجم Markdown إلى HTML لمخرجات javadoc.
توثيق ذو صلة