Added all missing type annotations.

- introduced `ScalaVersionSpecificReturnTypes`;
- split MIMA exclusions by Scala version;
- removed exclusions that are no longer needed;
- made Circle CI task names not mention the exact Scala version;
- provisioned for Scala 2.13-specific code;
- Scala 2.13- is only Scala 2.12 now that Scala 11 is no longer supported :)
- marked classes used by the compiler.

Author: dubinsky

.circleci/config.yml

@@ -92,56 +92,56 @@ workflows:
   build:
     jobs:
       - scala_job:
-          name: 2.12.18
+          name: 2.12.x
           java_version: jdk8
           scala_version: 2.12.18
       - scala_job:
-          name: 2.13.11
+          name: 2.13.x
           java_version: jdk8
           scala_version: 2.13.11
       - scala_job:
-          name: 3.3.0
+          name: 3.x
           java_version: jdk8
           scala_version: 3.3.0
       - scala_job:
-          name: jdk11_2.12
+          name: jdk11_2.12.x
           java_version: jdk11
           scala_version: 2.12.18
       - scala_job:
-          name: jdk11_2.13
+          name: jdk11_2.13.x
           java_version: jdk11
           scala_version: 2.13.11
       - scala_job:
-          name: jdk11_3.1
+          name: jdk11_3.x
           java_version: jdk11
           scala_version: 3.3.0
       - scala_job:
-          name: jdk17_2.12
+          name: jdk17_2.12.x
           java_version: jdk17
           scala_version: 2.12.18
       - scala_job:
-          name: jdk17_2.13
+          name: jdk17_2.13.x
           java_version: jdk17
           scala_version: 2.13.11
       - scala_job:
-          name: jdk17_3.3
+          name: jdk17_3.x
           java_version: jdk17
           scala_version: 3.3.0
       - scalajs_job:
-          name: sjs1.0_2.12
+          name: sjs1.0_2.12.x
           scala_version: 2.12.18
       - scalajs_job:
-          name: sjs1.0_2.13
+          name: sjs1.0_2.13.x
           scala_version: 2.13.11
       - scalajs_job:
-          name: sjs1.0_3.3
+          name: sjs1.0_3.x
           scala_version: 3.3.0
       - scalanative_job:
-          name: native0.4_2.12
+          name: native0.4_2.12.x
           scala_version: 2.12.18
       - scalanative_job:
-          name: native0.4_2.13
+          name: native0.4_2.13.x
           scala_version: 2.13.11
       - scalanative_job:
-          name: native0.4_3
+          name: native0.4_3.x
           scala_version: 3.3.0

build.sbt

@@ -9,20 +9,20 @@ ThisBuild / licenses += (("Apache-2.0", url("https://www.apache.org/licenses/LIC
 ThisBuild / libraryDependencySchemes += "org.scala-js" %% "scalajs-library" % "semver-spec"
 ThisBuild / apiURL := Some(url("https://javadoc.io/doc/org.scala-lang.modules/scala-xml_2.13/"))
 
-lazy val configSettings: Seq[Setting[_]] = Seq(
+lazy val configSettings: Seq[Setting[?]] = Seq(
   unmanagedSourceDirectories ++= {
     unmanagedSourceDirectories.value.flatMap { dir =>
-      val sv = scalaVersion.value
-      Seq(
-        CrossVersion.partialVersion(sv) match {
-          case Some((major, minor)) if major > 2 || (major == 2 && minor >= 13)  => file(dir.getPath ++ "-2.13+")
-          case _             => file(dir.getPath ++ "-2.13-")
-        },
-        CrossVersion.partialVersion(sv) match {
-          case Some((2, _))  => file(dir.getPath ++ "-2.x")
-          case _             => file(dir.getPath ++ "-3.x")
-        }
-      )
+      def forVersion(version: String): File = file(dir.getPath ++ "-" ++ version)
+      CrossVersion.partialVersion(scalaVersion.value) match {
+        case Some((3, _)) => Seq(forVersion("3"), forVersion("2.13+"))
+        case Some((2, minor)) =>
+          Seq(forVersion("2")) ++ (minor match {
+            case 13 => Seq(forVersion("2.13"), forVersion("2.13+"))
+            case 12 => Seq(forVersion("2.12"))
+            case _ => Seq()
+          })
+        case _ => Seq()
+      }
     }
   }
 )
@@ -65,13 +65,21 @@ lazy val xml = crossProject(JSPlatform, JVMPlatform, NativePlatform)
     versionPolicyIntention := Compatibility.BinaryCompatible,
     // Note: See discussion on non-JVM Mima in https://github.com/scala/scala-xml/pull/517
     mimaBinaryIssueFilters ++= {
-      import com.typesafe.tools.mima.core._
-      import com.typesafe.tools.mima.core.ProblemFilters._
-      Seq(
-        // necessitated by the introduction of new abstract methods in FactoryAdapter:
-        exclude[ReversedMissingMethodProblem]("scala.xml.parsing.FactoryAdapter.createComment"),  // see #549
-        exclude[ReversedMissingMethodProblem]("scala.xml.parsing.FactoryAdapter.createPCData")    // see #558
-      )
+      //import com.typesafe.tools.mima.core.{}
+      //import com.typesafe.tools.mima.core.ProblemFilters
+      Seq( // exclusions for all Scala versions
+      ) ++ (CrossVersion.partialVersion(scalaVersion.value) match {
+        case Some((3, _)) => Seq( // Scala 3-specific exclusions
+        )
+        case Some((2, minor)) => Seq( // Scala 2-specific exclusions
+        ) ++ (minor match {
+          case 13 => Seq( // Scala 2.13-specific exclusions
+          )
+          case 12 => Seq( // Scala 2.12-specific exclusions
+          )
+        })
+        case _ => Seq()
+      })
     },
     // Mima signature checking stopped working after 3.0.2 upgrade, see #557
     mimaReportSignatureProblems := (CrossVersion.partialVersion(scalaVersion.value) match {

shared/src/main/scala-2.13-/scala/xml/ScalaVersionSpecific.scala renamed to shared/src/main/scala-2.12/scala/xml/ScalaVersionSpecific.scala

@@ -22,6 +22,7 @@ private[xml] object ScalaVersionSpecific {
     override def apply(from: Coll): mutable.Builder[Node, NodeSeq] = NodeSeq.newBuilder
     override def apply(): mutable.Builder[Node, NodeSeq] = NodeSeq.newBuilder
   }
+  type SeqNodeUnapplySeq = scala.collection.Seq[Node]
 }
 
 private[xml] trait ScalaVersionSpecificNodeSeq extends SeqLike[Node, NodeSeq] { self: NodeSeq =>

shared/src/main/scala-2.13+/scala/xml/ScalaVersionSpecific.scala

@@ -24,6 +24,7 @@ private[xml] object ScalaVersionSpecific {
     def newBuilder(from: Coll): Builder[Node, NodeSeq] = NodeSeq.newBuilder
     def fromSpecific(from: Coll)(it: IterableOnce[Node]): NodeSeq = (NodeSeq.newBuilder ++= from).result()
   }
+  type SeqNodeUnapplySeq = scala.collection.immutable.Seq[Node]
 }
 
 private[xml] trait ScalaVersionSpecificNodeSeq

shared/src/main/scala-2/scala/xml/ScalaVersionSpecificReturnTypes.scala

@@ -0,0 +1,36 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package scala.xml
+
+/*
+ Unlike other Scala-version-specific things, this class is not filling any gaps in capabilities
+ between different versions of Scala; instead, it mostly documents the types that different versions of the
+ Scala compiler inferred in the unfortunate absence of the explicit type annotations.
+ What should have been specified explicitly is given in the comments;
+ next time we break binary compatibility the types should be changed in the code and this class removed.
+ */
+private[xml] object ScalaVersionSpecificReturnTypes { // should be
+  type ExternalIDAttribute = MetaData                 // Null.type
+  type NoExternalIDId = scala.Null
+  type NodeNoAttributes = MetaData                    // Null.type
+  type NullFilter = MetaData                          // Null.type
+  type NullGetNamespace = scala.Null
+  type NullNext = scala.Null
+  type NullKey = scala.Null
+  type NullValue = scala.Null
+  type NullApply1 = scala.collection.Seq[Node]        // scala.Null
+  type NullApply3 = scala.Null
+  type NullRemove = Null.type
+  type SpecialNodeChild = Nil.type
+  type GroupChild = Nothing
+}

shared/src/main/scala-3/scala/xml/ScalaVersionSpecificReturnTypes.scala

@@ -0,0 +1,36 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+package scala.xml
+
+/*
+ Unlike other Scala-version-specific things, this class is not filling any gaps in capabilities
+ between different versions of Scala; instead, it mostly documents the types that different versions of the
+ Scala compiler inferred in the unfortunate absence of the explicit type annotations.
+ What should have been specified explicitly is given in the comments;
+ next time we break binary compatibility the types should be changed in the code and this class removed.
+ */
+private[xml] object ScalaVersionSpecificReturnTypes { // should be
+  type ExternalIDAttribute = MetaData                 // Null.type
+  type NoExternalIDId = String                        // scala.Null
+  type NodeNoAttributes = MetaData                    // Null.type
+  type NullFilter = MetaData                          // Null.type
+  type NullGetNamespace = String                      // scala.Null
+  type NullNext = MetaData                            // scala.Null
+  type NullKey = String                               // scala.Null
+  type NullValue = scala.collection.Seq[Node]         // scala.Null
+  type NullApply1 = scala.collection.Seq[Node]        // scala.Null
+  type NullApply3 = scala.collection.Seq[Node]        // scala.Null
+  type NullRemove = MetaData                          // Null.type
+  type SpecialNodeChild = scala.collection.Seq[Node]  // Nil.type
+  type GroupChild = scala.collection.Seq[Node]        // Nothing
+}

shared/src/main/scala/scala/xml/Attribute.scala

@@ -22,7 +22,7 @@ import scala.collection.Seq
  *  @author  Burak Emir
  */
 object Attribute {
-  def unapply(x: Attribute) /* TODO type annotation */ = x match {
+  def unapply(x: Attribute): Option[(String, Seq[Node], MetaData)] = x match {
     case PrefixedAttribute(_, key, value, next) => Some((key, value, next))
     case UnprefixedAttribute(key, value, next)  => Some((key, value, next))
     case _                                      => None

shared/src/main/scala/scala/xml/Comment.scala

@@ -21,6 +21,7 @@ package xml
  *        and the final character may not be `-` to prevent a closing span of `-->`
  *        which is invalid. [[https://www.w3.org/TR/xml11//#IDA5CES]]
  */
+// Note: used by the Scala compiler.
 case class Comment(commentText: String) extends SpecialNode {
 
   override def label: String = "#REM"

shared/src/main/scala/scala/xml/Elem.scala

@@ -21,15 +21,17 @@ import scala.collection.Seq
  *  any `Node` instance (that is not a `SpecialNode` or a `Group`) using the
  *  syntax `case Elem(prefix, label, attribs, scope, child @ _*) => ...`
  */
+// Note: used by the Scala compiler.
 object Elem {
 
   def apply(prefix: String, label: String, attributes: MetaData, scope: NamespaceBinding, minimizeEmpty: Boolean, child: Node*): Elem =
     new Elem(prefix, label, attributes, scope, minimizeEmpty, child: _*)
 
-  def unapplySeq(n: Node) /* TODO type annotation */ = n match {
-    case _: SpecialNode | _: Group => None
-    case _                         => Some((n.prefix, n.label, n.attributes, n.scope, n.child.toSeq))
-  }
+  def unapplySeq(n: Node): Option[(String, String, MetaData, NamespaceBinding, ScalaVersionSpecific.SeqNodeUnapplySeq)] =
+    n match {
+      case _: SpecialNode | _: Group => None
+      case _                         => Some((n.prefix, n.label, n.attributes, n.scope, n.child.toSeq))
+    }
 }
 
 /**
@@ -51,6 +53,7 @@ object Elem {
  *                       empty; `false` if it should be written out in long form.
  *  @param child         the children of this node
  */
+// Note: used by the Scala compiler.
 class Elem(
   override val prefix: String,
   override val label: String,

shared/src/main/scala/scala/xml/EntityRef.scala

@@ -19,6 +19,7 @@ package xml
  * @author  Burak Emir
  * @param   entityName the name of the entity reference, for example `amp`.
  */
+// Note: used by the Scala compiler.
 case class EntityRef(entityName: String) extends SpecialNode {
   final override def doCollectNamespaces: Boolean = false
   final override def doTransform: Boolean = false