RFR: 8359123: Misleading examples in jmod man page [v2]

[Ana Maria Mihalceanu]

On Fri, 13 Jun 2025 17:07:20 GMT, Iris Clark <iris at openjdk.org> wrote:

>> Ana Maria Mihalceanu has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - Fix whitespaces.
>>  - Update description of commands as per code review
>
> 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>`.

Thank you for the suggestion, Iris. I've incorporated it.

> src/jdk.jlink/share/man/jmod.md line 220:
> 
>> 218:     deprecated, deprecated-for-removal, or incubating.
>> 219: 
>> 220: ## jmod Create Example
> 
> "Example" -> "Examples"

Well spotted. Thank you 😄 .

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

I followed the pattern you suggested. Thank you.

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

Thought it would be good to provide a reason for _why_ as well. But will keep the pattern for describing the command.

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

Thank you for the suggestions. I preferred to go ahead with _all_ approach. Can you please take a look again at the changes?

Thank you.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2147082608
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2147083353
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2147086816
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2147087912
PR Review Comment: https://git.openjdk.org/jdk/pull/25772#discussion_r2147089570