Как сделать работу наследования Javadoc для внешних API? (с Maven2)

Question

Когда класс переопределяет бетонный метод или орудий и абстрактный метод, Javadoc автоматически унаследован, если явно не перезаписывается.

Или, по крайней мере, инструмент пытается сделать это. Кажется, это не работает для связанных внешних API. Например, когда я в моем коде реализую 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 имеет возможность копировать или «наследовать» метод комментариев в классах и интерфейсах при следующих двух обстоятельствах. Конструкторы, поля и вложенные классы не наследуют документы.

• Автоматически наслеживать комментарий, чтобы заполнить отсутствующий текст - Когда Основное описание, или @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 будут добавлены ссылка API JAVADOC, в зависимости от версии JDK, используемой вашим проектом. Версия API Javadoc обнаруживается из стоимости <source/> параметр в org.apache.maven.plugins:maven-compiler-plugin (Определяется в ${project.build.plugins} или внутри ${project.build.pluginManagement}) или вычисляется через исполняемый файл Javadoc Tool. Если вы хотите пропустить эту ссылку, вам нужно настроить <detectJavaApiLink/> к false.

Примечание: Если вы используете неподдерживаемый JDK, как 7.0, вы можете добавить свой URL API Javadoc, используя <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.orcle.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 Утилита должна быть в состоянии Найти исходный код соответствующих внешних API для наследования Javadoc на наследство.

Answer 3

У меня был подобный вопрос в Stackoverflow, который помог мне решить эту проблему лучше, чем принятый ответ на этот квест: Maven-javadoc-plugin и inheritdoc для ядных классов Java API

Резюме:Чтобы унаследовать Javadoc от Java Core Cornal, вам нужно расстегнуть их источники и включить их в сборку Javadoc. Источники классов ядных классов Java предоставляются в src.zip Файл в JDK DISTRO.