8239581: Improve javadoc example for @jdk.jfr.Category

Reviewed-by: mgronlun, mseledtsov

src/jdk.jfr/share/classes/jdk/jfr/Category.java

@@ -44,51 +44,61 @@
  * for each upload, an event called File Upload starts when the user uploads a
  * file and ends when the upload is complete. For advanced diagnostics about
  * image uploads, more detailed events are created (for example, Image Read,
- * Image Resize, and Image Write). During these detailed events. other low
- * level-events could occur (for example, Socket Read and File Write).
+ * Image Resize, and Image Write). During these detailed events, other low-
+ * level events could occur (for example, Socket Read and File Write).
  * <p>
- * The following example shows a visualization that avoids overlaps:
+ * The following visualization shows overlapping events belonging to a
+ * single thread. By assigning the events to different categories they
+ * can be visually separated and stacked vertically.
  *
  * <pre>
- * -------------------------------------------------------------------
- *   |                         File Upload                        |
- * ------------------------------------------------------------------
- *   |       Image Read          | Image Resize |   Image Write   |
- * ------------------------------------------------------------------
- *   | Socket Read | Socket Read |              |    File Write   |
- * -------------------------------------------------------------------
+ * 13:00:01                                                     13:00:05
+ * ---------------------------------------------------------------------
+ *  1   |                         File Upload                        |
+ * ---------------------------------------------------------------------
+ *  2   |       Image Read          | Image Resize |   Image Write   |
+ * ---------------------------------------------------------------------
+ *  3   | Socket Read | Socket Read |              |    File Write   |
+ * ---------------------------------------------------------------------
  * </pre>
  *
  * The example can be achieved by using the following categories:
  *
  * <table class="striped">
- * <caption>Recording options and their purpose.</caption> <thead>
+ * <caption>Categories and lanes</caption> <thead>
  * <tr>
+ * <th scope="col">Lane</th>
  * <th scope="col">Event Name</th>
  * <th scope="col">Annotation</th>
  * </tr>
  * </thead> <tbody>
  * <tr>
+ * <th scope="row">1</th>
  * <th scope="row">File Upload</th>
  * <td><code>@Category("Upload")</code></td>
  * </tr>
  * <tr>
+ * <th scope="row">2</th>
  * <th scope="row">Image Read</th>
  * <td><code>@Category({"Upload", "Image Upload"})</code></td>
  * </tr>
  * <tr>
+ * <th scope="row">2</th>
  * <th scope="row">Image Resize</th>
  * <td><code>@Category({"Upload", "Image Upload"})</code></td>
  * </tr>
  * <tr>
+ * <th scope="row">2</th>
  * <th scope="row">Image Write</th>
  * <td><code>@Category({"Upload", "Image Upload"})</code></td>
  * </tr>
  * <tr>
+ * <th scope="row">3</th>
  * <th scope="row">Socket Read</th>
  * <td><code>@Category("Java Application")</code></td>
  * </tr>
  * <tr>
+ * <th scope="row">3</th>
  * <th scope="row">File Write</th>
  * <td><code>@Category("Java Application")</code></td>
  * </tr>
@@ -103,12 +113,12 @@
  * are visualized in a tree:
  *
  * <pre>
- *  |- Java Application
+ *  |-[Java Application]
  *  |  |- Socket Read
  *  |  |- File Write
- *  |- Upload
+ *  |-[Upload]
  *     |- File Upload
- *     |- Image Upload
+ *     |-[Image Upload]
  *        |- Image Read
  *        |- Image Resize
  *        |- File Write