Как я заставляю javadoc наследование работать на внешние API? (с Maven2)
Когда класс переопределяет конкретный метод или реализации и абстрактный метод, Javadoc автоматически наследован, если явно не перезаписано.
Или, по крайней мере, инструмент пытается сделать это. Кажется, что это не работает на связанные внешние API. Например, когда я в моей реализации кода java.util.Map, или что-то еще от JRE, javadocs не наследуются/копируются от JRE javadocs/apidocs.
В моем конкретном случае я пытаюсь настроить это в плагине Maven2 Javadoc, но это - то же, когда я выполняю javadoc инструмент CLI непосредственно.
Моя конфигурация плагина Maven2 Javadoc в настоящее время похожа на это:
Как упоминал @Stephen, исходный файл для унаследованного метода должен быть доступен и должен находиться по пути, указанному в -sourcepath . Это объясняется в документации инструмента Javadoc:
Инструмент Javadoc имеет возможность
копировать или "наследовать" комментарии метода в
классы и интерфейсы под
следующие два обстоятельства.
Конструкторы, поля и вложенные
классы не наследуют комментарии к документам.
Автоматически наследовать комментарий для заполнения отсутствующего текста - Когда основной
описание или @return ,
@param или @throws тег отсутствует
из комментария к методу Javadoc
инструмент копирует соответствующий основной
описание или комментарий тега из
метод, который он переопределяет или реализует (если
любой) по алгоритму
ниже.
В частности, когда тег @param для определенного
параметр отсутствует, тогда комментарий
для этого параметра копируется из
метод дальше по наследству
иерархия. Когда тег @throws для
конкретное исключение отсутствует,
Тег @throws копируется только в том случае, если
объявляется исключение.
Такое поведение отличается от версии 1.3 и более ранних, где
наличие какого-либо основного описания или
тег предотвратит все комментарии от
наследуется.
Явное наследование комментария с тегом {@ inheritDoc} - Вставьте
встроенный тег {@ inheritDoc} в
основное описание метода или @return ,
@param или @throws комментарий к тегу -
соответствующий унаследованный основной
описание или комментарий тега копируется
в это место.
Исходный файл для унаследованного
метод должен быть только на пути
указывается -sourcepath для
комментарий документа на самом деле
доступно для копирования. Ни класс
и его пакет не нужно передавать в
в командной строке. Это контрастирует
с 1.3.x и более ранними версиями, где
класс должен быть задокументирован
class
Таким образом, вам придется использовать необязательный параметр конфигурации подключаемого модуля javadoc (который по умолчанию содержит исходные коды проекта).
Кстати, - это что-то еще, используются для добавления перекрестных ссылок на внешние проекты. И на самом деле их не следует использовать для JDK. Из Настройка ссылок :
Начиная с версии 2.6, будет добавлена ссылка Javadoc API, в зависимости от версии JDK, используемой вашим проектом. Версия Javadoc API определяется по значению параметра в org.apache.maven.plugins: maven-compiler-plugin (определено в $ {project.build.plugins} или в $ {project.build.pluginManagement} ), или вычисляется с помощью исполняемого файла Javadoc Tool.Если вы хотите пропустить эту ссылку, вам необходимо настроить на false .
Примечание: , если вы используете неподдерживаемый JDK, например 7.0, вы можете добавить его URL-адрес Javadoc API, используя параметр , то есть :
Если вы настроили уровень 1.6 источника в подключаемом модуле компилятора, перекрестные ссылки на Java API просто работают (ссылки указывают на http://download.oracle.com/javase/6 / docs / api / ) для Java API добавить нечего.
Ни то, ни другое не работает у меня. Мне пришлось добавить раздел ссылок, чтобы перекрестные ссылки работали.
Странно. Вы действительно указали уровень компилятора источника , как описано в документации? На всякий случай вот что у меня работает:
<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>
Я не могу дать вам окончательного ответа, но я думаю, что недостающий элемент в головоломке состоит в том, что утилита javadoc должна иметь возможность найти источник код соответствующих внешних API для работы наследования javadoc.
