Используя плагин Maven javadoc, вы можете исключить определенные пакеты, но у меня много пакетов и только несколько классов, для которых я хочу создать Javadoc.
Есть ли способ включить, а не исключать?
Я также хотел бы сделать что-то на уровне класса, а не на уровне пакета, поскольку у меня есть некоторые классы в пакете, которые нуждаются в javadoc, а некоторые нет.
В конце я использовал параметр конфигурации sourcepath, чтобы указать два пакета, содержащие классы, которые я хотел использовать Javadoc, и дал классы в тех пакетах, которые я не хотел использовать для доступа по умолчанию Javadoc. Настройка параметра конфигурации show для общественности позволила мне выбрать, какие классы Javadoc были созданы, установив там доступ к публике. Полная конфигурация ниже:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<links>
<link>http://java.sun.com/j2se/1.5.0/docs/api/</link>
</links>
<source>1.5</source>
<show>public</show>
<doctitle>Foo API</doctitle>
<title>Foo API</title>
<bottom><![CDATA[Copyright notice]]></bottom>
<sourcepath>${basedir}/src/main/java/com/foo/api;${basedir}/src/main/java/com/bar/api</sourcepath>
</configuration>
</plugin>
Однако это по сути является обходным решением, и я категорически согласен с комментарием shek, что это должно быть преимуществом против maven-javadoc-плагина, поскольку оно поддерживается утилитой javadoc. http://jira.codehaus.org/browse/MJAVADOC
Так как maven-javadoc-plugin версии 2.9, вы можете сделать это в своей конфигурации:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9</version>
<configuration>
....
<sourceFileIncludes>
<include>Foo.java</include>
<include>Bar.java</include>
</sourceFileIncludes>
<sourcepath>${basedir}/src/main/java/path/to/foo-and-bar</sourcepath>
....
</configuration>
....
... который построил бы сайт Javadoc, включая упомянутые классы.
Используя maven-javadoc-plugin, вы не можете указать конкретную класс java (хотя вы можете использовать утилиту javadoc, см. ниже). Однако, используя опцию sourcepath для цели javadoc: javadoc, вы можете настроить определенные пакеты. Пример этого следует:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.5</version>
<configuration>
<charset>UTF-8</charset>
<docencoding>UTF-8</docencoding>
<docfilessubdirs>true</docfilessubdirs>
<links>
<link>http://java.sun.com/j2se/1.5.0/docs/api/</link>
</links>
<show>protected</show>
<source>1.5</source>
<sourcepath>${basedir}/src/main/java/com/acme/foo</sourcepath>
</configuration>
<reportSets>
<reportSet>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
</reportSets>
</plugin>
В этом примере все классы в пакете com.acme.foo (включая подпакеты) будут генерироваться javadoc.
Следует отметить, что этот плагин Maven представляет собой просто оболочку утилиту Sun javadoc. Таким образом, большая часть документации и конфигурации для javadoc имеет значение для этого плагина. См. Документацию Sun по параметру javadoc sourcepath.
В области, где maven-javadoc-plugin отличается функциональностью, документация Sun для параметра sourcepath указывает, что это возможно с помощью утилиты javadoc для generate javadoc для конкретных классов. Эта возможность недоступна с помощью maven-javadoc-plugin. Пример этого показан в документации Sun:
C:> cd C:\home\src\java\awt
C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java
Это просто, когда вы используете тег конфигурации <subpackages/> из Maven2-Plugin, например:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.7</version>
<configuration>
<sourceEncoding>ISO-8859-1</sourceEncoding>
<quiet>true</quiet>
<aggregate>true</aggregate>
<code>javadoc:aggregate</code>
<code>javadoc:test-aggregate</code>
<doclet>gr.spinellis.umlgraph.doclet.UmlGraphDoc</doclet>
<docletArtifact>
<groupId>gr.spinellis</groupId>
<artifactId>UmlGraph</artifactId>
<version>4.6</version>
</docletArtifact>
<additionalparam>
-inferrel -inferdep -quiet -hide java.*
-collpackages java.util.* -qualify
-postfixpackage -nodefontsize 9
-nodefontpackagesize 7
</additionalparam>
<subpackages>
de.interforum.gms.db.domain:de.interforum.sdr.db.domain
</subpackages>
</configuration>
<executions>
<execution>
<goals>
<goal>javadoc</goal>
<goal>test-javadoc</goal>
</goals>
<phase>site</phase>
<configuration>
<!-- Specific configuration for the given reports ... -->
</configuration>
</execution>
</executions>
</plugin>
Насколько я знаю, вы можете фильтровать только на уровне пакета. Однако Javadoc генерируется только для общедоступных и защищенных типов. Если типы имеют ограничения по умолчанию или частные, у них не будет генерироваться javadoc. Если они не используются по умолчанию, они все еще видны для других типов в пакете. Если вы не хотите javadoc, вы, вероятно, не хотите, чтобы люди использовали эти типы, поэтому, вероятно, это хороший выбор для всех.
Конфигурация excludePackageNames позволяет использовать подстановочные знаки. Поэтому, если у вас есть соглашение об имени пакета, которое позволяет это, вы можете исключить большинство пакетов.
Скажите, что у вас есть эти пакеты.
com.foo
com.foo.api
com.foo.internal
com.foo.internal.core
com.foo.internal.util
com.foo.internal.ui
com.foo.ui
и вы хотите только открыть foo, foo.api и foo.ui, этот шаблон будет работать:
<excludePackageNames>com.foo.internal.*:com.foo.bob</excludePackageNames>
Вы можете альтернативно переместить оскорбительные типы в отдельные пакеты, но это не является повод для этого.
В чем проблема с генерацией javadoc для этих типов?