https://jira.opendaylight.org This file is an XML representation of an issue en-us 8.20.10 820010 22-06-2022 https://jira.opendaylight.org/browse/ODLPARENT-70 odlparent <p>based on discussions rovarga, zxiiro and I just had on IRC:</p> <p>current limitations of <a href="https://nexus.opendaylight.org/content/sites/site/" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/site/</a> "include but are not limited to" :</p> <ul> <li>nexus hosted JavaDoc is not Google web search engine spider indexed</li> </ul> <ul> <li>too many clicks to go from root to JavaDoc of 1 class; mvn site more distracting and not helpful in this context</li> </ul> <ul> <li>linking between classes of artefacts within projects and cross projects broken (e.g. <a href="https://nexus.opendaylight.org/content/sites/site/org.opendaylight.yangtools/carbon/yang-model-util/apidocs/org/opendaylight/yangtools/yang/model/util/AbstractSchemaContext.html" class="external-link" target="_blank" rel="nofollow noopener">https://nexus.opendaylight.org/content/sites/site/org.opendaylight.yangtools/carbon/yang-model-util/apidocs/org/opendaylight/yangtools/yang/model/util/AbstractSchemaContext.html</a>)</li> </ul> <p>as the first step to get real JavaDoc for ODL, we'd need a new odlparent Maven Profile / Parent / whatever-it-takes to be able to build a JavaDoc site for a given project, across all artefacts of a project.</p> <p>Operating System: All<br/> Platform: All</p> ODLPARENT-70

New odlparent Maven Profile / Parent / whatever-it-takes to be able to build a JavaDoc site

Improvement Resolved Won't Do Unassigned Michael Vorburger Tue, 28 Feb 2017 20:41:30 +0000 Tue, 12 Mar 2019 15:27:28 +0000 Tue, 12 Mar 2019 15:27:28 +0000 General 0 5 <p>David Suarez and I were chatting about this on (private) IRC again today - plan:</p> <p>It's best to start exploring this in a simple context - we choose odlparent &amp; infrautils.</p> <p>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.</p> <p>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.</p> <p>We would want to see having the JD working between artifacts belonging to the same project; say e.g. the JD of <a href="https://github.com/opendaylight/infrautils/blob/master/ready/impl/src/main/java/org/opendaylight/infrautils/ready/internal/SystemReadyImpl.java" class="external-link" target="_blank" rel="nofollow noopener">https://github.com/opendaylight/infrautils/blob/master/ready/impl/src/main/java/org/opendaylight/infrautils/ready/internal/SystemReadyImpl.java</a> should link to the JD of SystemReadyMonitor, which is in the ready/api.</p> <p>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).</p> <p>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.</p> <p>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.</p> <p>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.</p> <p>Summarizing, I'd say that the first and second steps are done without changing anything.</p> <p>We no longer build sites and javadoc:aggregate has the downside of running project build twice. An alternative is presented here: <a href="https://github.com/opendaylight/yangtools/blob/master/docs/pom.xml" class="external-link" target="_blank" rel="nofollow noopener">https://github.com/opendaylight/yangtools/blob/master/docs/pom.xml</a></p> Blocks DOCS-33 RELENG-3 RELENG-42 Development External issue ID 7872 External issue URL Issue Type Rank 0|i0234f: