jPackage documentation needs major update

Summary

I am reporting on the latest version of the JDK, as of jan 18 2022. The documentation (we found only : https://docs.oracle.com/en/java/javase/16/jpackage/packaging-overview.html, with also this: https://docs.oracle.com/en/java/javase/17/jpackage/packaging-tool-user-guide.pdf), should be updated and proper advanced example (with rich commenting), should be added, because to use jpackage is not necessarily straight forward. To not become a time thief for more unexperienced developer, please note that whenever launching an application for MacOs, and when the application exploit system resources classified by Apple as "security" (e.g. microphone input), then the application MUST be packed and signed according to Apple rules. Therefore, I suggest the following:

In consequence, please add a full example on the --apple-sign option.
Put comments intended for the novice in the examples.
Explain Appdir usage in the documentation
PLEASE include explanation of the inclusion of non java files, for example files that should be part of the final installed directory for JNI usage. JNI is quite common in java applications, agree? On Windows, that almost always include the inclusion of one or more DLL files in the same directory as the application directory. To understand that this is possible, it seems necessary to program the (in my case) build.gradle according the "splash" example in the following list of examples: https://github.com/beryx/badass-jlink-plugin, found by hints on stackoverflow https://stackoverflow.com/questions/64338849/jpackage-add-files-to-installdir

No doubt, this manner of documentation is obscure at best. Please add a separate chapter in the official documentation on how to include non-java files in the final install directory, DLL files and whatever else imagineable. Preferrably, there should be a systemtic approach to this, like "put dll files in "external files" subdirectory", or something like that. That way, user not advocated in Groovy for Gradle can save time trying to program the correct subdir.

It would also be VERY GOOD if you could add some examples to demonstrate usage of the various build systems, Gradle under Android Studio (intellij) in my case, with a lot of explaining comments. Note: My project contains pure Java modules that are both part of Android app and part of desktop pure java applications. I found Android Studio to be fully compliant to such a mixed project structure, but I anticipate Intellij would be the same.
Perhaps a wet dream, but never the less a good one: If you presented a GUI along the lines of e.g. the launch4j tool, it would be supergreat and also modern. For the novice, it is so much simpler to use a GUI.

In concrete words: I want to expand the build.gradle files for the pure java application so as to make it installable on the three major desktop operating systems (while Andoid app has its own way, of course). Understand?

Beyond those comments, jpackage appears to be or become a very useful tool that allows for automatic cross-platform launch of applications. And this is precisely what I would like to see: Rich and somewhat complicate examples on how jpackage can be the tool to make things fully automated, including, but not limited to a list of relevant plugins, Gradle in my case. I am still not sure if I need the badass plugin for gradle, but it appears so. No documentation found.

Many thanks, looking forward to crawl my way to a fully automated system.

Steps to reproduce

Expected results

Actual results

Triaging info

Java version:

What is your operating system and platform?

How did you install Java?

Did it work before?

Did you test with other Java versions?

adoptium / adoptium-support