كيف أجعل الميراث جافادوك يعمل لواجهة برمجة التطبيقات الخارجية؟ (مع Maven2)

Question

عندما يتجاوز الفصل طريقة أو طريقة ملموسة وطريقة تجريدية ، يتم توريث Javadoc تلقائيًا ما لم يتم الكتابة بشكل صريح.

أو على الأقل الأداة تحاول القيام بذلك. يبدو أنه لا يعمل لصالح واجهات برمجة التطبيقات الخارجية المرتبطة. على سبيل المثال ، عندما أقوم بتنفيذ الكود الخاص بي java.util.Map, ، أو أي شيء آخر من JRE ، لا يتم موروثة/نسخ Javadocs من JRE Javadocs/Apidocs.

في حالتي المحددة ، أحاول تكوين هذا في البرنامج المساعد Maven2 Javadoc ، لكنه هو نفسه عندما أقوم بتشغيل أداة Javadoc CLI مباشرة.

يبدو تكوين المكون الإضافي Maven2 Javadoc حاليًا مثل هذا:

<reporting>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.7</version>
      <configuration>
        <stylesheet>maven</stylesheet>
        <links>
          <link>http://download.oracle.com/javase/6/docs/api</link>
        </links>
      </configuration>
    </plugin>
  </plugins>
</reporting>

أي مؤشرات حول كيفية جعل هذا العمل؟

Answer 1

كما ذكر stephen ، يجب أن يكون الملف المصدر للطريقة الموروثة متاحًا ويجب أن يكون على المسار المحدد بواسطة -sourcepath. تم شرح ذلك في وثائق أداة Javadoc:

النسخ التلقائي لتعليقات الطريقة

تتمتع أداة Javadoc بالقدرة على نسخ أو "الوراثة" لتعليقات طريقة في الفصول والواجهات في ظل الظروفتين التاليتين. لا يرث المنشئون والحقول والفصول المتداخلة تعليقات DOC.

• يرث التعليق تلقائيًا لملء النص المفقود - عندما الوصف الرئيسي, ، أو @return, @param أو @throws العلامة مفقودة من تعليق الطريقة ، تقوم أداة Javadoc بنسخ الوصف الرئيسي المقابل أو تعليق العلامة من الطريقة التي يتجاوزها أو تنفذها (إن وجدت) ، وفقًا للخوارزمية أدناه.

  بشكل أكثر تحديدا ، عندما أ @param العلامة لمعلمة معينة مفقودة ، ثم يتم نسخ التعليق على تلك المعلمة من الطريقة إلى زيادة التسلسل الهرمي للميراث. عندما @throws علامة استثناء معين مفقود ، @throws يتم نسخ العلامة فقط إذا تم الإعلان عن هذا الاستثناء.

  يتناقض هذا السلوك مع الإصدار 1.3 وما قبله ، حيث سيمنع وجود أي وصف أو علامة رئيسية جميع التعليقات من الوراثة.

• يرث التعليق بشكل صريح مع {@inheritDoc} بطاقة شعار - أدخل العلامة المضمنة {@inheritDoc} في الطريقة الوصف الرئيسي أو @return, @param أو @throws تعليق العلامة - يتم نسخ الوصف الرئيسي الموروثة أو تعليق العلامة في تلك البقعة.

يجب أن يكون الملف المصدر للطريقة الموروثة فقط على المسار المحدد بواسطة -sourcepath لتعليق DOC ليكون متاحًا بالفعل للنسخ. لا يحتاج الفصل ولا الحزمة إلى تمريره على سطر الأوامر. يتناقض هذا مع 1.3.x والإصدارات السابقة ، حيث كان يجب أن يكون الفصل فئة موثقة

لذلك يجب عليك استخدام <sourcepath> معلمة التكوين الاختيارية من المكون الإضافي Javadoc (الذي يحتوي على مصادر المشروع افتراضيًا).

---

بالمناسبة، <links/> شيء آخر ، <links/> تستخدم لإضافة روابط مرجعية متقاطعة إلى المشاريع الخارجية. وفي الواقع ، لا ينبغي استخدامها في JDK. من عند تكوين الروابط:

منذ 2.6 ، سيتم إضافة رابط Javadoc API ، اعتمادًا على إصدار JDK الذي يستخدمه مشروعك. تم اكتشاف إصدار API Javadoc من قيمة <source/> المعلمة في org.apache.maven.plugins:maven-compiler-plugin (المعرفة في ${project.build.plugins} أو في ${project.build.pluginManagement}) ، أو يتم حسابها عبر أداة javadoc قابلة للتنفيذ. إذا كنت تريد تخطي هذا الرابط ، فأنت بحاجة إلى التكوين <detectJavaApiLink/> ل false.

ملحوظة: إذا كنت تستخدم JDK غير مدعوم مثل 7.0 ، فيمكنك إضافة عنوان URL لـ Javadoc API باستخدام <javaApiLinks/> المعلمة ، أي:

<configuration>
  <javaApiLinks>
    <property>
      <name>api_1.7</name>
      <value>http://download.java.net/jdk7/docs/api/</value>
    </property>
  </javaApiLinks>
  ...
</configuration>

تشير إلى <links/> المعلمة لمزيد من المعلومات.

على افتراض أنك قمت بتكوين 1.6 source المستوى في المكون الإضافي للمترجم ، تعمل روابط المراجع المتقاطعة إلى Java API فقط (تشير الروابط إلى http://download.oracle.com/javase/6/docs/api/) ، لا يوجد شيء لإضافته إلى Java API.

---

لا يعمل خارج الصندوق بالنسبة لي. اضطررت إلى إضافة قسم الروابط لجعل العمل المرجعية المتقاطعة.

عجيب. هل قمت بالفعل بتحديد الشكوى source مستوى موثق؟ فقط في حال ، إليك ما يناسبني:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
      <source>1.6</source>
      <target>1.6</target>
    </configuration>
  </plugin>
  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.7</version>
    <configuration>
      <!-- No need for this -->
      <!--
      <javaApiLinks>
        <property>
          <name>api_1.6</name>
          <value>http://download.oracle.com/javase/6/docs/api/</value>
        </property>
      </javaApiLinks>
      -->
      <links>
        <link>http://commons.apache.org/dbcp/apidocs/</link>
        <link>http://commons.apache.org/fileupload/apidocs/</link>
      </links>
    </configuration>
  </plugin>

Answer 2

لا أستطيع أن أعطيك إجابة محددة ، لكنني أعتقد أن القطعة المفقودة في اللغز هي أن javadoc يجب أن تكون الأداة المساعدة قادرة على ذلك ابحث عن رمز المصدر من واجهات برمجة التطبيقات الخارجية ذات الصلة لميراث Javadoc للعمل.

Answer 3

كان لدي سؤال مماثل حول Stackoverflow الذي ساعدني في حل هذه المشكلة بشكل أفضل من الإجابة المقبولة لهذا البحث: Maven-javadoc-plugin و erneritdoc لفصول Java API الأساسية

ملخص:من أجل وراثة Javadoc من فصول Java Core ، تحتاج إلى فك مصادرها وإدراجها في بناء Javadoc. يتم توفير مصادر الطبقات الأساسية Java في أ src.zip ملف داخل JDK Distro.