Add missing @param/@tparam/@return Scaladoc tags in scala.util, scala.io, scala.ref (cleanup follow-up)

Author: bvenners

library-js/src/scala/util/DynamicVariable.scala

@@ -62,6 +62,7 @@ class DynamicVariable[T](init: T) {
    *  @tparam S the result type of the thunk, also the return type of this method
    *  @param newval The value to which to set the variable
    *  @param thunk The code to evaluate under the new setting
+   *  @return the result of evaluating `thunk` with the variable temporarily bound to `newval`
    */
   def withValue[S](newval: T)(thunk: => S): S = {
     val oldval = v

library/src/scala/io/BufferedSource.scala

@@ -22,7 +22,8 @@ import scala.collection.mutable.StringBuilder
  *  representation of a source file.
  *
  *  @param inputStream the underlying input stream to read characters from
- *  @param bufferSize the size of the internal buffer used for reading
+ *  @param bufferSize the size, in characters, of the internal buffer used for reading
+ *  @param codec the `Codec` used to decode bytes from the input stream into characters
  */
 class BufferedSource(inputStream: InputStream, bufferSize: Int)(implicit val codec: Codec) extends Source {
   def this(inputStream: InputStream)(implicit codec: Codec) = this(inputStream, DefaultBufSize)(using codec)
@@ -96,8 +97,8 @@ class BufferedSource(inputStream: InputStream, bufferSize: Int)(implicit val cod
    *  memory.
    *
    *  @param sb the string builder to append to
-   *  @param start the string to prepend before the first character
-   *  @param sep the separator string inserted between elements
+   *  @param start the string to prepend before the first element
+   *  @param sep the separator string inserted between elements; passing an empty string enables the efficient bulk-read path
    *  @param end the string to append after the last element
    *  @return the string builder `sb` with all elements appended
    */

library/src/scala/io/Position.scala

@@ -68,6 +68,7 @@ private[scala] abstract class Position {
    *
    *  @param line the 1-based line number, or 0 for undefined; values at or above `LINE_MASK` are clamped and the column is set to 0
    *  @param column the 1-based column number, or 0 for undefined; clamped to `COLUMN_MASK`, ignored when `line` >= `LINE_MASK`
+   *  @return the encoded position as a non-negative integer that packs the line number in the high bits and the column number in the low bits, suitable for decoding with `line`, `column`, and `toString`
    */
   final def encode(line: Int, column: Int): Int = {
     checkInput(line, column)
@@ -81,18 +82,21 @@ private[scala] abstract class Position {
   /** Returns the line number of the encoded position.
    *
    *  @param pos the encoded position as returned by `encode`
+   *  @return the 1-based line number extracted from `pos`, or 0 if the line is undefined
    */
   final def line(pos: Int): Int = (pos >> COLUMN_BITS) & LINE_MASK
 
   /** Returns the column number of the encoded position.
    *
    *  @param pos the encoded position as returned by `encode`
+   *  @return the 1-based column number extracted from `pos`, or 0 if the column is undefined
    */
   final def column(pos: Int): Int = pos & COLUMN_MASK
 
   /** Returns a string representation of the encoded position.
    *
    *  @param pos the encoded position as returned by `encode`
+   *  @return a string in the form `"line:column"` using the decoded line and column numbers
    */
   def toString(pos: Int): String = line(pos) + ":" + column(pos)
 }

library/src/scala/io/Source.scala

@@ -41,18 +41,21 @@ object Source {
   /** Creates a Source instance from a single character.
    *
    *  @param c the character to use as the source content
+   *  @return a `Source` that yields the single character `c`
    */
   def fromChar(c: Char): Source = fromIterable(Array(c))
 
   /** Creates Source from array of characters, with empty description.
    *
    *  @param chars the array of characters to use as the source content
+   *  @return a `Source` that yields the characters from `chars`
    */
   def fromChars(chars: Array[Char]): Source = fromIterable(chars)
 
   /** Creates Source from a String, with no description.
    *
    *  @param s the string to use as the source content
+   *  @return a `Source` that yields the characters of `s`
    */
   def fromString(s: String): Source = fromIterable(s)
 
@@ -61,6 +64,7 @@ object Source {
    *
    *  @param name the name of the file to read
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from the named file, described by its filename
    */
   def fromFile(name: String)(implicit codec: Codec): BufferedSource =
     fromFile(new JFile(name))(using codec)
@@ -70,6 +74,7 @@ object Source {
    *
    *  @param name the name of the file to read
    *  @param enc the name of the character encoding to use
+   *  @return a `BufferedSource` reading from the named file with the given encoding
    */
   def fromFile(name: String, enc: String): BufferedSource =
     fromFile(name)(using Codec(enc))
@@ -78,6 +83,7 @@ object Source {
    *
    *  @param uri the file URI to read from
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from the file referenced by `uri`
    */
   def fromFile(uri: URI)(implicit codec: Codec): BufferedSource =
     fromFile(new JFile(uri))(using codec)
@@ -86,6 +92,7 @@ object Source {
    *
    *  @param uri the file URI to read from
    *  @param enc the name of the character encoding to use
+   *  @return a `BufferedSource` reading from the file referenced by `uri` with the given encoding
    */
   def fromFile(uri: URI, enc: String): BufferedSource =
     fromFile(uri)(using Codec(enc))
@@ -95,6 +102,7 @@ object Source {
    *
    *  @param file the file to read from
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from `file` with the default buffer size
    */
   def fromFile(file: JFile)(implicit codec: Codec): BufferedSource =
     fromFile(file, Source.DefaultBufSize)(using codec)
@@ -103,6 +111,7 @@ object Source {
    *
    *  @param file the file to read from
    *  @param enc the name of the character encoding to use
+   *  @return a `BufferedSource` reading from `file` with the given encoding
    */
   def fromFile(file: JFile, enc: String): BufferedSource =
     fromFile(file)(using Codec(enc))
@@ -117,6 +126,7 @@ object Source {
    *  @param file the file to read from
    *  @param bufferSize the size of the input buffer, in characters
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from `file` with the given buffer size, described by the file's absolute path
    */
   def fromFile(file: JFile, bufferSize: Int)(implicit codec: Codec): BufferedSource = {
     val inputStream = new FileInputStream(file)
@@ -134,7 +144,7 @@ object Source {
    *
    *  @param bytes the array of bytes to decode into characters
    *  @param codec the implicit codec used for character encoding
-   *  @return      the created `Source` instance.
+   *  @return      a `Source` that yields the characters decoded from `bytes` using `codec`
    */
   def fromBytes(bytes: Array[Byte])(implicit codec: Codec): Source =
     fromString(new String(bytes, codec.name))
@@ -153,6 +163,7 @@ object Source {
    *
    *  @param uri the file URI to read from
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from the file referenced by `uri`
    */
   def fromURI(uri: URI)(implicit codec: Codec): BufferedSource =
     fromFile(new JFile(uri))(using codec)
@@ -161,6 +172,7 @@ object Source {
    *
    *  @param s the URL string to read from
    *  @param enc the name of the character encoding to use
+   *  @return a `BufferedSource` reading from the URL given by `s` with the given encoding
    */
   def fromURL(s: String, enc: String): BufferedSource =
     fromURL(s)(using Codec(enc))
@@ -169,6 +181,7 @@ object Source {
    *
    *  @param s the URL string to read from
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from the URL given by `s`
    */
   def fromURL(s: String)(implicit codec: Codec): BufferedSource =
     fromURL(new URI(s).toURL)(using codec)
@@ -177,6 +190,7 @@ object Source {
    *
    *  @param url the URL to read from
    *  @param enc the name of the character encoding to use
+   *  @return a `BufferedSource` reading from the stream opened on `url` with the given encoding
    */
   def fromURL(url: URL, enc: String): BufferedSource =
     fromURL(url)(using Codec(enc))
@@ -185,6 +199,7 @@ object Source {
    *
    *  @param url the URL to read from
    *  @param codec the implicit codec used for character encoding
+   *  @return a `BufferedSource` reading from the stream opened on `url`
    */
   def fromURL(url: URL)(implicit codec: Codec): BufferedSource =
     fromInputStream(url.openStream())(using codec)
@@ -197,7 +212,7 @@ object Source {
    *  @param  reset        a () => Source which resets the stream (if unset, reset() will throw an Exception)
    *  @param  close        a () => Unit method which closes the stream (if unset, close() will do nothing)
    *  @param  codec        (implicit) a scala.io.Codec specifying behavior (defaults to Codec.default)
-   *  @return              the buffered source
+   *  @return              a `BufferedSource` reading from `inputStream` with the given buffer size
    */
   def createBufferedSource(
     inputStream: InputStream,
@@ -221,6 +236,7 @@ object Source {
    *
    *  @param  resource     name of the resource to load from the classpath
    *  @param  classLoader  classloader to be used, or context classloader if not specified
+   *  @param codec the implicit codec used for character encoding
    *  @return              the buffered source
    */
   def fromResource(resource: String, classLoader: ClassLoader = Thread.currentThread().getContextClassLoader())(implicit codec: Codec): BufferedSource =
@@ -406,6 +422,7 @@ abstract class Source extends Iterator[Char] with Closeable {
   /** Change or disable the positioner.
    *
    *  @param on whether to enable (`true`) or disable (`false`) position tracking
+   *  @return this `Source`, to allow chained configuration calls
    */
   def withPositioning(on: Boolean): this.type = {
     positioner = if (on) RelaxedPositioner else NoPositioner

library/src/scala/ref/SoftReference.scala

@@ -26,15 +26,17 @@ object SoftReference {
 
   /** Creates a `SoftReference` pointing to `value`.
    *
-   *  @tparam T the type of the referenced object, must be a reference type
+   *  @tparam T the type of the referenced object; must be a subtype of `AnyRef`
    *  @param value the object to be softly referenced; may be reclaimed by the garbage collector when memory is low
+   *  @return a new `SoftReference` wrapping `value`
    */
   def apply[T <: AnyRef](value: T): SoftReference[T] = new SoftReference(value)
 
   /** Optionally returns the referenced value, or `None` if that value no longer exists.
    *
-   *  @tparam T the type of the referenced object, must be a reference type
+   *  @tparam T the type of the referenced object; must be a subtype of `AnyRef`
    *  @param sr the `SoftReference` to extract the value from
+   *  @return `Some(value)` if the referent has not been reclaimed, otherwise `None`
    */
   def unapply[T <: AnyRef](sr: SoftReference[T]): Option[T] = Option(sr.underlying.get)
 }

library/src/scala/ref/WeakReference.scala

@@ -35,13 +35,15 @@ object WeakReference {
    *
    *  @tparam T the type of the value to wrap in a weak reference
    *  @param value the object to be weakly referenced
+   *  @return a new `WeakReference` wrapping `value`
    */
   def apply[T <: AnyRef](value: T): WeakReference[T] = new WeakReference(value)
 
   /** Optionally returns the referenced value, or `None` if that value no longer exists.
    *
    *  @tparam T the type of the value to extract from the weak reference
    *  @param wr the weak reference to extract a value from
+   *  @return `Some(value)` if the referent is still reachable, or `None` if it has been garbage collected
    */
   def unapply[T <: AnyRef](wr: WeakReference[T]): Option[T] = Option(wr.underlying.get)
 }

library/src/scala/util/CommandLineParser.scala

@@ -17,6 +17,7 @@ object CommandLineParser {
    *  @param str the command line argument string to parse
    *  @param n the zero-based index of the argument, used for error reporting
    *  @param fs the type class instance (usually provided implicitly) that converts a string to type `T`
+   *  @return the value of type `T` parsed from `str`
    *  @throws ParseError if argument cannot be converted to type `T`.
    */
   def parseString[T](str: String, n: Int)(using fs: FromString[T]^): T = {
@@ -32,6 +33,7 @@ object CommandLineParser {
    *  @param args the command line arguments array
    *  @param n the zero-based index of the argument to parse
    *  @param fs the type class instance that converts a string to type `T`
+   *  @return the value of type `T` parsed from the argument at index `n`
    *  @throws ParseError if argument does not exist or cannot be converted to type `T`.
    */
   def parseArgument[T](args: Array[String], n: Int)(using fs: FromString[T]^): T =
@@ -44,6 +46,7 @@ object CommandLineParser {
    *  @param args the command line arguments array
    *  @param n the zero-based index of the first remaining argument to parse
    *  @param fs the type class instance that converts a string to type `T`
+   *  @return a list of values of type `T` parsed from arguments at indices `n` through the end, or an empty list if `n` is past the last argument
    *  @throws ParseError if some of the arguments cannot be converted to type `T`.
    */
   def parseRemainingArguments[T](args: Array[String], n: Int)(using fs: FromString[T]^): List[T] =
@@ -66,6 +69,7 @@ object CommandLineParser {
     /** Can throw java.lang.IllegalArgumentException.
      *
      *  @param s the string to convert to type `T`
+     *  @return the value of type `T` parsed from `s`
      */
     def fromString(s: String): T
 

library/src/scala/util/DynamicVariable.scala

@@ -57,6 +57,7 @@ class DynamicVariable[T](init: T) {
    *  @tparam S the result type of the thunk
    *  @param newval the value to which to set the variable
    *  @param thunk the code to evaluate under the new setting
+   *  @return the result of evaluating `thunk` with the variable bound to `newval`
    */
   def withValue[S](newval: T)(thunk: => S): S = {
     val oldval = value

library/src/scala/util/Either.scala

@@ -422,6 +422,7 @@ sealed abstract class Either[+A, +B] extends Product with Serializable {
    *  @tparam A1 the supertype of `A` used to widen the left type
    *  @tparam B1 the right type of the resulting `Either`
    *  @param f the function to bind across `Right`
+   *  @return the result of applying `f` if this is a `Right`, otherwise the unchanged `Left`
    */
   def flatMap[A1 >: A, B1](f: B => Either[A1, B1]): Either[A1, B1] = this match {
     case Right(b) => f(b)
@@ -563,6 +564,7 @@ final case class Left[+A, +B](value: A) extends Either[A, B] {
    *  ```
    *
    *  @tparam B1 the target right type to widen to
+   *  @return this `Left` typed as `Either[A, B1]`
    */
   def withRight[B1 >: B]: Either[A, B1] = this
 
@@ -585,6 +587,7 @@ final case class Right[+A, +B](value: B) extends Either[A, B] {
    *  ```
    *
    *  @tparam A1 the target left type to widen to
+   *  @return this `Right` typed as `Either[A1, B]`
    */
   def withLeft[A1 >: A]: Either[A1, B] = this
 
@@ -915,6 +918,7 @@ object Either {
      *  @tparam A1 the supertype of `A` used to widen the left type
      *  @tparam B1 the right type of the resulting `Either`
      *  @param f the function to bind across `Right`
+     *  @return the result of applying `f` if this is a `Right`, otherwise the unchanged `Left`
      */
     def flatMap[A1 >: A, B1](f: B => Either[A1, B1]): Either[A1, B1] = e match {
       case Right(b) => f(b)

library/src/scala/util/FromDigits.scala

@@ -41,6 +41,7 @@ object FromDigits {
      *
      *  @param digits the string representation of the numeric literal to convert
      *  @param radix the base for the number system (e.g. 10 for decimal, 16 for hexadecimal)
+     *  @return the value of type `T` represented by the digit string interpreted in the given radix
      */
     def fromDigits(digits: String, radix: Int): T
   }
@@ -95,6 +96,7 @@ object FromDigits {
    *  @param digits the string representation of the numeric literal to convert
    *  @param radix the base for the number system (e.g. 10 for decimal, 16 for hexadecimal)
    *  @param limit the upper bound for positive values of the result type (e.g. `Int.MaxValue` or `Long.MaxValue`)
+   *  @return the integer value represented by the digit string, as a `Long`
    */
   private def integerFromDigits(digits: String, radix: Int, limit: Long): Long = {
     var value: Long = 0
@@ -126,8 +128,10 @@ object FromDigits {
   }
 
   /** Converts digit string to Int number.
+   *
    *  @param digits            The string to convert
    *  @param radix             The radix
+   *  @return the `Int` value represented by the digit string in the given radix
    *  @throws NumberTooLarge   if number does not fit within Int range
    *  @throws MalformedNumber  if digits is not a legal digit string.
    *                           Legal strings consist only of digits conforming to radix,
@@ -137,8 +141,10 @@ object FromDigits {
     integerFromDigits(digits, radix, Int.MaxValue).toInt
 
   /** Converts digit string to Long number.
+   *
    *  @param digits            The string to convert
    *  @param radix             The radix
+   *  @return the `Long` value represented by the digit string in the given radix
    *  @throws NumberTooLarge   if the resulting number does not fit within Long range
    *  @throws MalformedNumber  if digits is not a legal digit string.
    *                           Legal strings consist only of digits conforming to radix,
@@ -150,7 +156,9 @@ object FromDigits {
   @sharable private val zeroFloat = raw"-?[0.]+(?:[eE][+-]?[0-9]+)?[fFdD]?".r
 
   /** Converts digit string to Float number.
+   *
    *  @param digits            The string to convert
+   *  @return the `Float` value represented by the digit string
    *  @throws NumberTooLarge   if the resulting number is infinite
    *  @throws NumberTooSmall   if the resulting number is 0.0f, yet the digits
    *                           string contains non-zero digits before the exponent.
@@ -168,7 +176,9 @@ object FromDigits {
   }
 
   /** Converts digit string to Double number.
+   *
    *  @param digits            The string to convert
+   *  @return the `Double` value represented by the digit string
    *  @throws NumberTooLarge   if the resulting number is infinite
    *  @throws NumberTooSmall   if the resulting number is 0.0d, yet the digits
    *                           string contains non-zero digits before the exponent.