8300133: Use generalized see and link tags in core libs

Reviewed-by: jjg, mchung, naoto, smarks

Author: jddarcy

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 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
@@ -73,8 +73,8 @@ public interface CharSequence {
      * indexing.
      *
      * <p>If the {@code char} value specified by the index is a
-     * <a href="{@docRoot}/java.base/java/lang/Character.html#unicode">surrogate</a>, the surrogate
-     * value is returned.
+     * {@linkplain Character##unicode surrogate}, the surrogate value
+     * is returned.
      *
      * @param   index   the index of the {@code char} value to be returned
      *
@@ -132,9 +132,9 @@ default boolean isEmpty() {
 
     /**
      * Returns a stream of {@code int} zero-extending the {@code char} values
-     * from this sequence.  Any char which maps to a <a
-     * href="{@docRoot}/java.base/java/lang/Character.html#unicode">surrogate code
-     * point</a> is passed through uninterpreted.
+     * from this sequence.  Any char which maps to a
+     * {@linkplain Character##unicode surrogate code point} is passed
+     * through uninterpreted.
      *
      * <p>The stream binds to this sequence when the terminal stream operation
      * commences (specifically, for mutable sequences the spliterator for the

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

@@ -4067,9 +4067,9 @@ public String toString() {
 
     /**
      * Returns a stream of {@code int} zero-extending the {@code char} values
-     * from this sequence.  Any char which maps to a <a
-     * href="{@docRoot}/java.base/java/lang/Character.html#unicode">surrogate code
-     * point</a> is passed through uninterpreted.
+     * from this sequence.  Any char which maps to a {@linkplain
+     * Character##unicode surrogate code point} is passed through
+     * uninterpreted.
      *
      * @return an IntStream of char values from this sequence
      * @since 9

src/java.base/share/classes/java/lang/module/Configuration.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2014, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2014, 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
@@ -48,8 +48,8 @@
 
 /**
  * A configuration that is the result of <a href="package-summary.html#resolution">
- * resolution</a> or resolution with
- * <a href="{@docRoot}/java.base/java/lang/module/Configuration.html#service-binding">service binding</a>.
+ * resolution</a> or resolution with {@linkplain
+ * Configuration##service-binding service binding}.
  *
  * <p> A configuration encapsulates the <em>readability graph</em> that is the
  * output of resolution. A readability graph is a directed graph whose vertices

src/java.base/share/classes/java/math/BigDecimal.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -3102,9 +3102,8 @@ public BigDecimal stripTrailingZeros() {
      * @apiNote
      * Note: this class has a natural ordering that is inconsistent with equals.
      * The behavior of comparing the result of this method for
-     * equality to 0 is analogous to checking the <a
-     * href="{@docRoot}/java.base/java/lang/Double.html#fpNumericalEq">numerical
-     * equality</a> of {@code double} values.
+     * equality to 0 is analogous to checking the {@linkplain
+     * Double##fpNumericalEq numerical equality} of {@code double} values.
      *
      * @param  val {@code BigDecimal} to which this {@code BigDecimal} is
      *         to be compared.
@@ -3197,9 +3196,9 @@ else if (ys != INFLATED)
      * HALF_UP)} which evaluates to 0.7 and <br>
      * {@code new BigDecimal("2.00").divide(BigDecimal.valueOf(3),
      * HALF_UP)} which evaluates to 0.67.
-     * The behavior of this method is analogous to checking the <a
-     * href="{@docRoot}/java.base/java/lang/Double.html#repEquivalence">representation
-     * equivalence</a> of {@code double} values.
+     * The behavior of this method is analogous to checking the
+     * {@linkplain Double##repEquivalence representation equivalence}
+     * of {@code double} values.
      *
      * @param  x {@code Object} to which this {@code BigDecimal} is
      *         to be compared.

src/java.base/share/classes/java/net/spi/InetAddressResolverProvider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2021, 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
@@ -41,8 +41,8 @@
  *
  * <p> A given invocation of the Java virtual machine maintains a single
  * system-wide resolver instance, which is used by
- * <a href="{@docRoot}/java.base/java/net/InetAddress.html#host-name-resolution">
- * InetAddress</a>. It is set after the VM is fully initialized and when an
+ * {@linkplain InetAddress##host-name-resolution
+ * InetAddress}. It is set after the VM is fully initialized and when an
  * invocation of a method in {@link InetAddress} class triggers the first lookup
  * operation.
  *
@@ -60,8 +60,8 @@
  *      method. The returned {@code InetAddressResolver} will be set as the
  *      system-wide resolver.
  *  <li>If the previous step fails to find any resolver provider the
- *      <a href="{@docRoot}/java.base/java/net/InetAddress.html#built-in-resolver">
- *      built-in resolver</a> will be set as the system-wide resolver.
+ *      {@linkplain InetAddress##built-in-resolver
+ *      built-in resolver} will be set as the system-wide resolver.
  * </ol>
  *
  * <p> If instantiating a custom resolver from a provider discovered in

src/java.base/share/classes/java/util/Collection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2018, 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
@@ -280,10 +280,10 @@ public interface Collection<E> extends Iterable<E> {
      *         element
      * @throws ClassCastException if the type of the specified element
      *         is incompatible with this collection
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         collection does not permit null elements
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      */
     boolean contains(Object o);
 
@@ -463,10 +463,10 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
      * @return {@code true} if an element was removed as a result of this call
      * @throws ClassCastException if the type of the specified element
      *         is incompatible with this collection
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         collection does not permit null elements
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws UnsupportedOperationException if the {@code remove} operation
      *         is not supported by this collection
      */
@@ -485,11 +485,11 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
      * @throws ClassCastException if the types of one or more elements
      *         in the specified collection are incompatible with this
      *         collection
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified collection contains one
      *         or more null elements and this collection does not permit null
      *         elements
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
+     *         ({@linkplain Collection##optional-restrictions optional})
      *         or if the specified collection is null.
      * @see    #contains(Object)
      */
@@ -535,11 +535,11 @@ default <T> T[] toArray(IntFunction<T[]> generator) {
      * @throws ClassCastException if the types of one or more elements
      *         in this collection are incompatible with the specified
      *         collection
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if this collection contains one or more
      *         null elements and the specified collection does not support
      *         null elements
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
+     *         ({@linkplain Collection##optional-restrictions optional})
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)
@@ -594,11 +594,11 @@ default boolean removeIf(Predicate<? super E> filter) {
      * @throws ClassCastException if the types of one or more elements
      *         in this collection are incompatible with the specified
      *         collection
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if this collection contains one or more
      *         null elements and the specified collection does not permit null
      *         elements
-     *         (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>),
+     *         ({@linkplain Collection##optional-restrictions optional})
      *         or if the specified collection is null
      * @see #remove(Object)
      * @see #contains(Object)

src/java.base/share/classes/java/util/Deque.java

@@ -363,10 +363,10 @@ public interface Deque<E> extends Queue<E> {
      * @return {@code true} if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
      *         is incompatible with this deque
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      */
     boolean removeFirstOccurrence(Object o);
 
@@ -382,10 +382,10 @@ public interface Deque<E> extends Queue<E> {
      * @return {@code true} if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
      *         is incompatible with this deque
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      */
     boolean removeLastOccurrence(Object o);
 
@@ -565,10 +565,10 @@ public interface Deque<E> extends Queue<E> {
      * @return {@code true} if an element was removed as a result of this call
      * @throws ClassCastException if the class of the specified element
      *         is incompatible with this deque
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      */
     boolean remove(Object o);
 
@@ -581,10 +581,10 @@ public interface Deque<E> extends Queue<E> {
      * @return {@code true} if this deque contains the specified element
      * @throws ClassCastException if the class of the specified element
      *         is incompatible with this deque
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements
-     * (<a href="{@docRoot}/java.base/java/util/Collection.html#optional-restrictions">optional</a>)
+     *         ({@linkplain Collection##optional-restrictions optional})
      */
     boolean contains(Object o);