8258776: ThreadLocal#initialValue() Javadoc is unaware of ThreadLocal…

…#withInitial()

Reviewed-by: alanb

src/java.base/share/classes/java/lang/ThreadLocal.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -120,13 +120,16 @@ private static int nextHashCode() {
      * most once per thread, but it may be invoked again in case of
      * subsequent invocations of {@link #remove} followed by {@link #get}.
      *
-     * <p>This implementation simply returns {@code null}; if the
+     * @implSpec
+     * This implementation simply returns {@code null}; if the
      * programmer desires thread-local variables to have an initial
-     * value other than {@code null}, {@code ThreadLocal} must be
-     * subclassed, and this method overridden.  Typically, an
-     * anonymous inner class will be used.
+     * value other than {@code null}, then either {@code ThreadLocal}
+     * can be subclassed and this method overridden or the method
+     * {@link ThreadLocal#withInitial(Supplier)} can be used to
+     * construct a {@code ThreadLocal}.
      *
      * @return the initial value for this thread-local
+     * @see #withInitial(java.util.function.Supplier)
      */
     protected T initialValue() {
         return null;
@@ -159,8 +162,7 @@ public ThreadLocal() {
      * current thread, it is first initialized to the value returned
      * by an invocation of the {@link #initialValue} method.
      * If the current thread does not support thread locals then
-     * this method returns its {@link #initialValue} (or {@code null}
-     * if the {@code initialValue} method is not overridden).
+     * this method returns its {@link #initialValue}.
      *
      * @return the current thread's value of this thread-local
      * @see Thread.Builder#allowSetThreadLocals(boolean)