You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@accumulo.apache.org by "ddanielr (via GitHub)" <gi...@apache.org> on 2024/11/06 13:45:07 UTC
[I] Website only hosts public API javadocs [accumulo-website]
ddanielr opened a new issue, #448:
URL: https://github.com/apache/accumulo-website/issues/448
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
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Website only hosts public API javadocs [accumulo-website]
Posted by "ctubbsii (via GitHub)" <gi...@apache.org>.
ctubbsii commented on issue #448:
URL: https://github.com/apache/accumulo-website/issues/448#issuecomment-2795293330
> 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Website only hosts public API javadocs [accumulo-website]
Posted by "ddanielr (via GitHub)" <gi...@apache.org>.
ddanielr commented on issue #448:
URL: https://github.com/apache/accumulo-website/issues/448#issuecomment-2794666363
> 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Website only hosts public API javadocs [accumulo-website]
Posted by "ddanielr (via GitHub)" <gi...@apache.org>.
ddanielr commented on issue #448:
URL: https://github.com/apache/accumulo-website/issues/448#issuecomment-2794668545
Why is the link name `javadocs` vs the page name of `apidocs`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Website only hosts public API javadocs [accumulo-website]
Posted by "ctubbsii (via GitHub)" <gi...@apache.org>.
ctubbsii commented on issue #448:
URL: https://github.com/apache/accumulo-website/issues/448#issuecomment-2532683215
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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] Website only hosts public API javadocs [accumulo-website]
Posted by "ctubbsii (via GitHub)" <gi...@apache.org>.
ctubbsii commented on issue #448:
URL: https://github.com/apache/accumulo-website/issues/448#issuecomment-2795283177
> 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
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@accumulo.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org