java Maven javadoc 插件 - 如何只包含某些类？

Maven javadoc plugin - how can I include only certain classes?

提问by Supertux

Using the Maven javadoc plugin you can exclude certain packages - but I have lots of packages and only a handful of classes I want to produce Javadoc for.

使用 Maven javadoc 插件，您可以排除某些包 - 但我有很多包，但我想要为其生成 Javadoc 的类只有少数。

Is there a way to include rather than exclude?

有没有办法包括而不是排除？

I would also like to do things on a class level rather than a package level as I have some classes in a package which need javadoc and some which don't.

我还想在类级别而不是包级别上做事情，因为我在包中有一些需要 javadoc 的类，而另一些则不需要。

采纳答案by Supertux

In the end I used the sourcepathconfiguration option to specify two packages containing the classes I wanted to Javadoc and gave classes in those packages that I didn't want to Javadoc default access. Setting the showconfiguration option to public allowed me to choose which classes Javadoc was produced for by setting there access to public. Full configuration below:

最后，我使用sourcepath配置选项指定了两个包含我想要 Javadoc 的类的包，并为那些包中的类提供了我不想 Javadoc 默认访问的类。将show配置选项设置为 public 允许我通过将访问权限设置为 public 来选择为哪些类生成 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>

However, this is essentially a workaround and I strongly agree with shek's comment that this should be an enchancement against the maven-javadoc-plugin as it is supported by the javadoc utility. http://jira.codehaus.org/browse/MJAVADOC

但是，这本质上是一种解决方法，我非常同意 shek 的评论，即这应该是对 maven-javadoc-plugin 的增强，因为它由 javadoc 实用程序支持。http://jira.codehaus.org/browse/MJAVADOC

回答by RCross

Since maven-javadoc-plugin version 2.9, you can do this in your configuration:

从 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>
  ....

... which would build a Javadoc site only including the mentioned classes.

...这将构建一个 Javadoc 站点，只包含提到的类。

回答by shek

Using the maven-javadoc-plugin, you cannot specify specific java classess (though you can with the javadoc utility, see below). However, via the the sourcepathconfiguration option for the javadoc:javadoc goal, you can configure specific packages. An example of this follows:

使用maven-javadoc-plugin，您不能指定特定的 java 类（尽管您可以使用 javadoc 实用程序，请参见下文）。但是，通过javadoc:javadoc 目标的sourcepath配置选项，您可以配置特定的包。一个例子如下：

<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>

In this example, all classes under the com.acme.foopackage (including subpackages) will have javadoc generated.

在这个例子中，com.acme.foo包下的所有类（包括子包）都会生成 javadoc。

It should be noted that this Maven plugin is simply a wrapper around Sun's javadoc utility. As such, most of the documentation and configuration for javadoc holds true for this plugin. See Sun's documentation on the javadoc sourcepath parameter.

应该注意的是，这个 Maven 插件只是一个围绕Sun 的 javadoc 实用程序的包装器。因此，javadoc 的大部分文档和配置都适用于此插件。请参阅 Sun 关于 javadoc sourcepath 参数的文档。

In an area where the maven-javadoc-plugin differs in functionality, Sun's documentation for the sourcepath parameter mentions that it is possible with the javadoc utility to generate javadoc for specific classes. This capability is not available with the maven-javadoc-plugin. An example of this is shown in Sun's documentation:

在 maven-javadoc-plugin 功能不同的地方，Sun 的 sourcepath 参数文档提到可以使用 javadoc 实用程序为特定类生成 javadoc。此功能不适用于 maven-javadoc-plugin。Sun 的文档中显示了一个示例：

  C:> cd C:\home\src\java\awt
  C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java

回答by udoline

It's simply, when you use the configuration tag <subpackages/>from Maven2-Plugin, e.g.:

很简单，当您使用<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>

回答by Rich Seller

As far as I know you can only filter at the package level. However Javadoc is only generated for public and protected types. If the types are default-scoped or private they won't have javadoc generated for them. Making them default-scoped means they are still visible to other types in the package.If you don't want javadoc, you probably don't want people to use those types, so this is probably a good scope to go for anyway.

据我所知，您只能在包级别进行过滤。然而，Javadoc 仅为公共和受保护类型生成。如果类型是默认范围或私有的，则不会为它们生成 javadoc。将它们设为默认范围意味着它们仍然对包中的其他类型可见。如果您不想要 javadoc，您可能不希望人们使用这些类型，因此无论如何这可能是一个很好的范围。

The excludePackageNames configuration allows wildcards. So as long as you have a package name convention that allows this you can exclude the majority of packages.

excludePackageNames 配置允许使用通配符。因此，只要您有允许这样做的包名称约定，您就可以排除大多数包。

Say you have these packages.

假设你有这些包。

com.foo
com.foo.api
com.foo.internal   
com.foo.internal.core
com.foo.internal.util
com.foo.internal.ui
com.foo.ui

and you only want to expose foo, foo.api and foo.ui, this pattern will work:

并且您只想公开 foo、foo.api 和 foo.ui，此模式将起作用：

<excludePackageNames>com.foo.internal.*:com.foo.bob</excludePackageNames>

You could alternatively move the offending types into separate packages, but this is not a good reason to do so.

您也可以将有问题的类型移动到单独的包中，但这不是这样做的充分理由。

What is the issue with generating javadoc for these types?

为这些类型生成 javadoc 有什么问题？