Merge pull request scala/scala#10293 from som-snytt/issue/12710-stringbuilder-doc

Tweak class doc for StringBuilder

Author: som-snytt

library/src/scala/Array.scala

@@ -624,7 +624,7 @@ object Array {
  *
  *  @see [[https://www.scala-lang.org/files/archive/spec/2.13/ Scala Language Specification]], for in-depth information on the transformations the Scala compiler makes on Arrays (Sections 6.6 and 6.15 respectively.)
  *  @see [[https://docs.scala-lang.org/sips/scala-2-8-arrays.html "Scala 2.8 Arrays"]] the Scala Improvement Document detailing arrays since Scala 2.8.
- *  @see [[https://docs.scala-lang.org/overviews/collections/arrays.html "The Scala 2.8 Collections' API"]] section on `Array` by Martin Odersky for more information.
+ *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/arrays.html "The Scala 2.8 Collections' API"]] section on `Array` by Martin Odersky for more information.
  *  @hideImplicitConversion scala.Predef.booleanArrayOps
  *  @hideImplicitConversion scala.Predef.byteArrayOps
  *  @hideImplicitConversion scala.Predef.charArrayOps

library/src/scala/collection/concurrent/Map.scala

@@ -19,7 +19,7 @@ import scala.annotation.tailrec
   *
   *  $concurrentmapinfo
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#concurrent_maps "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#concurrent_maps "Scala's Collection Library overview"]]
   *  section on `Concurrent Maps` for more information.
   *
   *  @tparam K  the key type of the map

library/src/scala/collection/immutable/BitSet.scala

@@ -20,7 +20,7 @@ import scala.annotation.{implicitNotFound, nowarn}
 
 /** A class for immutable bitsets.
   *  $bitsetinfo
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#immutable-bitsets "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#immutable-bitsets "Scala's Collection Library overview"]]
   *  section on `Immutable BitSets` for more information.
   *
   *  @define Coll `immutable.BitSet`

library/src/scala/collection/immutable/LazyList.scala

@@ -220,7 +220,7 @@ import scala.runtime.Statics
   *
   *  @tparam A    the type of the elements contained in this lazy list.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#lazylists "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#lazylists "Scala's Collection Library overview"]]
   *  section on `LazyLists` for more information.
   *  @define Coll `LazyList`
   *  @define coll lazy list

library/src/scala/collection/immutable/List.scala

@@ -65,7 +65,7 @@ import scala.runtime.Statics.releaseFence
   *        objects that rely on structural sharing), will be serialized and deserialized with multiple lists, one for
   *        each reference to it. I.e. structural sharing is lost after serialization/deserialization.
   *
-  *  @see  [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#lists "Scala's Collection Library overview"]]
+  *  @see  [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#lists "Scala's Collection Library overview"]]
   *  section on `Lists` for more information.
   *
   *  @define coll list

library/src/scala/collection/immutable/ListMap.scala

@@ -119,7 +119,7 @@ sealed class ListMap[K, +V]
   * n elements will take O(n^2^) time. This makes the builder suitable only for a small number of
   * elements.
   *
-  * @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#list-maps "Scala's Collection Library overview"]]
+  * @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#list-maps "Scala's Collection Library overview"]]
   * section on `List Maps` for more information.
   * @define Coll ListMap
   * @define coll list map

library/src/scala/collection/immutable/Queue.scala

@@ -27,7 +27,7 @@ import scala.collection.mutable.{Builder, ListBuffer}
   *  where a pivot is required, in which case, a cost of `O(n)` is incurred, where `n` is the number of elements in the queue. When this happens,
   *  `n` remove operations with `O(1)` cost are guaranteed. Removing an item is on average `O(1)`.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#immutable-queues "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#immutable-queues "Scala's Collection Library overview"]]
   *  section on `Immutable Queues` for more information.
   *
   *  @define Coll `immutable.Queue`

library/src/scala/collection/immutable/TreeMap.scala

@@ -60,7 +60,7 @@ import scala.runtime.AbstractFunction2
   *  @tparam V         the type of the values associated with the keys.
   *  @param ordering   the implicit ordering used to compare objects of type `A`.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#red-black-trees "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#red-black-trees "Scala's Collection Library overview"]]
   *  section on `Red-Black Trees` for more information.
   *
   *  @define Coll immutable.TreeMap

library/src/scala/collection/immutable/TreeSet.scala

@@ -26,7 +26,7 @@ import scala.runtime.AbstractFunction1
   *  @tparam A         the type of the elements contained in this tree set
   *  @param ordering   the implicit ordering used to compare objects of type `A`
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-immutable-collection-classes.html#red-black-trees "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html#red-black-trees "Scala's Collection Library overview"]]
   *  section on `Red-Black Trees` for more information.
   *
   *  @define Coll `immutable.TreeSet`

library/src/scala/collection/mutable/ArrayBuffer.scala

@@ -26,7 +26,7 @@ import scala.collection.generic.DefaultSerializable
   *  access take constant time (amortized time). Prepends and removes are
   *  linear in the buffer size.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#array-buffers "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#array-buffers "Scala's Collection Library overview"]]
   *  section on `Array Buffers` for more information.
 
   *

library/src/scala/collection/mutable/BitSet.scala

@@ -23,7 +23,7 @@ import scala.annotation.implicitNotFound
   *
   * $bitsetinfo
   *
-  * @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#mutable-bitsets "Scala's Collection Library overview"]]
+  * @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#mutable-bitsets "Scala's Collection Library overview"]]
   * section on `Mutable Bitsets` for more information.
   *
   * @define Coll `BitSet`

library/src/scala/collection/mutable/CollisionProofHashMap.scala

@@ -24,7 +24,7 @@ import scala.runtime.Statics
   * as determined by the `Ordering` has to be consistent with `equals` and `hashCode`. Universal equality
   * of numeric types is not supported (similar to `AnyRefMap`).
   *
-  * @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
+  * @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
   * section on `Hash Tables` for more information.
   *
   * @define Coll `mutable.CollisionProofHashMap`

library/src/scala/collection/mutable/HashMap.scala

@@ -20,7 +20,7 @@ import scala.util.hashing.MurmurHash3
 
 /** This class implements mutable maps using a hashtable.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
   *  section on `Hash Tables` for more information.
   *
   *  @tparam K    the type of the keys contained in this hash map.

library/src/scala/collection/mutable/HashSet.scala

@@ -20,7 +20,7 @@ import scala.util.hashing.MurmurHash3
 
 /** This class implements mutable sets using a hashtable.
   *
-  * @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
+  * @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#hash-tables "Scala's Collection Library overview"]]
   * section on `Hash Tables` for more information.
   *
   * @define Coll `mutable.HashSet`

library/src/scala/collection/mutable/ListBuffer.scala

@@ -23,7 +23,7 @@ import scala.runtime.Statics.releaseFence
 /** A `Buffer` implementation backed by a list. It provides constant time
   *  prepend and append. Most other operations are linear.
   *
-  *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#list-buffers "Scala's Collection Library overview"]]
+  *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#list-buffers "Scala's Collection Library overview"]]
   *  section on `List Buffers` for more information.
   *
   *  @tparam A    the type of this list buffer's elements.

library/src/scala/collection/mutable/StringBuilder.scala

@@ -24,17 +24,30 @@ import scala.Predef.{ // unimport char-related implicit conversions to avoid tri
  //_
 }
 
-/** A builder for mutable sequence of characters.  This class provides an API
-  * mostly compatible with `java.lang.StringBuilder`, except where there are
-  * conflicts with the Scala collections API (such as the `reverse` method.)
-  *
-  * $multipleResults
-  *
-  * @define Coll `mutable.IndexedSeq`
-  * @define coll string builder
-  * @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#stringbuilders "Scala's Collection Library overview"]]
-  * section on `StringBuilders` for more information.
-  */
+/** A builder of `String` which is also a mutable sequence of characters.
+ *
+ *  This class provides an API mostly compatible with `java.lang.StringBuilder`,
+ *  except where there are conflicts with the Scala collections API, such as the `reverse` method:
+ *  [[reverse]] produces a new `StringBuilder`, and [[reverseInPlace]] mutates this builder.
+ *
+ *  Mutating operations return either `this.type`, i.e., the current builder, or `Unit`.
+ *
+ *  Other methods extract data or information from the builder without mutating it.
+ *
+ *  The distinction is also reflected in naming conventions used by collections,
+ *  such as `append`, which mutates, and `appended`, which does not, or `reverse`,
+ *  which does not mutate, and `reverseInPlace`, which does.
+ *
+ *  The `String` result may be obtained using either `result()` or `toString`.
+ *
+ *  $multipleResults
+ *
+ *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#stringbuilders "Scala's Collection Library overview"]]
+ *  section on `StringBuilders` for more information.
+ *
+ *  @define Coll `mutable.IndexedSeq`
+ *  @define coll string builder
+ */
 @SerialVersionUID(3L)
 final class StringBuilder(val underlying: java.lang.StringBuilder) extends AbstractSeq[Char]
   with ReusableBuilder[Char, String]

library/src/scala/collection/mutable/WeakHashMap.scala

@@ -24,7 +24,7 @@ import scala.collection.convert.JavaCollectionWrappers.{JMapWrapper, JMapWrapper
  *  @tparam K      type of keys contained in this map
  *  @tparam V      type of values associated with the keys
  *
- *  @see [[https://docs.scala-lang.org/overviews/collections/concrete-mutable-collection-classes.html#weak-hash-maps "Scala's Collection Library overview"]]
+ *  @see [[https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html#weak-hash-maps "Scala's Collection Library overview"]]
  *  section on `Weak Hash Maps` for more information.
  *
  *  @define Coll `WeakHashMap`