Repository navigation
Website only hosts public API javadocs #448
Description
The accumulo website only hosts the public API javadocs.
This is problematic as the website link does not have verbiage that describes these javadocs are only scoped to the public API classes.
Looking at javadoc.io, there is a clear difference between the package index available between the 2.1.3 versions of accumulo.
https://accumulo.apache.org/docs/2.x/apidocs/allpackages-index.html
https://www.javadoc.io/doc/org.apache.accumulo/accumulo-core/2.1.3/allpackages-index.html
Activity
ctubbsii commentedon Dec 10, 2024
I'm not sure what the problem is that you're reporting here. Yes, the docs are a subset of all the Java code. That is intentional, and fits our general theme of trying to document what we think is useful/relevant for users to know. I don't think there is any implication that the javadocs are comprehensive.
The javadoc jars published to Maven Central, however, are comprehensive, and I believe that's what powers javadoc.io. But, what a third party chooses to publish has no bearing on what we choose to publish. I'm not sure there's anything for us to fix here.
Also, for what it's worth, the links on the downloads page refers to these as "Java API", which I think aligns nicely with the subset we're choosing to publish. So, I don't think there's anything to do for this issue.
ddanielr commentedon Apr 10, 2025
The link directly from the Documentation page says
Javadocs (2.x)and then underneath of that link isPublic API. The link names suggest that the javadocs are complete as that next link is the subset of the public api.Once the page loads, it does say
Apache Accumulo Project 2.1.3 APIwhich is properly scoped but easy for someone to miss.I agree that 3rd parties have no impact on what we chose to publish.
I agree that the download page verbiage is accurate. I think the issue is based on the page navigation.
ddanielr commentedon Apr 10, 2025
Why is the link name
javadocsvs the page name ofapidocs?ctubbsii commentedon Apr 10, 2025
Because most people call them "Javadocs", but the javadoc tooling generates the files in an "apidocs" folder. This is a pattern followed by the maven tooling for generating site documentation as well. See https://maven.apache.org/plugins/maven-compiler-plugin/project-reports.html which has a link to "Javadoc" that points to https://maven.apache.org/plugins/maven-compiler-plugin/apidocs/index.html
ctubbsii commentedon Apr 10, 2025
The nav link names could be improved, but I don't think they are a great source of confusion. The "javadoc" nav links are really links to "Javadocs generated for our public and user facing API and SPI classes", and our "Public API" link is really a link to our answer to the question "What do we include in our definition of Public API?", but those are much harder to fit in the nav bar.
We could remove the Javadoc links from the navigation, and instead add links onto the "Public API" page to the Javadocs, so users navigate through the public API definition before being presented with the link to the docs for it.