Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [tycho-user] javadoc - best practices

Thanks for the hint, Mickael. I've already tried to use the maven-javadoc-plugin. After looking at the GMF tooling pom, I noticed that it's not my missing maven knowledge: It seems as if the plugin is not correctly handled when defined in a "sub"-pom, according to the comment in GMF tooling's parent pom. Since I have the same project structure as the GMF tooling, it was easy for me to simply use their javadoc settings as well.

For people not familiar with the GMF tooling Javadoc solution: The maven-javadoc-plugin is included in the parent pom.xml as follows:

<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.8</version>
<configuration>
<minmemory>128m</minmemory>
<maxmemory>1g</maxmemory>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<goals>
<goal>aggregate</goal>
</goals>
<phase>generate-resources</phase>
<configuration>
<minmemory>128m</minmemory>
<maxmemory>1024m</maxmemory>
<reportOutputDirectory>doc/org.eclipse.gef3d.doc/reference</reportOutputDirectory>
<destDir>api</destDir>
<excludePackageNames>*.internal:*.internal.*:*.tests:*.tests.*:*.examples:*.examples.*</excludePackageNames>
</configuration>
</execution>
</executions>
</plugin>

Actually, the javadocs are created in the first mvn install run (at least in my case). However I see other problems with that solution:

1) Generating code into a non-target folder is not the best style, is it? Worse: The generated code is not deleted when the clean target is called.

2) Excluding packages may work for internal or example packages, however tests usually reside in packages using the same name as the classes under test (in order to access package visible members). So, these test classes cannot be excluded. Using the Eclipse test layout, it would be best to have a solution for ignoring the test plugins.

regarding 1)
I tried to generate the javadoc into some target folder, which works. However I haven't managed to add the generated javadoc then to the documentation bundle jar (at least not with the resource plugin). Is there a general solution to add (generated) artifacts to a bundle in case of <packaging>eclipse-plugin</packaging>, without putting these artifacts into non-target folders?

regarding 2)
Is there a way to let the maven-javadoc-plugin ignore bundles or classes?

Cheers,
Jens


Back to the top