Website only hosts public API javadocs

[ddanielr]

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

[ctubbsii]

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]

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 link directly from the Documentation page says Javadocs (2.x) and then underneath of that link is Public 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 API which is properly scoped but easy for someone to miss.

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.

I agree that 3rd parties have no impact on what we chose to publish.

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.

I agree that the download page verbiage is accurate. I think the issue is based on the page navigation.

[ddanielr]

Why is the link name javadocs vs the page name of apidocs?

[ctubbsii]

Why is the link name javadocs vs the page name of apidocs?

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]

The link directly from the Documentation page says Javadocs (2.x) and then underneath of that link is Public API. The link names suggest that the javadocs are complete as that next link is the subset of the public api.

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.

I agree that the download page verbiage is accurate. I think the issue is based on the page navigation.

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.