Make caps.Capability non-experimental (#23507)

Closes #22745.

Make `scala.caps.Capability` non-experimental.

The `Capability` trait can be used as a marker trait even outside of
capture-checking.
Only when capture checking is enabled, the trait carries a special
meaning, marking each instance a top-level capability.

Other definitions inside the `scala.caps` package (the package is
already non-experimental) stays experimental
and can only be used with `-experimental` or with capture-checking
enabled (with an import or with the feature flag).

Author: natsukagami

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -2112,8 +2112,8 @@ class Definitions {
    */
   @tu lazy val ccExperimental: Set[Symbol] = Set(
     CapsModule, CapsModule.moduleClass, PureClass,
-    Caps_Capability, // TODO: Remove when Capability is stabilized
-    Caps_Classifier, Caps_SharedCapability, Caps_Control, Caps_ExclusiveCapability, Caps_Mutable, Caps_Read,
+    /* Caps_Classifier, Caps_SharedCapability, Caps_Control, -- already stable */
+    Caps_ExclusiveCapability, Caps_Mutable, Caps_Read,
     RequiresCapabilityAnnot,
     captureRoot, Caps_CapSet, Caps_ContainsTrait, Caps_ContainsModule, Caps_ContainsModule.moduleClass,
     ConsumeAnnot, UseAnnot, ReserveAnnot,

library/src/scala/caps/package.scala

@@ -22,43 +22,58 @@ import annotation.{experimental, compileTimeOnly, retainsCap}
  * But even without capture checking, extending this trait can be useful for documenting the intended purpose
  * of a class.
  *
- * Capability has exactly two subtraits: Shared and Exclusive.
+ * Capability has exactly two subtraits: [[SharedCapability Shared]] and [[ExclusiveCapability Exclusive]].
  */
-@experimental
 sealed trait Capability extends Any
 
 /** A marker trait for classifier capabilities that can appear in `.only`
  *  qualifiers. Capability classes directly extending `Classifier` are treated
- *  as classifier capbilities
+ *  as classifier capbilities.
+ *
+ * [[Classifier]] has a formal meaning when
+ * [[scala.language.experimental.captureChecking Capture Checking]]
+ * is turned on. It should not be used outside of capture checking.
  */
-@experimental
 trait Classifier
 
 /** The universal capture reference. */
 @experimental
 object cap extends Capability
 
 /** Marker trait for capabilities that can be safely shared in a concurrent context.
+ *
+ * [[SharedCapability]] has a formal meaning when
+ * [[scala.language.experimental.captureChecking Capture Checking]]
+ * is turned on.
  * During separation checking, shared capabilities are not taken into account.
  */
-@experimental
 trait SharedCapability extends Capability, Classifier
 
 @experimental
 type Shared = SharedCapability
 
-/** Marker trait for exclusive capabilities that are separation-checked
+/** Marker trait for capabilities that should only be used by one concurrent process
+ *  at a given time. For example, write-access to a shared mutable buffer.
+ *
+ * [[ExclusiveCapability]] has a formal meaning when
+ * [[scala.language.experimental.captureChecking Capture Checking]]
+ * is turned on.
+ * During separation checking, exclusive usage of marked capabilities will be enforced.
  */
 @experimental
 trait ExclusiveCapability extends Capability, Classifier
 
 @experimental
 type Exclusive = ExclusiveCapability
 
-/** Base trait for capabilities that capture some continuation or return point in
- *  the stack. Examples are exceptions, labels, Async, CanThrow.
+/** Marker trait for capabilities that capture some continuation or return point in
+ *  the stack. Examples are exceptions, [[scala.util.boundary.Label labels]], [[scala.CanThrow CanThrow]]
+ *  or Async contexts.
+ *
+ * [[Control]] has a formal meaning when
+ * [[scala.language.experimental.captureChecking Capture Checking]]
+ * is turned on.
  */
-@experimental
 trait Control extends SharedCapability, Classifier
 
 /** Marker trait for classes with methods that require an exclusive reference. */

project/MiMaFilters.scala

@@ -28,6 +28,10 @@ object MiMaFilters {
         ProblemFilters.exclude[MissingClassProblem]("scala.annotation.internal.onlyCapability"),
         ProblemFilters.exclude[MissingFieldProblem]("scala.runtime.stdLibPatches.language#experimental.separationChecking"),
         ProblemFilters.exclude[MissingClassProblem]("scala.runtime.stdLibPatches.language$experimental$separationChecking$"),
+        ProblemFilters.exclude[MissingClassProblem]("scala.caps.Capability"),
+        ProblemFilters.exclude[MissingClassProblem]("scala.caps.Classifier"),
+        ProblemFilters.exclude[MissingClassProblem]("scala.caps.SharedCapability"),
+        ProblemFilters.exclude[MissingClassProblem]("scala.caps.Control"),
       ),
 
       // Additions since last LTS

tests/run-tasty-inspector/stdlibExperimentalDefinitions.scala

@@ -32,17 +32,13 @@ val experimentalDefinitionInLibrary = Set(
   "scala.annotation.retainsCap",
   "scala.Pure",
   "scala.caps.CapSet",
-  "scala.caps.Capability",
-  "scala.caps.Classifier",
   "scala.caps.Contains",
   "scala.caps.Contains$",
   "scala.caps.Contains$.containsImpl",
   "scala.caps.Exists",
-  "scala.caps.SharedCapability",
   "scala.caps.ExclusiveCapability",
   "scala.caps.Mutable",
   "scala.caps.Read",
-  "scala.caps.Control",
   "scala.caps.consume",
   "scala.caps.internal",
   "scala.caps.internal$",