RFR: 8231093: Document the ZIP FS properties noCompression and releaseVersion

[Alan Bateman]

On 22/09/2019 23:43, Lance Andersen wrote:
> I updated the patch and the CSR.
>
> The updated webrev is: 
> http://cr.openjdk.java.net/~lancea/8231093/webrev.01/index.html
>
I went through the spec updates in module-info.java.

"when adding entries ...". Is that also true when someone re-writes a file?

Do we need quotes around "STORED" and "DEFLATED"  value to make it 
clearer that they are strings?

"an IllegalArgumentException will be thrown". This could be expanded to 
say that will be thrown when creating the file system.

For releaseVersion there are 3 list items that start "If the value ..." 
and one that starts with "If the Object". We should keep the wording 
consistent. Also it feels like it accepts too many possible value types 
and maybe some of these should be dropped.

Could we link "multi-release JAR" to the "Multi-release JAR files" 
section of the JAR file spec. I think {@docRoot}/../specs/jar/jar.html 
should work.

When the value of releaseVersion is a String or Integer then it's the 
feature version.  In MR JARs the version is the major version of the 
Java platform release so "11.0.1" shouldn't be in the example.

The paragraph for a value of "runtime" or Runtime.Version is a bit 
difficult to read. I think you want "runtime" to use 
Runtime.version().feature(). If a Runtime.Version object is provided 
then it's feature() method will be invoked. Maybe it would be better to 
split these out or maybe allowing a Runtime.Version object should be 
dropped to reduce the number of possible value types.

-Alan