Re: [tycho-user] javadoc - best practices

["Jens v.P." <eclipse-mailinglist@xxxxxxxxx>]

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