Re: Javadoc usability
Emmanuel, It looks like you updated the Commons Parent POM to add a profile without documenting the change in changes.xml. Would you please do that? TY, Gary On 2024/05/18 12:21:54 sebb wrote: > If we are changing the Javadoc settings, we should update the footer > to include the full list of attributions. > > On Sat, 18 May 2024 at 12:59, Emmanuel Bourg wrote: > > > > Le 18/05/2024 à 13:07, Gary Gregory a écrit : > > > You must be talking about this: > > > > > > https://bugs.openjdk.org/browse/JDK-8202961 > > > > > > The frames command line option might be completely gone from the current > > > Java version but I haven't tried > > > > Digging a bit, frames were deprecated in JDK 11 and eventually removed > > in JDK 13 [1]. > > > > > > > I don't think we should use an antique version of the doclet. > > > > As long as a component doesn't require Java 13+ we could at least keep > > the frames, for example by adding the -frame option to the javadoc > > plugin configuration in the parent pom when building with JDK 11. > > > > Emmanuel Bourg > > > > > > [1] https://bugs.openjdk.org/browse/JDK-8215599 > > > > > > - > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: Javadoc usability
If we are changing the Javadoc settings, we should update the footer to include the full list of attributions. On Sat, 18 May 2024 at 12:59, Emmanuel Bourg wrote: > > Le 18/05/2024 à 13:07, Gary Gregory a écrit : > > You must be talking about this: > > > > https://bugs.openjdk.org/browse/JDK-8202961 > > > > The frames command line option might be completely gone from the current > > Java version but I haven't tried > > Digging a bit, frames were deprecated in JDK 11 and eventually removed > in JDK 13 [1]. > > > > I don't think we should use an antique version of the doclet. > > As long as a component doesn't require Java 13+ we could at least keep > the frames, for example by adding the -frame option to the javadoc > plugin configuration in the parent pom when building with JDK 11. > > Emmanuel Bourg > > > [1] https://bugs.openjdk.org/browse/JDK-8215599 > > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: Javadoc usability
Le 18/05/2024 à 13:07, Gary Gregory a écrit : You must be talking about this: https://bugs.openjdk.org/browse/JDK-8202961 The frames command line option might be completely gone from the current Java version but I haven't tried Digging a bit, frames were deprecated in JDK 11 and eventually removed in JDK 13 [1]. I don't think we should use an antique version of the doclet. As long as a component doesn't require Java 13+ we could at least keep the frames, for example by adding the -frame option to the javadoc plugin configuration in the parent pom when building with JDK 11. Emmanuel Bourg [1] https://bugs.openjdk.org/browse/JDK-8215599 - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: Javadoc usability
The "unknown unknowns" ;-) Gary On Sat, May 18, 2024 at 7:27 AM Emmanuel Bourg wrote: > > The search box is a nice addition, but it's only useful if you know what > you are looking for. It doesn't replace a plain list of classes that can > be explored at a glance. > > Emmanuel Bourg > > Le 18/05/2024 à 13:09, Gary Gregory a écrit : > > Notice that the newer Javadocs has a fancy Search box, quite handy IMO. > > > > Gary > > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: Javadoc usability
The search box is a nice addition, but it's only useful if you know what you are looking for. It doesn't replace a plain list of classes that can be explored at a glance. Emmanuel Bourg Le 18/05/2024 à 13:09, Gary Gregory a écrit : Notice that the newer Javadocs has a fancy Search box, quite handy IMO. Gary - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: Javadoc usability
Notice that the newer Javadocs has a fancy Search box, quite handy IMO. Gary On Sat, May 18, 2024, 7:07 AM Gary Gregory wrote: > You must be talking about this: > > https://bugs.openjdk.org/browse/JDK-8202961 > > The frames command line option might be completely gone from the current > Java version but I haven't tried > : > > > https://docs.oracle.com/en/java/javase/21/docs/specs/man/javadoc.html#option-add-stylesheet > > Note that the no frames option is retained as a noop. > > I don't think we should use an antique version of the docket. > > Gary > > On Sat, May 18, 2024, 5:53 AM Emmanuel Bourg wrote: > >> Hi all, >> >> I got a look at the Commons IO Javadoc [1] yesterday and it looks like >> something got wrong starting with the 2.14 release, the framed layout >> [2] up to the version 2.13 was much more usable, with an instant >> overview of the package structure and the classes available. Exploring >> the API is really tedious with the new layout. >> >> I don't know if the latest JDKs still support the framed layout, if they >> do it would be nice to trigger the build option necessary, otherwise I >> think we should switch to an alternative doclet, or stick to older JDKs >> for now. >> >> What do you think? >> >> Emmanuel Bourg >> >> [1] https://javadoc.io/doc/commons-io/commons-io/2.16.1/index.html >> [2] https://javadoc.io/doc/commons-io/commons-io/2.13.0/index.html >> >> - >> To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org >> For additional commands, e-mail: dev-h...@commons.apache.org >> >>
Re: Javadoc usability
You must be talking about this: https://bugs.openjdk.org/browse/JDK-8202961 The frames command line option might be completely gone from the current Java version but I haven't tried : https://docs.oracle.com/en/java/javase/21/docs/specs/man/javadoc.html#option-add-stylesheet Note that the no frames option is retained as a noop. I don't think we should use an antique version of the docket. Gary On Sat, May 18, 2024, 5:53 AM Emmanuel Bourg wrote: > Hi all, > > I got a look at the Commons IO Javadoc [1] yesterday and it looks like > something got wrong starting with the 2.14 release, the framed layout > [2] up to the version 2.13 was much more usable, with an instant > overview of the package structure and the classes available. Exploring > the API is really tedious with the new layout. > > I don't know if the latest JDKs still support the framed layout, if they > do it would be nice to trigger the build option necessary, otherwise I > think we should switch to an alternative doclet, or stick to older JDKs > for now. > > What do you think? > > Emmanuel Bourg > > [1] https://javadoc.io/doc/commons-io/commons-io/2.16.1/index.html > [2] https://javadoc.io/doc/commons-io/commons-io/2.13.0/index.html > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
Javadoc usability
Hi all, I got a look at the Commons IO Javadoc [1] yesterday and it looks like something got wrong starting with the 2.14 release, the framed layout [2] up to the version 2.13 was much more usable, with an instant overview of the package structure and the classes available. Exploring the API is really tedious with the new layout. I don't know if the latest JDKs still support the framed layout, if they do it would be nice to trigger the build option necessary, otherwise I think we should switch to an alternative doclet, or stick to older JDKs for now. What do you think? Emmanuel Bourg [1] https://javadoc.io/doc/commons-io/commons-io/2.16.1/index.html [2] https://javadoc.io/doc/commons-io/commons-io/2.13.0/index.html - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
