RFR: Extend documentation regarding logging

[Jesper Wilhelmsson]

On Tue, 30 Aug 2022 12:11:07 GMT, Johan Sjölén <duke at openjdk.org> wrote:

> Hi!
> 
> Here's some suggested improvements to the logging documentation. It's currently just a draft, but please feel welcome to come with any suggestions.

Thank you for extending this section! This is good material that will be very helpful for anyone embarking on a VM hacking journey. I've made a few minor suggestions on style and language. On the technical content I trust you know that a lot better than me :-)

src/guide/hotspot-development.md line 14:

> 12: 
> 13: The appropriate way to print logging output from HotSpot is through the [Unified Logging Framework (JEP 158)](https://openjdk.org/jeps/158).
> 14: It gives you a lot of nice features and enables common command-line options for all logging.

Please don't add line breaks in sections. Goes for sections below as well.

src/guide/hotspot-development.md line 16:

> 14: It gives you a lot of nice features and enables common command-line options for all logging.
> 15: 
> 16: 

One empty line is enough :-)

src/guide/hotspot-development.md line 17:

> 15: 
> 16: 
> 17: A basic log message can be output like this.

Please end the line with a colon.

src/guide/hotspot-development.md line 34:

> 32: 
> 33: Sometimes single line printf-style logging isn't enough.
> 34: For example, it can be useful to group several log lines together or to use Hotspot's output stream API.

HotSpot should have a capitalized S.

src/guide/hotspot-development.md line 55:

> 53:   st.print("I'm printing a lot of %s ", "arguments");
> 54:   st.print("With a lot of extra info %d ", 3);
> 55:   st.print_cr("and so it's useful to use a stream");

I think it would be useful to explain the difference between print and print_cr even though it may seem obvious to many. A single sentence just saying that print_cr will print a line break is enough.

src/guide/hotspot-development.md line 72:

> 70: ~~~
> 71: 
> 72: 

One empty line is enough. The fact that you added two makes me think that you want to separate these two sections slightly. If so, use a subheader ##.

src/guide/hotspot-development.md line 73:

> 71: 
> 72: 
> 73: You turn on logging by starting the JVM with the `-Xlog` command line option specified.

I would phrase this slightly different: "You enable logging in the JVM by using the `-Xlog` command line option."

src/guide/hotspot-development.md line 74:

> 72: 
> 73: You turn on logging by starting the JVM with the `-Xlog` command line option specified.
> 74: For example, the messages from the examples would be visible if the JVM were run with any of the following flags:

"...from the examples above..."
"flags" -> "options"

src/guide/hotspot-development.md line 82:

> 80: ~~~
> 81: 
> 82: A full description of the syntax of `-Xlog` is available in [JEP 158](https://openjdk.java.net/jeps/158), also mentioned above.

I would end the sentence directly after the link.

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

Changes requested by jwilhelm (Lead).

PR: https://git.openjdk.org/guide/pull/91