JEP 467: Markdown दस्तावेज़ टिप्पणियाँ

लक्ष्य

Java की दस्तावेज़ टिप्पणियों में Markdown सिंटैक्स का समर्थन देकर पठनीयता बेहतर करना और अधिक संक्षिप्त दस्तावेज़ लेखन को प्रोत्साहित करना।

प्रेरणा

• मौजूदा JavaDoc HTML टैग्स पर निर्भर है → यह बहुत लंबा-चौड़ा और पढ़ने में कठिन है।
• डेवलपर्स पहले से ही README, GitHub आदि में Markdown के अभ्यस्त हैं।
• Markdown समर्थन से सुसंगत और संक्षिप्त दस्तावेज़ लेखन संभव है।

विवरण

• JavaDoc टिप्पणियों के भीतर CommonMark-आधारित Markdown सिंटैक्स का समर्थन।
• मौजूदा HTML टिप्पणियाँ भी अब भी उपयोग की जा सकती हैं।
• मौजूदा /* ... */ शैली की टिप्पणियों के बजाय /// का उपयोग करके यह दर्शाया जाता है कि यह Markdown दस्तावेज़ टिप्पणी है।
• 3rd-party JavaDoc tools Markdown को parse और render करते हैं।

Markdown विनिर्देश

• CommonMark आधारित।
• समर्थित सिंटैक्स:
  • शीर्षक (#, ##, ### आदि)
  • सूची (क्रमबद्ध/अक्रमबद्ध)
  • कोड ब्लॉक (```)
  • लिंक
  • तालिका (Github Flavored Markdown शैली)
  • उद्धरण
  • जोर (*इटैलिक*, **बोल्ड**)

Java-विशिष्ट टैग

Markdown के साथ मौजूदा JavaDoc @-टैग्स का उपयोग संभव:

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

[devnamho0910]

बेहतरीन है...

[carnoxen]

लगता है कि इसे standard में शामिल कर लिया गया है।

[click]

यह JDK23 में शामिल हो गया है।
टेस्ट करके देखा तो, प्रोजेक्ट का JDK version 23 से कम होने पर भी अगर IDE या Javadoc EXPORT tool इसे सपोर्ट करे, तो यह सामान्य रूप से काम करता है।