Add missing docstring for String (#7571)

nojaf · web-flow · commit d6fc76aab2cc · 2025-07-04T08:27:07.000+02:00
* Add missing docstring for String * Update analysis snapshot * Remove Symbol functions from String module * Add changelog entry * Revert "Remove Symbol functions from String module" This reverts commit 44193d3. * Revert "Add changelog entry" This reverts commit e28d75e. * Update String doc samples * Remove symbol bindings * Update analysis tests
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -15,6 +15,9 @@
 #### :boom: Breaking Change
 
 - The legacy rescript cli can be called through rewatch via `rewatch legacy`. Arguments to rewatch need to be passed after the subcommand. Argument `--compiler-args` is now a subcommand `compiler-args`. https://github.com/rescript-lang/rescript/pull/7551
+- Remove `String.getSymbol` from standard library. https://github.com/rescript-lang/rescript/pull/7571
+- Remove `String.getSymbolUnsafe` from standard library. https://github.com/rescript-lang/rescript/pull/7571
+- Remove `String.setSymbol` from standard library. https://github.com/rescript-lang/rescript/pull/7571
 
 #### :rocket: New Feature
 
diff --git a/runtime/Stdlib_String.res b/runtime/Stdlib_String.res
@@ -164,10 +164,6 @@ external splitByRegExpAtMost: (string, Stdlib_RegExp.t, ~limit: int) => array<op
 @send external padStart: (string, int, string) => string = "padStart"
 @send external padEnd: (string, int, string) => string = "padEnd"
 
-@get_index external getSymbol: (string, Stdlib_Symbol.t) => option<'a> = ""
-@get_index external getSymbolUnsafe: (string, Stdlib_Symbol.t) => 'a = ""
-@set_index external setSymbol: (string, Stdlib_Symbol.t, 'a) => unit = ""
-
 @send external localeCompare: (string, string) => float = "localeCompare"
 
 external ignore: string => unit = "%ignore"
diff --git a/runtime/Stdlib_String.resi b/runtime/Stdlib_String.resi
@@ -121,8 +121,30 @@ String.fromCodePointMany([0xd55c, 0xae00, 0x1f63a]) == `한글😺`
 @variadic @val
 external fromCodePointMany: array<int> => string = "String.fromCodePoint"
 
+/**
+`equal(str1, str2)` checks if two strings are equal.
+
+## Examples
+
+```rescript
+String.equal("hello", "hello") == true
+String.equal("hello", "world") == false
+String.equal("", "") == true
+```
+*/
 external equal: (string, string) => bool = "%equal"
 
+/**
+`compare(str1, str2)` compares two strings, returns an `Ordering.t` value.
+
+## Examples
+
+```rescript
+String.compare("hello", "hello") == Ordering.equal
+String.compare("apple", "banana") == Ordering.less
+String.compare("zebra", "apple") == Ordering.greater
+```
+*/
 external compare: (string, string) => Stdlib_Ordering.t = "%compare"
 
 /**
@@ -1090,11 +1112,6 @@ String.padEnd("abc", 1, "") == "abc"
 @send
 external padEnd: (string, int, string) => string = "padEnd"
 
-// TODO: add docs
-@get_index external getSymbol: (string, Stdlib_Symbol.t) => option<'a> = ""
-@get_index external getSymbolUnsafe: (string, Stdlib_Symbol.t) => 'a = ""
-@set_index external setSymbol: (string, Stdlib_Symbol.t, 'a) => unit = ""
-
 /**
 `localeCompare(referenceStr, compareStr)` returns a float than indicatings
 whether a reference string comes before or after, or is the same as the given
diff --git a/tests/analysis_tests/tests/src/expected/CompletionJsx.res.txt b/tests/analysis_tests/tests/src/expected/CompletionJsx.res.txt
@@ -785,6 +785,30 @@ Path s
       "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
       "newText": ""
       }]
+  }, {
+    "label": "->String.startsWith",
+    "kind": 12,
+    "tags": [],
+    "detail": "(string, string) => bool",
+    "documentation": {"kind": "markdown", "value": "\n`startsWith(str, substr)` returns `true` if the `str` starts with `substr`,\n`false` otherwise.\nSee [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN.\n\n## Examples\n\n```rescript\nString.startsWith(\"BuckleScript\", \"Buckle\") == true\nString.startsWith(\"BuckleScript\", \"\") == true\nString.startsWith(\"JavaScript\", \"Buckle\") == false\n```\n"},
+    "sortText": "startsWith",
+    "insertText": "->String.startsWith",
+    "additionalTextEdits": [{
+      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
+      "newText": ""
+      }]
+  }, {
+    "label": "->String.splitAtMost",
+    "kind": 12,
+    "tags": [],
+    "detail": "(string, string, ~limit: int) => array<string>",
+    "documentation": {"kind": "markdown", "value": "\n`splitAtMost(str, delimiter, ~limit)` splits the given `str` at every\noccurrence of `delimiter` and returns an array of the first `limit` resulting\nsubstrings. If `limit` is negative or greater than the number of substrings,\nthe array will contain all the substrings.\n\n## Examples\n\n```rescript\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=3) == [\"ant\", \"bee\", \"cat\"]\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=0) == []\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=9) == [\"ant\", \"bee\", \"cat\", \"dog\", \"elk\"]\n```\n"},
+    "sortText": "splitAtMost",
+    "insertText": "->String.splitAtMost",
+    "additionalTextEdits": [{
+      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
+      "newText": ""
+      }]
   }, {
     "label": "->String.searchOpt",
     "kind": 12,
@@ -821,42 +845,6 @@ Path s
       "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
       "newText": ""
       }]
-  }, {
-    "label": "->String.substringToEnd",
-    "kind": 12,
-    "tags": [],
-    "detail": "(string, ~start: int) => string",
-    "documentation": {"kind": "markdown", "value": "\n`substringToEnd(str, ~start)` returns the substring of `str` from position\n`start` to the end.\n- If `start` is less than or equal to zero, the entire string is returned.\n- If `start` is greater than or equal to the length of `str`, the empty string\nis returned.\nSee [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN.\n\n## Examples\n\n```rescript\nString.substringToEnd(\"playground\", ~start=4) == \"ground\"\nString.substringToEnd(\"playground\", ~start=-3) == \"playground\"\nString.substringToEnd(\"playground\", ~start=12) == \"\"\n```\n"},
-    "sortText": "substringToEnd",
-    "insertText": "->String.substringToEnd",
-    "additionalTextEdits": [{
-      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
-      "newText": ""
-      }]
-  }, {
-    "label": "->String.startsWith",
-    "kind": 12,
-    "tags": [],
-    "detail": "(string, string) => bool",
-    "documentation": {"kind": "markdown", "value": "\n`startsWith(str, substr)` returns `true` if the `str` starts with `substr`,\n`false` otherwise.\nSee [`String.startsWith`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith) on MDN.\n\n## Examples\n\n```rescript\nString.startsWith(\"BuckleScript\", \"Buckle\") == true\nString.startsWith(\"BuckleScript\", \"\") == true\nString.startsWith(\"JavaScript\", \"Buckle\") == false\n```\n"},
-    "sortText": "startsWith",
-    "insertText": "->String.startsWith",
-    "additionalTextEdits": [{
-      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
-      "newText": ""
-      }]
-  }, {
-    "label": "->String.splitAtMost",
-    "kind": 12,
-    "tags": [],
-    "detail": "(string, string, ~limit: int) => array<string>",
-    "documentation": {"kind": "markdown", "value": "\n`splitAtMost(str, delimiter, ~limit)` splits the given `str` at every\noccurrence of `delimiter` and returns an array of the first `limit` resulting\nsubstrings. If `limit` is negative or greater than the number of substrings,\nthe array will contain all the substrings.\n\n## Examples\n\n```rescript\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=3) == [\"ant\", \"bee\", \"cat\"]\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=0) == []\nString.splitAtMost(\"ant/bee/cat/dog/elk\", \"/\", ~limit=9) == [\"ant\", \"bee\", \"cat\", \"dog\", \"elk\"]\n```\n"},
-    "sortText": "splitAtMost",
-    "insertText": "->String.splitAtMost",
-    "additionalTextEdits": [{
-      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
-      "newText": ""
-      }]
   }, {
     "label": "->String.sliceToEnd",
     "kind": 12,
@@ -869,18 +857,6 @@ Path s
       "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
       "newText": ""
       }]
-  }, {
-    "label": "->String.setSymbol",
-    "kind": 12,
-    "tags": [],
-    "detail": "(string, Symbol.t, 'a) => unit",
-    "documentation": null,
-    "sortText": "setSymbol",
-    "insertText": "->String.setSymbol",
-    "additionalTextEdits": [{
-      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
-      "newText": ""
-      }]
   }, {
     "label": "->String.splitByRegExp",
     "kind": 12,
@@ -941,5 +917,17 @@ Path s
       "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
       "newText": ""
       }]
+  }, {
+    "label": "->String.substringToEnd",
+    "kind": 12,
+    "tags": [],
+    "detail": "(string, ~start: int) => string",
+    "documentation": {"kind": "markdown", "value": "\n`substringToEnd(str, ~start)` returns the substring of `str` from position\n`start` to the end.\n- If `start` is less than or equal to zero, the entire string is returned.\n- If `start` is greater than or equal to the length of `str`, the empty string\nis returned.\nSee [`String.substring`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/substring) on MDN.\n\n## Examples\n\n```rescript\nString.substringToEnd(\"playground\", ~start=4) == \"ground\"\nString.substringToEnd(\"playground\", ~start=-3) == \"playground\"\nString.substringToEnd(\"playground\", ~start=12) == \"\"\n```\n"},
+    "sortText": "substringToEnd",
+    "insertText": "->String.substringToEnd",
+    "additionalTextEdits": [{
+      "range": {"start": {"line": 93, "character": 17}, "end": {"line": 93, "character": 18}},
+      "newText": ""
+      }]
   }]
 
diff --git a/tests/analysis_tests/tests/src/expected/DotPipeCompletionSpec.res.txt b/tests/analysis_tests/tests/src/expected/DotPipeCompletionSpec.res.txt
@@ -418,25 +418,25 @@ Path Array.joinWith
 Path Stdlib.String.includ
 Path includ
 [{
-    "label": "->String.includes",
+    "label": "->String.includesFrom",
     "kind": 12,
     "tags": [],
-    "detail": "(string, string) => bool",
-    "documentation": {"kind": "markdown", "value": "\n`includes(str, searchValue)` returns `true` if `searchValue` is found anywhere\nwithin `str`, `false` otherwise.\nSee [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN.\n\n## Examples\n\n```rescript\nString.includes(\"programmer\", \"gram\") == true\nString.includes(\"programmer\", \"er\") == true\nString.includes(\"programmer\", \"pro\") == true\nString.includes(\"programmer.dat\", \"xyz\") == false\n```\n"},
-    "sortText": "includes",
-    "insertText": "->String.includes",
+    "detail": "(string, string, int) => bool",
+    "documentation": {"kind": "markdown", "value": "\n`includesFrom(str, searchValue, start)` returns `true` if `searchValue` is found\nanywhere within `str` starting at character number `start` (where 0 is the\nfirst character), `false` otherwise.\nSee [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN.\n\n## Examples\n\n```rescript\nString.includesFrom(\"programmer\", \"gram\", 1) == true\nString.includesFrom(\"programmer\", \"gram\", 4) == false\nString.includesFrom(`대한민국`, `한`, 1) == true\n```\n"},
+    "sortText": "includesFrom",
+    "insertText": "->String.includesFrom",
     "additionalTextEdits": [{
       "range": {"start": {"line": 89, "character": 55}, "end": {"line": 89, "character": 56}},
       "newText": ""
       }]
   }, {
-    "label": "->String.includesFrom",
+    "label": "->String.includes",
     "kind": 12,
     "tags": [],
-    "detail": "(string, string, int) => bool",
-    "documentation": {"kind": "markdown", "value": "\n`includesFrom(str, searchValue, start)` returns `true` if `searchValue` is found\nanywhere within `str` starting at character number `start` (where 0 is the\nfirst character), `false` otherwise.\nSee [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN.\n\n## Examples\n\n```rescript\nString.includesFrom(\"programmer\", \"gram\", 1) == true\nString.includesFrom(\"programmer\", \"gram\", 4) == false\nString.includesFrom(`대한민국`, `한`, 1) == true\n```\n"},
-    "sortText": "includesFrom",
-    "insertText": "->String.includesFrom",
+    "detail": "(string, string) => bool",
+    "documentation": {"kind": "markdown", "value": "\n`includes(str, searchValue)` returns `true` if `searchValue` is found anywhere\nwithin `str`, `false` otherwise.\nSee [`String.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes) on MDN.\n\n## Examples\n\n```rescript\nString.includes(\"programmer\", \"gram\") == true\nString.includes(\"programmer\", \"er\") == true\nString.includes(\"programmer\", \"pro\") == true\nString.includes(\"programmer.dat\", \"xyz\") == false\n```\n"},
+    "sortText": "includes",
+    "insertText": "->String.includes",
     "additionalTextEdits": [{
       "range": {"start": {"line": 89, "character": 55}, "end": {"line": 89, "character": 56}},
       "newText": ""
diff --git a/tests/tests/src/core/Core_TempTests.mjs b/tests/tests/src/core/Core_TempTests.mjs
@@ -249,10 +249,6 @@ let x = Symbol.for("Foo");
 
 console.log(x);
 
-let array$1 = "foo"[Symbol.iterator]().toArray();
-
-console.log(array$1);
-
 console.info("");
 
 console.info("Global namespace");
@@ -338,6 +334,7 @@ export {
   _formatter,
   formatter,
   segments,
+  array,
   date,
   dict,
   dict2,
@@ -354,7 +351,6 @@ export {
   set,
   regexp,
   x,
-  array$1 as array,
   timeout,
   z,
   intFromBigInt,
diff --git a/tests/tests/src/core/Core_TempTests.res b/tests/tests/src/core/Core_TempTests.res
@@ -160,8 +160,6 @@ Console.info("Symbol")
 Console.info("---")
 let x = Symbol.getFor("Foo")
 Console.log(x)
-let array: array<string> = String.getSymbolUnsafe("foo", Symbol.iterator)()->Iterator.toArray
-Console.log(array)
 
 Console.info("")
 Console.info("Global namespace")
