7

クラスが具象メソッドまたは実装および抽象メソッドをオーバーライドする場合、明示的に上書きしない限り、Javadoc は自動的に継承されます。

または、少なくともツールはこれを実行しようとします。リンクされた外部 API では機能しないようです。たとえば、コードで実装するjava.util.Map場合、またはJREから何か他のものを実装すると、Javadocは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>

これを機能させる方法についての指針はありますか？

4

3 に答える 3

6

@Stephen が述べたように、継承されたメソッドのソース ファイルは利用可能である必要があり、 で指定されたパス上にある必要があります-sourcepath。これについては、Javadoc ツールのドキュメントで説明されています。

メソッドコメントの自動コピー

Javadoc ツールには、次の 2 つの状況下で、クラスおよびインターフェースのメソッド コメントをコピーまたは「継承」する機能があります。コンストラクター、フィールド、およびネストされたクラスはドキュメント コメントを継承しません。

  • 欠落しているテキストを埋めるためにコメントを自動的に継承する-主な説明、 または@return、 @paramまたは@throwsタグがメソッドのコメントから欠落している場合、Javadoc ツールは、対応する主な説明またはタグのコメントを、オーバーライドまたは実装するメソッド (存在する場合) からコピーします。以下のアルゴリズム。

    より具体的には@param、特定のパラメーターのタグが欠落している場合、そのパラメーターのコメントが継承階層のさらに上のメソッドからコピーされます。特定の例外のタグ@throwsが欠落している @throws場合、その例外が宣言されている場合にのみタグがコピーされます。

    この動作は、メインの説明またはタグが存在するとすべてのコメントが継承されないバージョン 1.3 以前とは対照的です。

  • {@inheritDoc}タグ付きのコメントを明示的に継承する{@inheritDoc}-メソッドのメインの説明またはタグ コメントにインライン タグを@return挿入 @paramします@throws。対応する継承されたメインの説明またはタグ コメントがその場所にコピーされます。

-sourcepath継承されたメソッドのソース ファイルは、ドキュメント コメントを実際にコピーできるようにするために、 で指定されたパス上にあるだけで済みます。クラスもそのパッケージも、コマンド ラインで渡す必要はありません。これは、クラスが文書化されたクラスでなければならなかった 1.3.x 以前のリリースとは対照的です。

<sourcepath>そのため、javadoc プラグイン (デフォルトでプロジェクトのソースを含む)のオプションの構成パラメーターを使用する必要があります。

ところで、外部プロジェクトへの相互参照リンクを追加するために使用される<links/>ものは他にもあります。<links/>実際には、JDK には使用しないでください。リンクの構成から:

2.6 以降、プロジェクトで使用されている JDK バージョンに応じて、Javadoc API リンクが追加されます。Javadoc API のバージョンは、(または で 定義されている) の<source/>パラメータの値から検出されるか、Javadoc ツール実行可能ファイルを介して計算されます。このリンクをスキップする場合は、 に設定する必要があります。org.apache.maven.plugins:maven-compiler-plugin${project.build.plugins}${project.build.pluginManagement}<detectJavaApiLink/>false

注: 7.0 などのサポートされていない JDK を使用している場合は、次の<javaApiLinks/>パラメーターを使用してその Javadoc API URL を追加できます。

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

詳細については、<links/>パラメーターを参照してください。

コンパイラ プラグインで1.6 レベルを構成したと仮定すると、Java API への相互参照リンクは正常に機能し (リンクはhttp://download.oracle.com/javase/6/docs/api/sourceを指します)、追加するものは何もありません。 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>
于 2010-08-04T04:45:03.070 に答える
1

決定的な答えを出すことはできませんが、パズルに欠けているピースは、ユーティリティがjavadoc 継承を機能させるために関連する外部 API のソース コードjavadocを見つけることができる必要があるということだと思います。

于 2010-08-04T00:27:13.967 に答える
0

StackOverflow で同様の質問があり、この質問の受け入れられた回答よりもこの問題を解決するのに役立ちました: maven-javadoc-plugin and inheritDoc for Java API core classes

概要: Java コア クラスから Javadoc を継承するには、それらのソースを解凍して Javadoc ビルドに含める必要があります。Java コア クラスのソースはsrc.zip、JDK ディストリビューション内のファイルで提供されます。

于 2016-08-02T05:39:29.800 に答える