Enable Starlark sets by default

Now that the Starlark language spec has been approved: https://github.com/bazelbuild/starlark/blob/master/spec.md#sets

Require elements of arguments to StarlarkSet methods to be hashable, matching
the final version of the language spec.

Take the opportunity to update our documentation to match the spec whenever
reasonable (modulo minor differences in terminology and formatting).

RELNOTES: Flip --experimental_enable_starlark_set and enable the Starlark set data type by default.
PiperOrigin-RevId: 707659085
Change-Id: Ibcad59838f9709e980d7b69f4957b8f0fede51c6

Author: tetromino

src/main/java/com/google/devtools/build/lib/packages/semantics/BuildLanguageOptions.java

@@ -808,7 +808,7 @@ public final class BuildLanguageOptions extends OptionsBase {
 
   @Option(
       name = "experimental_enable_starlark_set",
-      defaultValue = "false",
+      defaultValue = "true",
       documentationCategory = OptionDocumentationCategory.STARLARK_SEMANTICS,
       effectTags = {OptionEffectTag.BUILD_FILE_SEMANTICS},
       metadataTags = {OptionMetadataTag.EXPERIMENTAL},

src/main/java/net/starlark/java/eval/MethodLibrary.java

@@ -641,13 +641,24 @@ public StarlarkInt intForStarlark(Object x, Object baseO) throws EvalException {
   @StarlarkMethod(
       name = "set",
       doc =
-          "<b>Experimental</b>. This API is experimental and may change at any time. Please do not"
-              + " depend on it. It may be enabled on an experimental basis by setting"
-              + " <code>--experimental_enable_starlark_set</code>.\n" //
-              + "<p>Creates a new <a href=\"../core/set.html\">set</a>, optionally initialized to"
-              + " contain the elements from a given iterable.",
+          """
+Creates a new <a href=\"../core/set.html\">set</a> containing the unique elements of a given
+iterable, preserving iteration order.
+
+<p>If called with no argument, <code>set()</code> returns a new empty set.
+
+<p>For example,
+<pre class=language-python>
+set()                          # an empty set
+set([3, 1, 1, 2])              # set([3, 1, 2]), a set of three elements
+set({"k1": "v1", "k2": "v2"})  # set(["k1", "k2"]), a set of two elements
+</pre>
+""",
       parameters = {
-        @Param(name = "elements", defaultValue = "[]", doc = "A set, sequence, or dict."),
+        @Param(
+            name = "elements",
+            defaultValue = "[]",
+            doc = "A set, a sequence of hashable values, or a dict."),
       },
       useStarlarkThread = true)
   public StarlarkSet<Object> set(Object elements, StarlarkThread thread) throws EvalException {

src/main/java/net/starlark/java/eval/StarlarkSemantics.java

@@ -258,5 +258,5 @@ public final String toString() {
   public static final String ALLOW_RECURSION = "-allow_recursion";
 
   /** Whether StarlarkSet objects may be constructed by the interpreter. */
-  public static final String EXPERIMENTAL_ENABLE_STARLARK_SET = "-experimental_enable_starlark_set";
+  public static final String EXPERIMENTAL_ENABLE_STARLARK_SET = "+experimental_enable_starlark_set";
 }