RFR [15] 8236823: Ensure that API documentation uses minified libraries

[Jonathan Gibbons]

Pavel,

It does seem like the -x.y.z is part of the standard naming scheme when 
downloading the file, and I can see the rationale for leaving the 
filename as-is. That being said, it is (and always has been) 
inconsistent with the lack of any version in the jquery-ui files.

There are pros and cons to renaming the file.

Using the name of the file as downloaded causes a small amount of churn 
in the repo since each time we remove one version and add another. On 
the other hand, using the same file name each time causes almost 
equivalent churn because the diffs between versions are of no interest 
to us, and the diffs between minified versions are effectively 
meaningless, and probably cause as much churn as removing the old 
version and adding the new one.

Overall, I'd recommend your proposed approach of a facade file to 
encapulate javadoc use of jQuery, and to use that to document the 
original location of the current version of the file, and to document 
the upgrade process. I agree with your suggestion that we should not 
modify any downloaded file, and should override (instead of modify) the 
CSS as needed. Within that approach, the name of the file becomes a 
second- or third-order concern, hidden behind the encapsulation.

-- Jon


On 5/29/20 9:18 AM, Pavel Rappo wrote:
> Thanks, Jon.
>
> Apparently, I didn't pay enough attention while researching history. As a result, I mistakenly attributed that naming scheme to the fix for JDK-8222548 and I apologize for that. jQuery has been present in our repo in the form of jquery-x.y.z.js since its first appearance, as can be seen below.
>
> 1.
>
> changeset:   33920:bd731341c405
> user:        bpatel
> date:        Fri Nov 20 20:55:07 2015 +0000
> summary:     8141492: Implement search feature in javadoc
>
> langtools/src/jdk.javadoc/share/classes/com/sun/tools/doclets/internal/toolkit/resources/jquery/jquery-1.10.2.js
>
> 2.
>
> changeset:   35426:374342e56a56
> user:        ksrini
> date:        Sat Nov 28 18:52:17 2015 -0800
> summary:     8035473: [javadoc] Revamp the existing Doclet APIs
>
> langtools/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/jquery/jquery-1.10.2.js
>
> 3.
>
> changeset:   47216:71c04702a3d5
> user:        erikj
> date:        Tue Sep 12 19:03:39 2017 +0200
> summary:     8187443: Forest Consolidation: Move files to unified layout
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/jquery/jquery-1.10.2.js
>
> 4.
>
> changeset:   50394:89dc31d7572b
> user:        sundar
> date:        Tue Jun 05 08:10:08 2018 +0530
> summary:     8203780: javadoc should be updated to use jquery 1.12.4, jquery-ui 1.12.1 and jszip v3.1.5
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/jquery/jquery-1.12.4.js
>
> 5.
>
> changeset:   50575:72c694f035ee
> user:        pmuthuswamy
> date:        Fri Jun 15 10:48:56 2018 +0530
> summary:     8204666: javadoc should be updated to use jQuery 3.3.1
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/jquery/jquery-3.3.1.js
>
> 6.
>
> changeset:   54531:edf1b4c6b936
> user:        hannesw
> date:        Mon Apr 15 15:38:47 2019 +0200
> summary:     8221644: jquery directory should be renamed
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script-dir/jquery-3.3.1.js
>
> 7.
>
> changeset:   54895:4f1f939d8f5d
> user:        pmuthuswamy
> date:        Thu May 16 16:40:48 2019 +0530
> summary:     8222548: Upgrading JDK 13 with the latest available jQuery 3.4.1
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script-dir/jquery-3.4.1.js
>
> -Pavel
>
>> On 29 May 2020, at 15:47, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>>
>>
>> On 5/28/20 7:08 AM, Pavel Rappo wrote:
>>> 1. I don't understand why JDK-8222548 renamed "jquery.js" to "jquery-3.4.1.js". Unless necessary, things like this introduce unneeded churn to the codebase. It's much cleaner to change just the contents of a file rather than both the contents and the name as that name might be used in the codebase. So, I'm thinking of renaming jquery-x.y.z.v.js back to just jquery.v.js.
>> JDK-8222548 was just continuing the pattern.  Not an excuse; just an explanation.
>>
>> --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java	Thu May 16 10:52:36 2019 +0200
>> +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java	Thu May 16 16:40:48 2019 +0530
>> @@ -199,8 +199,7 @@
>>   
>>       private void copyJqueryFiles() throws DocletException {
>>           List<String> files = Arrays.asList(
>> -                "jquery-3.3.1.js",
>> -                "jquery-migrate-3.0.1.js",
>> +                "jquery-3.4.1.js",
>>                   "jquery-ui.js",
>>                   "jquery-ui.css",
>>                   "jquery-ui.min.js",
>>