RFR: JDK-8319122: Improve documentation of various Zip-file related APIs [v2]

[Yakov Shafranovich]

On Sat, 11 Nov 2023 14:04:11 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Yakov Shafranovich has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Fixed more line breaks
>>  - fixed line breaks
>
> src/jdk.zipfs/share/classes/module-info.java line 310:
> 
>> 308:  * considered duplicates, which can result in unexpected behavior such as wrong
>> 309:  * metadata or content being returned when parsing archives containing
>> 310:  * duplicate names.
> 
> The jdk.zipfs module is the JDK's ZIP file system provider, it allows the contents of a ZIP or JAR file be treated as a file system. I think what is missing from this module description is the mapping of file system concepts to ZIP files. If we added a section to the documentation for that then it would be a place to document the file separator, normalization, how directories and file tree are synthesized, and the limitation that a file system cannot be constructed when it leads to have several entries in a directory having equal names. There's a lot more that could be added but hopefully you can see that an implNote and warnings just doesn't work as a way to present the mapping.

That would probably also involve taking existing documentation such as the note about not opening entries with "."/"..", and the POSIX permissions mappings?

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/16424#discussion_r1391317278