RFR [15] 8238167: Remove stray files from jdk.javadoc

[Pavel Rappo]

Only after this changeset had been pushed, did it occur to me to have a look at
the actual release of the JQuery UI library. I downloaded and unzipped
jquery-ui-1.12.1.zip file, which had the following structure:

    +- AUTHORS.txt
    +- LICENSE.txt
    +- external
    |   +- jquery
(!) |       +- jquery.js
    +- images
    |   +- ui-icons_444444_256x240.png
    |   +- ui-icons_555555_256x240.png
    |   +- ui-icons_777620_256x240.png
    |   +- ui-icons_777777_256x240.png
    |   +- ui-icons_cc0000_256x240.png
    |   +- ui-icons_ffffff_256x240.png
    +- index.html
    +- jquery-ui.css
    +- jquery-ui.js
    +- jquery-ui.min.css
    +- jquery-ui.min.js
    +- jquery-ui.structure.css
    +- jquery-ui.structure.min.css
    +- jquery-ui.theme.css
    +- jquery-ui.theme.min.css
    +- package.json

Note that jquery.js file. This might solve the mystery of where this file came
from. So it might not be some random "leftover from the development stage",
I called it earlier, but a JQuery library that this JQuery UI library depends on.
Silly me!

It looks like the initial changeset

    changeset:   33920:bd731341c405
    user:        bpatel
    date:        Fri Nov 20 20:55:07 2015 +0000
    summary:     8141492: Implement search feature in javadoc

brought several JS libraries "squashed" under the script-dir directory, JSZip,
JSZipUtils, JQuery, and JQuery UI. This and the fact that both the jquery.js
and jquery-1.10.2.js files had the same contents, might have confused the people
who performed subsequent upgrades of those libraries. (It certainly confused me!)

At least this would explain why the top-level jquery.js file, the one we use,
has been always updated in parallel with external/jquery/jquery.js, a JQuery's
own dependency, that we have never used.

Yet, JQuery UI depends on JQuery. I'm not sure if we are lucky and JQuery UI
"just works" with our version of JQuery or it's that JQuery UI 1.12 indeed works
with any JQuery 1.7+ library out there, as that project states on its site.

That said, the changeset that was pushed yesterday does NOT break anything.
I just felt I had to convey these further findings for the sake of future
maintainers.

I should probably file a follow-up bug that deals with tidying of all that
JS mess.

-Pavel

> On 29 Jan 2020, at 15:39, Pavel Rappo <pavel.rappo at oracle.com> wrote:
> 
> Hello,
> 
> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8238167:
> 
>  http://cr.openjdk.java.net/~prappo/8238167/webrev.00/
> 
> This is a cleanup change that removes a couple of files that I have not found
> to be of any use.
> 
> The first file, jquery.js, was introduced in
> 
>    changeset:   33920:bd731341c405
>    user:        bpatel
>    date:        Fri Nov 20 20:55:07 2015 +0000
>    summary:     8141492: Implement search feature in javadoc
> 
> That same changeset also brought the jquery-1.10.2.js file. While the contents
> of these files were identical, only the latter file was used. Since then both
> files have been updated together, with the same content. Every time that happened,
> the latter file, jquery-1.10.2.js, was simultaneously renamed to reflect the
> version of the JQuery library it was updated with.
> As of today, jquery.js is still not used.
> 
> The second file, help.html, is part of the test scenario. The file first appeared in
> 
>    changeset:   36705:890c250d8da8
>    parent:      36503:4a95f4b1bd8b
>    user:        ksrini
>    date:        Mon Mar 14 15:04:57 2016 -0700
>    summary:     8071982: Update tests for revamped Doclet API
> 
> I flagged this file as suspicious while testing the change for 8237909: Remove
> zipped index files feature. I noticed that the TestOptions test did not seem to
> care whether the JSZip library was present or not, despite the fact that its
> resource, help.html, explicitly referred to that library. Further investigation
> showed that this file was never used by that test, or anyone for that matter.
> The javadoc tool has only a handful of "help" options:
> 
>    javadoc -help | grep help
>        --help, -help, -?, -h
>        --help-extra, -X
>        -helpfile <file>
>                      Include file that help link links to
>        -nohelp       Do not generate help link
> 
> all of which are covered by the TestHelpOption and TestXOption tests. There
> doesn't seem to be any need in testing anything related to "help" options in
> TestOptions. Its @summary, otherwise very specific, certainly doesn't mention
> anything like that.
> 
>    ***
> 
> Both files, jquery.js and help.html, have been diligently updated over the
> years. They seem to be leftovers from the development stage. Since they are not
> used, updating those files is a burden to maintainers and provides nothing in
> return. I propose to delete them.
> 
> All javadoc tests pass, and the functionality of the generated pages
> seems to be intact.
> 
> Thanks,
> -Pavel
>