4

Having configured maven-site-plugin and maven-javadoc-plugin (with doclava doclet), I'm trying to get proper JavaDocs on the site generated by mvn site. In my code I have sevaral JUnit test classes (located in src/test/java/my/package/*.java) which JavaDoc comments link the source classes (located in src/main/java/my/package/*.java). The problem is that when generating Test JavaDocs, javadoc cannot find where source classes documentation is located. I tried to tell javadoc where to find it by using links and offlineLinks configuration options of maven-javadoc-plugin (documented here), but with no luck. I'd like javadoc to generate relative links so that they are workable when viewing generated documentation offline (browsing from /path/to/project/target/site/index.html in a browser). I wouldn't like to disable Test JavaDocs generation

My pom.xml | An excerpt from mvn site output

Also, I'm a Java and Maven newbie

To clarify the question, here is an example. I have a test class GenerateATest residing in src/test/java/name/earshinov/PrefixCircuits/GenerateATest.java (sorry that comments are in Russian):

package name.earshinov.PrefixCircuits;
// imports skipped

/**
 * Тестирование алгоритма построения вспомогательных подсетей типа A,
 * реализованного в классе {@link name.earshinov.util.PrefixCircuitGenerator},
 * по отдельным случаям, описанным в оригинальной статье
 */
public class GenerateATest {
// ...

The linked class PrefixCircuitGenerator is in src/main/java/name/earshinov/PrefixCircuits/PrefixCircuitGenerator.java. After I run mvn site, I get JavaDocs for source classes at target/site/apidocs/index.html and Test JavaDocs at target/site/testapidocs/index.html. In GenerateATest documentation in Test JavaDocs I'd like to see the link leading to the documentation of PrefixCircuitGenerator in source classes JavaDocs. However, javadoc can't find PrefixCircuitGenerator I refer to, so it does not generate the link and the corresponding warning is visible in mvn site output:

[WARNING] /home/eugene/dev/java/PrefixCircuits-maven/src/test/java/name/earshinov/PrefixCircuits/GenerateATest.java:9: warning 101: Unresolved link/see tag "name.earshinov.util.PrefixCircuitGenerator" in name.earshinov.PrefixCircuits.GenerateATest

My aim is to (somehow) tell javadoc how to generate the link. Changing {@link name.earshinov.PrefixCircuits.PrefixCircuitGenerator} to {@link PrefixCircuitGenerator} does not change anything.

Community
  • 1
  • 1
Evgeny A.
  • 731
  • 2
  • 8
  • 19
  • First i would suggest to clean up your build to prevent any warnings during the site generation as stated in the output. Furthermore what kind of links don't work? Links to production code? – khmarbaise Sep 05 '11 at 06:14
  • @khmarbaise What do you mean by cleaning up the build? I get the same warnings after `mvn clean`. Regarding the links I need, I'll add an example to the topic – Evgeny A. Sep 05 '11 at 08:23
  • You get warnings about the maven-project-info-report-plugin cause you didn't define the version number of the maven-project-info-report-plugin in your build. – khmarbaise Sep 05 '11 at 08:37
  • @khmarbaise I did not use this plugin explicitly (it is probably a dependency of the site-plugin), so I did not want to include it in my POM only to define its version. Now I added the project-info-report-plugin to the list of the reporting plugins as, I assume, you recommend – Evgeny A. Sep 05 '11 at 08:49
  • You can tell javadoc where documentation for related classes is by using the `-link` parameter. I have no idea how this transfers to Maven, though. – Paŭlo Ebermann Sep 05 '11 at 13:14
  • @Paŭlo The `-link` parameter is controlled by the `links` configuration option of the javadoc plugin. I tried it without successs. It can be that I tried it in a wrong way, but we need a Maven or Maven&JavaDoc expert here – Evgeny A. Sep 05 '11 at 13:30

1 Answers1

0

Just got some time for experimentation. Seems that doclava doclet just does not support foreign documentation links (does not implement -link command line option). I discovered it by running javadoc from CLI. Probably javadoc plugin knows that the -link option is specific to the standard doclet, so it does not bother getting the value of this option from pom.xml and passing it to javadoc via command line arguments, if an alternative doclet is used. Hence no error is generated.

Evgeny A.
  • 731
  • 2
  • 8
  • 19