From 305d87dbaa492460791a7a4f59d3d0279d7af141 Mon Sep 17 00:00:00 2001
From: Alan Bateman <alan.bateman@oracle.com>
Date: Wed, 10 Mar 2021 07:41:48 +0000
Subject: [PATCH] Move examples to class desc

---
 .../share/classes/java/lang/Thread.java       | 59 +++++++++----------
 1 file changed, 27 insertions(+), 32 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/Thread.java b/src/java.base/share/classes/java/lang/Thread.java
index 33242d7ec9a..c5c06c66bd3 100644
--- a/src/java.base/share/classes/java/lang/Thread.java
+++ b/src/java.base/share/classes/java/lang/Thread.java
@@ -122,12 +122,29 @@
  *
  * <h2>Creating and starting threads</h2>
  *
- * <p> As noted above {@code Thread} defines a {@link Builder} API for creating and
- * starting threads. The following example starts a platform thread with name
- * "greeter" that prints a message:
- * <pre>{@code    Runnable runnable = () -> System.out.println("hello world");
- *   Thread thread = Thread.ofPlatform().name("greeter").start(runnable);
- *   thread.join(); }</pre>
+ * <p> As noted above, {@code Thread} defines a {@link Builder} API for creating and
+ * starting threads. The {@link #ofPlatform()} and {@link #ofVirtual()} methods are
+ * used to create builders for platform and virtual threads respectively.
+ * The following are examples that use the builder:
+ * <pre>{@code
+ *   Runnable runnable = ...
+ *
+ *   // Start a daemon thread to run a task
+ *   Thread thread = Thread.ofPlatform().daemon().start(runnable);
+ *
+ *   // Create an unstarted thread with name "duke", its start() method
+ *   // must be invoked to schedule it to execute.
+ *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
+ *
+ *   // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
+ *   ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();
+ *
+ *   // Start a virtual thread to run a task
+ *   Thread thread = Thread.ofVirtual().start(runnable);
+ *
+ *   // A ThreadFactory that creates virtual threads
+ *   ThreadFactory factory = Thread.ofVirtual().factory();
+ * }</pre>
  *
  * <p> In addition to the builder, {@code Thread} defines (for historical and
  * customization reasons) public constructors for creating platform threads. Most
@@ -758,15 +775,14 @@ public interface VirtualThreadTask extends Runnable {
      * that creates platform threads.
      *
      * @apiNote The following are examples using the builder:
-     *
      * <pre>{@code
-     *   // Create a thread with name "duke".
-     *   // The thread's start method must be invoked to schedule it to execute.
-     *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
-     *
      *   // Start a daemon thread to run a task
      *   Thread thread = Thread.ofPlatform().daemon().start(runnable);
      *
+     *   // Create an unstarted thread with name "duke", its start() method
+     *   // must be invoked to schedule it to execute.
+     *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
+     *
      *   // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
      *   ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();
      * }</pre>
@@ -783,7 +799,6 @@ public static Builder.OfPlatform ofPlatform() {
      * that creates virtual threads.
      *
      * @apiNote The following are examples using the builder:
-     *
      * <pre>{@code
      *   // Start a virtual thread to run a task.
      *   Thread thread = Thread.ofVirtual().start(runnable);
@@ -823,26 +838,6 @@ public static Builder.OfVirtual ofVirtual() {
      * <p> Unless otherwise specified, passing a null argument to a method in
      * this interface causes a {@code NullPointerException} to be thrown.
      *
-     * @apiNote The following are examples using the builder:
-     *
-     * <pre>{@code
-     *   // Start a virtual thread to run a task.
-     *   Thread thread = Thread.ofVirtual().start(runnable);
-     *
-     *   // A ThreadFactory that creates virtual threads
-     *   ThreadFactory factory = Thread.ofVirtual().factory();
-     *
-     *   // Create a thread with name "duke".
-     *   // The thread's start method must be invoked to schedule it to execute.
-     *   Thread thread = Thread.ofPlatform().name("duke").unstarted(runnable);
-     *
-     *   // Start a daemon thread to run a task
-     *   Thread thread = Thread.ofPlatform().daemon().start(runnable);
-     *
-     *   // A ThreadFactory that creates daemon threads named "worker-0", "worker-1", ...
-     *   ThreadFactory factory = Thread.ofPlatform().daemon().name("worker-", 0).factory();
-     * }</pre>
-     *
      * @see Thread#ofPlatform()
      * @see Thread#ofVirtual()
      * @since 99