RFR: 8272339: Update notes section from serialver man page

[Stuart Marks]

On Thu, 21 Nov 2024 03:56:48 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Quick doc-only change. I don't think this needs a CSR, since it contains changes only to the "notes" section, which is non-normative.
>
> src/jdk.compiler/share/man/serialver.md line 63:
> 
>> 61:     48 MB.
>> 62: 
>> 63: ## Warning
> 
> Should we move the warning more upfront?

I thought it was sufficient to change the "Notes" heading to "Warning" and to leave it in place. The tool docs are styled after Unix "man pages" which typically have Name, Synopsis, Description, Options (sometimes the last two are swapped), and then possibly other sections if the doc is long, followed by things like Notes and Warnings at the end. Of course we needn't adhere to this structure slavishly. If it were sufficiently important we could diverge from the usual structure, but in this case it doesn't seem to me that the severity of the issue is so high that we need to place the warning more prominently.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22289#discussion_r1852885770