Javadoc टिप्पणी में कई लाइन कोड उदाहरण

Question

मेरे पास एक छोटा कोड उदाहरण है जिसे मैं एक विधि के लिए जवादोक टिप्पणी में शामिल करना चाहता हूं।

/**
 * -- ex: looping through List of Map objects --
 * <code>
 * for (int i = 0; i < list.size(); i++) {
 *      Map map = (Map)list.get(i);
 *      System.out.println(map.get("wordID"));
 *      System.out.println(map.get("word"));
 * }
 * </code>
 * 
 * @param query - select statement
 * @return List of Map objects
 */

समस्या यह है कि कोड उदाहरण जावदोक में दिखाई देता है जिसमें कोई रेखा नहीं टूटती है जिससे इसे पढ़ना मुश्किल हो जाता है।

-- ex: looping through List of Map objects -- for (int i = 0; i list.size(); i++) { Map map = (Map)list.get(i); System.out.println(map.get("wordID")); System.out.println(map.get("word")); } 
Parameters
query - - select statement 
Returns:
List of Map objects 

मुझे लगता है कि मैं कोड टैग संभालने में गलत हूं लाइन ब्रेक को संभालना होगा। Javadoc टिप्पणियों में कोड उदाहरणों को प्रारूपित करने का सबसे अच्छा तरीका क्या है?

Answer 1

पहले से बताए गए <pre>टैग के अलावा , आपको @codeJavaDoc एनोटेशन का भी उपयोग करना चाहिए , जो HTML संस्थाओं के मुद्दों (विशेष रूप से जेनरिक के साथ), जैसे:

* <pre>
* {@code
* Set<String> s;
* System.out.println(s);
* }
* </pre>

सही HTML आउटपुट देगा:

Set<String> s;
System.out.println(s);

@codeब्लॉक को छोड़ते समय (या किसी <code>टैग का उपयोग करके ) HTML का परिणाम इस प्रकार होगा:

Set s;
System.out.println(s);

(संदर्भ के लिए, जावा एसई 8 टैग विवरण यहां मिल सकते हैं: जावदोक टैग )

Comments

मैंने भी ऐसा सोचा होगा, लेकिन दुर्भाग्य से ऐसा नहीं है, आपको अभी भी लाइन ब्रेक पाने के लिए <प्री> टैग जोड़ना होगा।

— फाबियन स्टील

दुर्भाग्य से, ऐसा लगता है कि जब आप ctrl + shift + F (ग्रहण में प्रारूप कोड) को हिट करते हैं, तो ग्रहण {@code} टैग को गड़बड़ कर देता है और इसे {& # 064; कोड के साथ बदल देता है; कोड ...

— jpdaigle

@jpdaigle मैंने अभी ग्रहण गैलीलियो और हेलियोस में यह कोशिश की थी और फॉर्मैटर मेरे लिए कुछ भी प्रतिस्थापित नहीं करता है (मैक ओएस पर, लेकिन मैंने कभी ऐसा नहीं देखा कि फॉर्मैटर ऐसा कुछ अन्य प्लेटफार्मों पर भी करता हो)।

— फाबियन स्टील

एक और दुर्भाग्यपूर्ण है, यदि आपके पास घुंघराले ब्रेस "{}" का उपयोग करके अपने उदाहरण कोड में ब्लॉक हैं, तो पहले समापन ब्रेस @code ब्लॉक को समाप्त कर देगा। इसके चारों ओर एक तरह से ब्रेसिज़ के लिए html (इसके लिए प्रतीक्षा करें ...) का उपयोग करना है। मुझे ब्लॉक के साथ कोड के लिए <pre> टैग के लिए एक सम्मोहक तर्क दिखाई नहीं देता है।

— एड ग्रिबेल

ग्रहण {@code} टैग को गड़बड़ कर देता है और इसे {& # 064; कोड के साथ बदल देता है; कोड- यह ग्रहण के कारण नहीं है, यह (खराब?) Javadoc उपयोगिता के कारण है। यदि आपके पास {@code ... multiline ...} के अंदर मल्टीलाइन कोड में @ वर्ण है, तो javadoc इसे सही ढंग से पार्स करने में विफल रहता है :( कम से कम यह वही है जो मैं Oracle JDK1.7.0_45 javadoc कार्यान्वयन के साथ देखता हूं

— पुरुष

Answer 2

मेरे पास एक बहुत कठिन समय था जिसमें एक विशिष्ट कोड उदाहरण शामिल था, जिसमें एक जावाडॉक टिप्पणी थी। मैं इसे साझा करना चाहूंगा।
कृपया निम्नलिखित ध्यान दें:

• <code>घुंघराले कोष्ठक की व्याख्या करने से रोकने के लिए पुराने - टैग का उपयोग
• "नई" का उपयोग {@code ...}- आउटपुट में जेनरिक को शामिल करने के लिए टैग
• @ साइन इन @Override"के माध्यम से" से बचना {@literal @}Overrideक्योंकि javadoc जनरेटर "झुकाव" इस तथ्य के कारण है कि @ सीधे घुंघराले ब्रैकेट के बाद जाता है
• के सामने एक खाली स्थान हटाएं {@codeऔर {@literal, आंतरिक रिक्त स्थान की भरपाई के लिए और संरेखण रखने

javadoc कोड:

/** this methods adds a specific translator from one type to another type. `
  * i.e.
  * <pre>
  * <code>new BeanTranslator.Builder()
  *   .translate(
  *     new{@code Translator<String, Integer>}(String.class, Integer.class){
  *      {@literal @}Override
  *       public Integer translate(String instance) {
  *         return Integer.valueOf(instance);
  *       }})
  *   .build();
  * </code>
  * </pre>
  * @param translator
  */

के रूप में मुद्रित हो जाता है

new BeanTranslator.Builder()
  .translate(
    new Translator<String, Integer>(String.class, Integer.class){
      @Override
      public Integer translate(String instance) {
        return Integer.valueOf(instance);
      }})
  .build();

Comments

यह काम करता है, लेकिन मुझे चेतावनी मिलती है जब जावदोक इस चेतावनी को "चेतावनी: {@code} <कोड>" के भीतर चला रहा है

— शेन रोवेट

यह एक काम है, स्वीकृत उत्तर मेरे ग्रहण (4.6.2) में अच्छी तरह से काम नहीं करता है।

— एरिक वांग

मुझे आश्चर्य है कि यह सब क्यों आवश्यक है, मेरा इंटेलीज 13 और बाद में स्वीकृत उत्तर में कोड के साथ ठीक काम करता है। क्या यह सिर्फ एक ग्रहण मुद्दा है?

— bvdb

हां, मैंने इंटेलीज 11 और बाद में भी इस काम को ठीक देखा है। IntelliJ इसे सही ढंग से संभालती है। दुर्भाग्य से ग्रहण JavaDoc को सही तरीके से प्रस्तुत नहीं करता है (होवर स्टेट), और नई लाइनों और HTML विराम दोनों को अनदेखा करता है। मैं एक समाधान खोजने की कोशिश कर रहा हूं जो दोनों आईडीई में अच्छी तरह से काम करता है, क्योंकि वे आज उपयोग किए गए शीर्ष आईडीई में से दो हैं।

— माइकल एम

Answer 3

जावा स्रोत के पास इसके लिए बहुत सारे अच्छे उदाहरण हैं। यहाँ "String.java" के सिर से एक उदाहरण दिया गया है:

....
 * is equivalent to:
 * <p><blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <p><blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
...

Comments

सारांश में,<pre><blockquote>...</blockquote></pre>

— जिन क्वाँ

बल्कि<p><blockquote><pre> </pre></blockquote></p>

— मास्टरएक्सिलो

@JinKwon दुख की बात है कि यह हमेशा काम नहीं कर रहा है, मेरे कोड स्निपेट में नहीं :( शुरुआत के कामों में {@ कोड जोड़कर, भले ही समापन) तक नहीं

— पहुंचेगा

यह अधिकांश कोड के लिए काम करता है, लेकिन कोणीय कोष्ठक जैसे कि में नहीं बचता है List<String>। उसके लिए मैं उपयोग कर रहा हूं <pre>{@code ... }</pre>।

— डैनियल

Answer 4

<pre></pre>टैग के साथ अपने बहुस्तरीय कोड को संलग्न करें ।

Answer 5

आपको <pre></pre>लाइन ब्रेक के लिए टैग चाहिए , और {@code ... }जेनरिक के लिए उनके अंदर। लेकिन फिर इसे <generic>टैग के रूप में एक ही लाइन पर शुरुआती ब्रेस को रखने की अनुमति नहीं है , क्योंकि तब सब कुछ 1 लाइन पर फिर से प्रदर्शित किया जाएगा।

एक पंक्ति पर प्रदर्शित:

* ..
* <pre>
* {@code
* public List<Object> getObjects() {
*    return objects;
* }
* </pre>
* ..

लाइन ब्रेक के साथ प्रदर्शित:

* ..
* <pre>
* {@code
* public List<Object> getObjects() 
* {
*    return objects;
* }
* </pre>
* ..

एक और अजीब बात यह है कि जब आप समापन ब्रेस को चिपकाते हैं {@code, तो यह प्रदर्शित होता है:

* ..
* <pre>
* {@code
*   public List<Object> getObjects() 
*   {
*     return objects;
*   }
* }
* </pre>
* ..

आउटपुट:

public List<Object> getObjects() 
{
   return objects;
}
}

Comments

स्टैक ओवरफ्लो पर आपका स्वागत है। पदों में कोड को प्रारूपित करने के लिए, आप या तो इसे (एक अलग पैराग्राफ पर) चार स्थानों से उपसर्ग कर सकते हैं, या उन्हें बैकटिक्स (`` ...``) से घेर सकते हैं । आप की जरूरत नहीं है <code>और <pre>टैग। मैंने आपके जवाब को इस दिमाग में संपादित किया।

— पाओलो एबरमन

Answer 6

/**
 * <blockquote><pre>
 * {@code
 * public Foo(final Class<?> klass) {
 *     super();
 *     this.klass = klass;
 * }
 * }
 * </pre></blockquote>
 **/

• <pre/> लाइनों के संरक्षण के लिए आवश्यक है।
• {@code अपनी लाइन होनी चाहिए
• <blockquote/> सिर्फ इंडेंटेशन के लिए है।

public Foo(final Class<?> klass) {
    super();
    this.klass = klass;
}

---

JDK8 के साथ अद्यतन करें

उचित कोड के लिए न्यूनतम आवश्यकताएं हैं <pre/>और {@code}।

/**
 * test.
 *
 * <pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre>
 */

पैदावार

 <T> void test(Class<? super T> type) {
     System.out.printf("hello, world\n");
 }

और एक वैकल्पिक आसपास <blockquote/>एक इंडेंटेशन सम्मिलित करता है।

/**
 * test.
 *
 * <blockquote><pre>{@code
 * <T> void test(Class<? super T> type) {
 *     System.out.printf("hello, world\n");
 * }
 * }</pre></blockquote>
 */

पैदावार

     <T> void test(Class<? super T> type) {
         System.out.printf("hello, world\n");
     }

सम्मिलित करना <p>या के साथ आसपास के <p>और </p>पैदावार चेतावनी।

Answer 7

मैं निम्नलिखित स्निप के साथ अच्छी दिखने वाली HTML फाइलें उत्पन्न करने में सक्षम था, यह कोड 1 में दिखाया गया है।

 * <pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 *</pre>

(कोड 1)

कोड 1 छवि 1 में उत्पन्न javadoc HTML पेज में बदल गया, जैसा कि अपेक्षित था।

A-->B
 \
  C-->D
   \   \
    G   E-->F

(चित्र एक)

हालाँकि, NetBeans 7.2 में, यदि आप Alt + Shift + F (वर्तमान फ़ाइल को पुन: स्वरूपित करने के लिए) हिट करते हैं, तो कोड 1 कोड 2 में बदल जाता है।

 * <
 * pre>
 * {@code
 * A-->B
 *  \
 *   C-->D
 *    \   \
 *     G   E-->F
 * }
 * </pre>

(कोड 2)

जहां पहले <pre>अब दो लाइनों पर टूट गया है। कोड 2 उत्पन्न javadoc HTML फ़ाइल के रूप में चित्र 2 में दिखाया गया है।

< pre> A-->B \ C-->D \ \ G E-->F

(रेखा चित्र नम्बर 2)

ऑल्ट + शिफ्ट + एफ मारने के बाद भी स्टीव बी का सुझाव (कोड 3) सबसे अच्छा परिणाम देता है और अपेक्षित रूप में बना रहता है।

*<p><blockquote><pre>         
* A-->B
*  \
*   C-->D
*    \   \
*     G   E-->F
* </pre></blockquote>

(कोड 3)

कोड 3 का उपयोग उसी javadoc HTML आउटपुट का निर्माण करता है जैसा कि चित्र 1 में दिखाया गया है।

Answer 8

यहाँ मेरे दो सेंट हैं।

जैसा कि अन्य उत्तर पहले से ही बताते हैं, आपको <pre> </pre>संयोजन के साथ उपयोग करना चाहिए {@code }।

का उपयोग करें preऔर{@code}

• अपने कोड को अंदर लपेटना <pre>और </pre>अपने कोड को एक पंक्ति में ढहने से रोकता है;
• अपने कोड को लपेटना अंदर {@code }रोकता है <, >और बीच में सब कुछ गायब होने से। यह विशेष रूप से तब उपयोगी होता है जब आपके कोड में जेनरिक या लैम्ब्डा एक्सप्रेशन होते हैं।

एनोटेशन की समस्या

समस्या तब उत्पन्न हो सकती है जब आपके कोड ब्लॉक में एक एनोटेशन हो। ऐसा शायद इसलिए है क्योंकि जब @संकेत जावदोक लाइन की शुरुआत में दिखाई देता है, तो इसे जावदोक टैग की तरह माना जाता है @paramया @return। उदाहरण के लिए, इस कोड को गलत तरीके से पार्स किया जा सकता है:

/**
 * Example usage:
 *
 * <pre>{@code
 * @Override
 * public void someOverriddenMethod() {

मेरे मामले में उपरोक्त कोड पूरी तरह से गायब हो जाएगा।

इसे ठीक करने के लिए, लाइन को एक @संकेत के साथ शुरू नहीं करना चाहिए :

/**
 * Example usage:
 *
 * <pre>{@code  @Override
 * public int someMethod() {
 *     return 13 + 37;
 * }
 * }</pre>
 */

ध्यान दें कि चीजों को अगली पंक्तियों के साथ संरेखित करने के बीच @codeऔर दो रिक्त स्थान @Overrideहैं। मेरे मामले में (Apache Netbeans का उपयोग करके) इसे सही तरीके से प्रस्तुत किया गया है।

Answer 9

के बीच एक महत्वपूर्ण अंतर है <blockquote><pre>...और <pre>{@code....पूर्व जेनेरिक में प्रकार की घोषणाओं को छोड़ देगा, लेकिन बाद वाला इसे रखेगा।

E.g.: List<MyClass> myObject = null;List myObject = null;झगड़े के List<MyClass> myObject = null;साथ और दूसरे के साथ के रूप में प्रदर्शित करता है

Answer 10

यदि आप Android डेवलपर हैं, तो आप इसका उपयोग कर सकते हैं:

<pre class=”prettyprint”>

TODO:your code.

</pre>

जावा कोड के साथ अपने कोड को जावदोक में प्रिंट करने के लिए।

Comments

कृपया समझाएं: @code टैग की आवश्यकता वाले मुद्दों पर विचार करते हुए एंड्रॉइड के टूल को क्या काम करना चाहिए? और किस घटक को प्रीट्रिप्रिंट वर्ग को परिभाषित करना चाहिए? Android नियमित Javadoc का उपयोग करता है।

— noamtm

Xamarin / VS, Android Studio, या इससे कोई फर्क नहीं पड़ता?

— tyblu

@tyblu एंड्रॉइड स्टूडियो काम करता है, लेकिन Xamarin Studio / VS शायद काम नहीं करता। आपके पास एक कोशिश हो सकती है।

— ifeegoo

Answer 11

"कोड" को "पूर्व" से बदलने का प्रयास करें। HTML में प्री टैग टेक्स्ट को प्रीफ़ॉर्मेट के रूप में चिह्नित करता है और जैसे ही आप उन्हें टाइप करते हैं, सभी लाइनफ़ीड और स्पेस दिखाई देंगे।

Answer 12

मैंने अभी यहाँ Javadoc 1.5 संदर्भ पढ़ा है , और केवल कोड के साथ <और >अंदर संलग्न किया जाना चाहिए {@code ...}। यहाँ एक सरल उदाहरण है:

 /** 
 * Bla bla bla, for example:
 *
 * <pre>
 * void X() {
 *    List{@code <String>} a = ...;
 *    ...
 * }
 * </pre>
 *
 * @param ...
 * @return ...
 */
 .... your code then goes here ...

Answer 13

मैं अपना उदाहरण कोड <pre class="brush: java"></pre>टैग के साथ संलग्न करता हूं और प्रकाशित javadocs के लिए SyntaxHighlighter का उपयोग करता हूं । यह आईडीई को नुकसान नहीं पहुंचाता है और प्रकाशित कोड उदाहरणों को सुंदर बनाता है।

Comments

हाइलाइट से पूछा गया: stackoverflow.com/questions/1391614/…

— Ciro Santilli 郝海东 over over over 病

सिंटेक्स हाइलाइटर के साथ आपको स्क्रिप्ट को लोड करना होगा और सीएसएस को सही करना होगा। आश्चर्यजनक लग रहा है, लेकिन आपको आवश्यक स्क्रिप्ट और सीएसएस के लिए सही रास्ता रखना चाहिए। इसके अलावा, अगर ऑफ़लाइन उपयोग करना चाहते हैं, तो सही रास्तों से सावधान रहना चाहिए।

— एलेक्स बर्थ

Answer 14

जावा एसई 1.6 का उपयोग करते हुए, ऐसा लगता है कि सभी UPPERCASE PRE पहचानकर्ता जावदोक में ऐसा करने का सबसे अच्छा तरीका है:

/**
 * <PRE>
 * insert code as you would anywhere else
 * </PRE>
 */

ऐसा करने का सबसे सरल तरीका है।

जावाडॉक से एक उदाहरण जो मुझे java.awt.Event विधि से मिला है:

/**
 * <PRE>
 *    int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
 *    int offmask = CTRL_DOWN_MASK;
 *    if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
 *        ...
 *    }
 * </PRE>
 */

यह आउटपुट उत्पन्न करता है जो बिल्कुल नियमित कोड की तरह दिखता है, नियमित कोड स्पेसिंग और नई लाइनों के साथ बरकरार है।

Comments

यह मौजूदा उत्तरों में कुछ भी नहीं जोड़ता है।

— madth3

पागल 3, तुम सही हो। मुझे लगा कि मैंने कम बनाम UPPERCASE प्री मॉडिफायर का उपयोग करते समय एक अंतर देखा था, लेकिन दूसरी नज़र में, यह ऐसा नहीं लगता है। इस वेबपेज पर यह कैसे दिखाई देता है इसके साथ कुछ करना भी हो सकता है।

— यूजीन_सीडी-एडापको

HTML टैग में मामला संवेदनशील?

— जेसन

Answer 15

विज़ुअल स्टूडियो कोड में कम से कम, आप एक Javadoc टिप्पणी को ट्रिपल-बैकटिक्स में लपेटकर लाइन-ब्रेक का सम्मान करने के लिए बाध्य कर सकते हैं, जैसा कि नीचे देखा गया है:

/** ```markdown
 * This content is rendered in (partial) markdown.
 * 
 * For example, *italic* and **bold** text works, but [links](https://www.google.com) do not.
 * Bonus: it keeps single line-breaks, as seen between this line and the previous.
 ``` */