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

[Jonathan Gibbons]

On 5/28/20 7:08 AM, Pavel Rappo wrote:
> There are three issues I particularly noticed while working on this, yet I'm not addressing them in this patch. Resolving those issues will improve maintainability in that area.

These all seem like good ideas.


>
> 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.

I think JDK-8222548 was just perpetuating the existing code pattern. I 
think dropping the `-x.y.z`, keeping `.v` (`.min`) is a good idea.


>
> 2. The particulars of jQuery and friends are spread across multiple places in the jdk.javadoc codebase. That needlessly complicates changes. To remediate that, JavaDoc could hide all the details such as file paths, versions, the order of .css overrides, etc. behind some sort of a "facade" object.

A facade object sounds like a good idea, and has the advantage of 
providing a place to record/comment the history of updates.  In 
particular, it could provide comments containing URLs specifying the 
origin of the downloaded files.


>
> 3. Do we need non-minified versions of the libraries?

In the past, previous developers have found it useful to have the 
non-minified versions available for debugging/development. If we had a 
facade object, it may be enough to have pointers/URLs to the 
non-minified versions, for use if and when needed.

-- Jon