RFR: 8359123: Misleading examples in jmod man page

[Iris Clark]

On Thu, 12 Jun 2025 07:57:20 GMT, Ana Maria Mihalceanu <duke at openjdk.org> wrote:

> Please review my PR. This PR includes the following:
> 
> - [x] Fix a small typo in a word and copyright.
> - [x] Enhance description for `--target-platform`.
> - [x] Rearrange `jmod create` example from basic to complex.

Changes requested by iris (Reviewer).

src/jdk.jlink/share/man/jmod.md line 183:

> 181: `--target-platform` *platform*
> 182: :   Specifies the target platform. The value is a string that identifies
> 183:     the platform this module is intended for, typically in the form `<os>-<arch>`.

Consider: "The value is a string identifying the module's intended platform, typically of the form `<os>-<arch>`.

src/jdk.jlink/share/man/jmod.md line 220:

> 218:     deprecated, deprecated-for-removal, or incubating.
> 219: 
> 220: ## jmod Create Example

"Example" -> "Examples"

src/jdk.jlink/share/man/jmod.md line 222:

> 220: ## jmod Create Example
> 221: 
> 222: The basic manner to create a JMOD file is by including only compiled classes:

I"m not sure what this is supposed to describe, perhaps something like this is more clear:  "Create a JMOD file containing only compiled classes:".

Whatever you choose should be parallel to the descriptions of the other create examples.  (My later comments are parallel to my suggestion for this line.)

src/jdk.jlink/share/man/jmod.md line 228:

> 226: ```
> 227: 
> 228: To ensure reproducible artifacts, the following command creates

Is it necessary to provide a reason to use this option rather than just describe what the example does?  For parallelization, I'd retain the text in old line 231.

src/jdk.jlink/share/man/jmod.md line 237:

> 235: 
> 236: The command below creates a platform-specific JMOD file, bundling class files,
> 237: user-editable configuration files, header files, native commands and libraries:

Your description for the more complex command line should either list all or none of the options.

If you chose the "none" approach, consider "Create a platform-specific JMOD file containing multiple artifacts."

If you chose the "all" approach, you'll need to add references to the  options on line 242, e.g. "Create a platform-specific JMOD file containing class files, user-editable configuration files, header files, ... ".

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

PR Review: https://git.openjdk.org/jdk/pull/25772#pullrequestreview-2925555112
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2145550424
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2145564293
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2145578809
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2145585506
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2145676273