Operating System: All
Platform: All

David Suarez and I were chatting about this on (private) IRC again today - plan:

It's best to start exploring this in a simple context - we choose odlparent & infrautils.

So the first goal would be to spend some time to figure out how to get a single ODL project (as in Git repo) build to easily produce a nice JavaDoc (and just the JavaDoc HTML, but not and without having to go through that useless "Maven site"). And not for just 1 artifact (single POM) but an entire project, combined... let us try to achieve that even just on odlparent itself (which has very little actual Java code), for starters.

Then in a 2nd step, goal is to another proposed change to infrautils which does the same for intrautils, without having anything copy/pasted, but inherited the required Maven magic from odlparent.

We would want to see having the JD working between artifacts belonging to the same project; say e.g. the JD of https://github.com/opendaylight/infrautils/blob/master/ready/impl/src/main/java/org/opendaylight/infrautils/ready/internal/SystemReadyImpl.java should link to the JD of SystemReadyMonitor, which is in the ready/api.

Then in the next step, we would want working links to external JD .. I expect there will be a way to, in odlparent, fix the URL of JD of all external libs (for all those which we "support" in odlparent by a dependencyManagement). So say e.g. in the JD of SystemReadyImpl you should get a link to BundleContext (osgi.org) as well as BundleService (karaf.apache.org).

Finally, as a 3rd req, let's also figure out how to get a link from say some netvirt JD to a genius util JD. I would do this without hard-coded fixed absolute http links, but based on the assumption that the JD of projects can be reached via relative ../.. kind of path.

I've been researching a little in the odlparent configuration we have currently and I found that we can generate a proper JavaDoc at different levels by just using the javadoc:aggregate goal. The HTML Javadoc is generated in the default directory ./target/site/apidocs.

I have tested both in infrautils and odlparent projects and it works. As expected, when the goal is used at module level, e.g. counters-impl, the JavaDocs includes only the source for that module, but if we execute it at the counter level we have the JD for the counters-api and the counters-impl as well. If we want to generate the JD for the whole infrautils project we just need to invoke it at that level: mvn javadoc:aggregate.

Summarizing, I'd say that the first and second steps are done without changing anything.

We no longer build sites and javadoc:aggregate has the downside of running project build twice. An alternative is presented here: https://github.com/opendaylight/yangtools/blob/master/docs/pom.xml