Merge pull request #10789 from dotty-staging/scala3doc/lang-import-docs

Document new language imports

Author: abgruszecki

library/src/scala/runtime/stdLibPatches/language.scala

@@ -25,17 +25,38 @@ object language:
      */
     //object dependent
 
-    /** Experimental support for named type arguments */
+    /** Experimental support for named type arguments.
+      *
+      * @see [[https://dotty.epfl.ch/docs/reference/other-new-features/named-typeargs]]
+      */
     object namedTypeArguments
 
-    /** Experimental support for generic number literals */
+    /** Experimental support for generic number literals.
+      *
+      * @see [[https://dotty.epfl.ch/docs/reference/changed-features/numeric-literals]]
+      */
     object genericNumberLiterals
   end experimental
 
-  /** Where imported, auto-tupling is disabled */
+  /** Where imported, auto-tupling is disabled.
+    *
+    * '''Why control the feature?''' Auto-tupling can lead to confusing and
+    * brittle code in presence of overloads. In particular, surprising overloads
+    * can be selected, and adding new overloads can change which overload is selected
+    * in suprising ways.
+    *
+    * '''Why allow it?''' Not allowing auto-tupling is difficult to reconcile with
+    * operators accepting tuples.
+    */
   object noAutoTupling
 
-  /** Where imported, loose equality using eqAny is disabled */
+  /** Where imported, loose equality using eqAny is disabled.
+    *
+    * '''Why allow and control the feature?''' For compatibility and migration reasons,
+    * strict equality is opt-in. See linked documentation for more information.
+    *
+    * @see [[https://dotty.epfl.ch/docs/reference/contextual/multiversal-equality]]
+    */
   object strictEquality
 
   /** Where imported, ad hoc extensions of non-open classes in other
@@ -56,9 +77,27 @@ object language:
    */
   object adhocExtensions
 
-  /** Source version */
+  /** Set source version to 3.0-migration.
+    *
+    * @see [[https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-migration-mode]]
+    */
   object `3.0-migration`
+
+  /** Set source version to 3.0.
+    *
+    * @see [[https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-migration-mode]]
+    */
   object `3.0`
+
+  /** Set source version to 3.1-migration.
+    *
+    * @see [[https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-migration-mode]]
+    */
   object `3.1-migration`
+
+  /** Set source version to 3.1
+    *
+    * @see [[https://scalacenter.github.io/scala-3-migration-guide/docs/scala-3-migration-mode]]
+    */
   object `3.1`
 end language