मावेन का उपयोग करते समय सख्त जावा 8 जावाडॉक के आसपास कैसे काम करें

Question

आपको जल्दी पता चलेगा कि JDK8 जब जावदोक में आता है तो (डिफ़ॉल्ट रूप से) बहुत अधिक सख्त होता है। ( लिंक - अंतिम बुलेट बिंदु देखें)

यदि आप कभी कोई जावदोक उत्पन्न नहीं करते हैं, तो निश्चित रूप से आप किसी भी समस्या का अनुभव नहीं करेंगे, लेकिन मावेन रिलीज प्रक्रिया जैसी चीजें और संभवतः आपके सीआई बिल्ड अचानक विफल हो जाएंगे जहां उन्होंने जेडडीके 7 के साथ ठीक काम किया है। कुछ भी जो Javadoc टूल के निकास मान की जांच करता है, अब विफल हो जाएगा। JDK8 की warningsतुलना में JDK8 Javadoc शायद अधिक क्रियात्मक है, लेकिन यहाँ ऐसा नहीं है। हम बात कर रहे हैं errors!

यह सवाल मौजूद है कि इसके बारे में क्या किया जाए। सबसे अच्छा तरीका क्या है? क्या इन त्रुटियों को स्रोत कोड फ़ाइलों में एक बार और सभी के लिए तय किया जाना चाहिए? यदि आपके पास एक विशाल कोड आधार है तो यह बहुत काम हो सकता है। क्या अन्य विकल्प मौजूद हैं?

आपको उन कहानियों के साथ टिप्पणी करने का भी स्वागत है जो अब विफल हो जाती हैं जो पहले गुजरती थीं।

अब जो असफलता की डरावनी कहानियां

wsimport उपकरण

wsimportउपकरण वेब सेवा उपभोक्ताओं को बनाने के लिए एक कोड जनरेटर है। यह JDK में शामिल है। यहां तक ​​कि अगर आप wsimportJDK8 से उपकरण का उपयोग करते हैं, तो यह स्रोत कोड का उत्पादन करेगा जो कि JDK8 से javadoc संकलक के साथ संकलित नहीं किया जा सकता है ।

@ ताथोर टैग

मैं 3-4 साल पुराना सोर्स कोड फाइल खोल रहा हूं और इसे देख रहा हूं:

/**
 * My very best class
 * @author John <[e-mail]> 
 */

यह अब <चरित्र के कारण विफल हो जाता है। कड़ाई से यह कहना उचित है, लेकिन बहुत क्षमाशील नहीं है।

HTML टेबल

आपके Javadoc में HTML टेबल्स? इस मान्य HTML पर विचार करें:

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

यह अब त्रुटि संदेश के साथ विफल हो जाता है no summary or caption for table। एक त्वरित सुधार इस तरह करना है:

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

लेकिन क्यों यह जावदोक उपकरण मुझे मारता है से रोकने के लिए एक विश्व त्रुटि है ??

चीजें जो अब अधिक स्पष्ट कारणों के लिए विफल हो जाती हैं

1. अमान्य लिंक, उदा {@link notexist}
2. विकृत HTML, उदा always returns <code>true<code> if ...

अपडेट करें

लिंक:

स्टीफन कोलबोर्न द्वारा इस विषय पर उत्कृष्ट ब्लॉग ।

Comments

यह ब्लॉग दिखाता है कि इसे कैसे बंद किया जा सकता है: blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

— हिमांशु भारद्वाज

आप इसे संकलन के दौरान डॉक्स की जांच करने के लिए कहने के लिए -Xdoclintभी उपयोग कर सकते हैं javac...

— होल्गर

@HimanshuBhardwaj। स्टीफन कोलेबॉर्न के ब्लॉग से जुड़ने के लिए धन्यवाद। इस विषय पर मैंने अब तक जो सबसे अच्छा टुकड़ा पढ़ा है!

— पेटेर

इसके अतिरिक्त "त्रुटियों" में से एक भी गलत है: '>' का बुरा उपयोग - '- यह गलत है,'> 'XML में पूरी तरह से स्वीकार्य है,']] के विशिष्ट अनुक्रम को छोड़कर> '' जिसे स्वीकार नहीं किया गया है (एक चरस से बच जाना चाहिए)। सुविधा के लिए केवल '<' बच जाना चाहिए, '>' में एमनेमिक (gt) है, लेकिन इसका उपयोग पूरी तरह से वैकल्पिक है।

— स्टैक्समैन

मुझे आश्चर्य है कि HTML 5 के बजाय HTML 4 अनुपालन के साथ क्या है। व्यक्तिगत रूप से, मैं एक साधारण मार्कअप भाषा पसंद करूंगा क्योंकि मुझे स्रोत कोड पढ़ना है और न केवल सुंदर आउटपुट; और कम से कम मेरे लिए HTML की मानव-पठनीयता बहस का विषय है।

— डैनियल

Answer 1

अभी के लिए, सबसे आसान तरीका है कि मैं कड़ी मेहनत से जावा 8 जावाडॉक के आसपास काम करना जानता हूं, जब मावेन इसका उपयोग कर इसे निष्क्रिय कर रहा है।

चूंकि पैरामीटर -Xdoclint:noneकेवल जावा 8 में मौजूद है, इस पैरामीटर को परिभाषित करना किसी अन्य जावा के लिए बिल्ड को तोड़ता है। इसे रोकने के लिए, हम एक प्रोफ़ाइल बना सकते हैं जो केवल जावा 8 के लिए सक्रिय होगी, यह सुनिश्चित करते हुए कि जावा संस्करण की परवाह किए बिना हमारा समाधान काम करता है।

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

बस उसे अपने पोम में जोड़ें और आप जाने के लिए अच्छे हैं।

---

Maven-javadoc-plugin 3.0.0 उपयोगकर्ताओं के लिए:

बदलने के

<additionalparam>-Xdoclint:none</additionalparam>

द्वारा

<doclint>none</doclint>

धन्यवाद @banterCZ!

Comments

मैं इसे सबसे संभावित समाधान के रूप में स्वीकार करूंगा जिसे हम में से अधिकांश लागू करेंगे। मुझे <activation>हिस्सा पसंद है । लेकिन मैं चाहता हूं कि कोई व्यक्ति एक ऐसा उपकरण लेकर आए, जो उन कई स्रोत फ़ाइलों के माध्यम से जा सकता है और डेवलपर को त्रुटियों को ठीक करने में सहायता कर सकता है ... बजाय केवल डॉकलाइन को बंद करने के।

— पेट्र

इस समाधान का उपयोग करने से सावधान रहें यदि आप एक ही समय में एक और प्रोफ़ाइल पर डिफ़ॉल्ट रूप से सक्रिय होने का भरोसा करते हैं (सक्रिय बायफ़ॉल्ट = सच का उपयोग करके)।

— mwhs

@peterh: पूरी तरह से सब कुछ का दस्तावेजीकरण करने का कोई मतलब नहीं है, यह एक बेकार डुप्लिकेटेड काम है, स्वच्छ कोड सिद्धांतों द्वारा यह केवल वही दस्तावेज करने की सिफारिश की जाती है जो स्पष्ट नहीं है, और सार्वजनिक एपीआई।

— डैनियल हैरी

यह maven-javadoc-plugin संस्करण 3.0.0 के साथ काम नहीं करता है। मुझे बनाने के लिए संस्करण 3.0.0-M1 पर वापस जाना पड़ा -Xdoclint: कोई काम नहीं।

— मेह्रद सदेघ

@MehradSadegh maven-javadoc- प्लगइन संस्करण 3.0.0 के लिए बस <additionalparam>-Xdoclint:none</additionalparam>द्वारा प्रतिस्थापित<doclint>none</doclint>

— banterCZ

Answer 2

यदि आप मावेन जेवाडॉक प्लगइन का उपयोग कर रहे हैं, तो आप failOnErrorइसे किसी भी HTML त्रुटियों को खोजने से रोकने के लिए विकल्प का उपयोग कर सकते हैं:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

या आप सख्त HTML विकल्पों को पूरी तरह से निष्क्रिय कर सकते हैं:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

अधिक जानकारी के लिए ।

Comments

हम्म। इन समाधानों के साथ समस्या यह है कि अगर आप इसे JDK8 Javadoc के साथ सोचते हैं तो आप त्रुटियों पर विफल नहीं होना चाहेंगे जबकि JDK7 Javadoc के साथ आप करते हैं। तो इस कारण से मुझे सबसे अच्छा -Xdoclintविकल्प पसंद है। आशा है कि यह एक JDK7 Javadoc के साथ निष्पादित होने पर चुपचाप नजरअंदाज कर दिया जाएगा?

— पेट्र

आप जावा संस्करण पर रखे मावेन प्रोफाइल के माध्यम से विकल्प को सशर्त रूप से लागू कर सकते हैं…?

— डोनल फैलो

नहीं, JDK7 के साथ यह javadoc के साथ विफल रहता है: त्रुटि - अमान्य ध्वज: -Xdoclint: कोई नहीं (अच्छा काम Oracle)।

— जियोवन्नी टोराल्डो

Answer 3

चूंकि maven-javadoc-plugin के संस्करण 3.0.0 में doclint को समर्पित XML टैग के माध्यम से कॉन्फ़िगर किया गया है

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>

Answer 4

मुझे @ ThiagoPorciúncula का समाधान पसंद है लेकिन यह मेरे लिए बहुत दूर नहीं गया।

मेरे पास आमतौर पर पहले से ही javadoc प्लगइन additionalparamसेट है जो प्रोफ़ाइल द्वारा ओवरराइड नहीं किया जा रहा था। इसके कारण मुझे यह करना पड़ा:

• disableDoclintडिफ़ॉल्ट रूप से खाली होने के लिए एक संपत्ति सेट करें ।
• यदि java> = 8 में, disableDoclintगुण होने के लिए सेट करें-Xdoclint:none
• ${disableDoclint} in theअतिरिक्तपरम section of theमावेन-जावादोक-प्लगइन का उपयोग करें ।

यह अच्छी तरह से काम करने लगता है।

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

फिर नीचे मैं ${disableDoclint}उस additionalparamखंड में वैकल्पिक चर का उपयोग कर सकता हूं जिसे मैंने पहले ही परिभाषित किया था।

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
    </configuration>
</plugin>

यह जावा 8 के तहत काम करता है लेकिन जावा 7 के तहत वाक्यविन्यास त्रुटियों का कारण नहीं बनता है। वू हू!

Answer 5

ध्यान दें कि त्रुटि के लिए no summary or caption for table, <table summary="">अब और काम नहीं करेगा। यदि आपकी स्थिति ऐसी है, तो <caption>अपनी तालिका में एक तत्व जोड़ें , जैसे:

<table>
    <caption>Examples</caption>
    ...
</table>

उम्मीद है कि इससे वहां किसी को मदद मिलेगी। जब तक मुझे यह पता चला मुझे इसमें कुछ समय लगा।

Comments

JDK का क्या संस्करण? यह सुनिश्चित करने के लिए कि <table summary="">ट्रिक अभी भी JDK8 पर काम करती है। (बस jdk1.8.0_201 पर परीक्षण)

— peterh

@peterh मैंने jdk 11.

— जेरोनिमो बैक

यह अप-टू-डेट उत्तर है। summary="..."विशेषता HTML5 (JDK 11 javadoc के लिए डिफ़ॉल्ट आउटपुट) के साथ समर्थित नहीं है। यह JDK 8.

— kap