You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@poi.apache.org by Nick Burch <ni...@apache.org> on 2018/10/19 09:53:41 UTC
Proposal - host javadocs of recent versions too
Hi All
As many of you will know, we have javadocs on the website, but these
correspond to the latest (typically unreleased) code. Javadocs for a
specific release are shipped in the binary package, and as a javadoc jar
via Maven central (eg for IDE use). Based on stackoverflow posts though,
this approach can sometimes cause new user confusion.
What I'd propose is that we host additionally the javadocs of the last few
main releases, so people can easily look up the javadocs of the version
they're using, without needing to re-find a past download / download
something else.
The immediate change would be:
* Everything at https://poi.apache.org/apidocs/ gets pushed to
https://poi.apache.org/apidocs/dev/
* A new page at https://poi.apache.org/apidocs/ which says which
versions you can see javadocs for online, and instructions on getting
older ones from the released files
* Redirects for as much as possible from https://poi.apache.org/apidocs/
to https://poi.apache.org/apidocs/dev/ to avoid breaking links
* Tweaks to the site build ant file to support the changes
Then, and this is the bit which could use some more feedback:
* /apidocs/40/ for the latest 4.0.x release (eg when we do 4.0.1 we
replace them)
* /apidocs/317/ for 3.17 final
* /apidocs/316/ for 3.16 final
* No betas, nothing older than 3.16
* Using 40 not 4.0 nor 4.0.x
* Using 317 not 3.17
On these last parts especially, what do people think?
Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org
Re: Proposal - host javadocs of recent versions too
Posted by Dominik Stadler <do...@gmx.at>.
Thanks a lot Nick! That should avoid some confusion when we reference
JavaDocs in support-mails and StackOverflow.
There are currently around 100 warnings, I'll try to bring that down
somewhat in the coming days, it's mostly HTML violations and missing
@param/@return/@throws.
Dominik.
On Tue, Oct 30, 2018 at 5:35 PM Nick Burch <ap...@gagravarr.org> wrote:
> On Fri, 19 Oct 2018, Nick Burch wrote:
> > The immediate change would be:
> > * Everything at https://poi.apache.org/apidocs/ gets pushed to
> > https://poi.apache.org/apidocs/dev/
> > * A new page at https://poi.apache.org/apidocs/ which says which
> > versions you can see javadocs for online, and instructions on getting
> > older ones from the released files
> > * Redirects for as much as possible from https://poi.apache.org/apidocs/
> > to https://poi.apache.org/apidocs/dev/ to avoid breaking links
> > * Tweaks to the site build ant file to support the changes
>
> These are now hopefully all done and sorted!
>
> > Then, and this is the bit which could use some more feedback:
> > * /apidocs/4.0/ for the latest 4.0.x release (eg when we do 4.0.1 we
> > replace them)
> > * /apidocs/3.17/ for 3.17 final
>
> These two are done as well
>
>
> I think the main thing that remains now, if anyone feels keen is that
> building the latest Javadocs shows a bunch of broken references to other
> classes / methods / fields. If someone has maybe an hour to spare, it'd be
> great to run "ant javadocs", see the warnings for the broken references,
> and fix as many of them as possible!
>
> Nick
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
> For additional commands, e-mail: dev-help@poi.apache.org
>
>
Re: Proposal - host javadocs of recent versions too
Posted by Nick Burch <ap...@gagravarr.org>.
On Fri, 19 Oct 2018, Nick Burch wrote:
> The immediate change would be:
> * Everything at https://poi.apache.org/apidocs/ gets pushed to
> https://poi.apache.org/apidocs/dev/
> * A new page at https://poi.apache.org/apidocs/ which says which
> versions you can see javadocs for online, and instructions on getting
> older ones from the released files
> * Redirects for as much as possible from https://poi.apache.org/apidocs/
> to https://poi.apache.org/apidocs/dev/ to avoid breaking links
> * Tweaks to the site build ant file to support the changes
These are now hopefully all done and sorted!
> Then, and this is the bit which could use some more feedback:
> * /apidocs/4.0/ for the latest 4.0.x release (eg when we do 4.0.1 we
> replace them)
> * /apidocs/3.17/ for 3.17 final
These two are done as well
I think the main thing that remains now, if anyone feels keen is that
building the latest Javadocs shows a bunch of broken references to other
classes / methods / fields. If someone has maybe an hour to spare, it'd be
great to run "ant javadocs", see the warnings for the broken references,
and fix as many of them as possible!
Nick
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@poi.apache.org
For additional commands, e-mail: dev-help@poi.apache.org