Add some docs to stblib Symbol (#7336)

Author: jderochervlk

packages/artifacts.txt

@@ -1177,7 +1177,9 @@ lib/ocaml/Stdlib_String.resi
 lib/ocaml/Stdlib_Symbol.cmi
 lib/ocaml/Stdlib_Symbol.cmj
 lib/ocaml/Stdlib_Symbol.cmt
+lib/ocaml/Stdlib_Symbol.cmti
 lib/ocaml/Stdlib_Symbol.res
+lib/ocaml/Stdlib_Symbol.resi
 lib/ocaml/Stdlib_Type.cmi
 lib/ocaml/Stdlib_Type.cmj
 lib/ocaml/Stdlib_Type.cmt

runtime/Stdlib_Symbol.res

@@ -1,19 +1,25 @@
 type t
 
 @val external make: string => t = "Symbol"
-@val external getFor: string => t = "Symbol.for"
-@val external keyFor: t => option<string> = "Symbol.keyFor"
+@val @scope("Symbol")
+external getFor: string => option<t> = "for"
+@val @scope("Symbol") external keyFor: t => option<string> = "keyFor"
+@get
+external description: t => option<string> = "description"
+@send external toString: t => string = "toString"
 
-@val external asyncIterator: t = "Symbol.asyncIterator"
-@val external hasInstance: t = "Symbol.hasInstance"
-@val external isConcatSpreadable: t = "Symbol.isConcatSpreadable"
-@val external iterator: t = "Symbol.iterator"
-@val external match: t = "Symbol.match"
-@val external matchAll: t = "Symbol.matchAll"
-@val external replace: t = "Symbol.replace"
-@val external search: t = "Symbol.search"
-@val external species: t = "Symbol.species"
-@val external split: t = "Symbol.split"
-@val external toPrimitive: t = "Symbol.toPrimitive"
-@val external toStringTag: t = "Symbol.toStringTag"
-@val external unscopables: t = "Symbol.unscopables"
+@val @scope("Symbol")
+external asyncIterator: t = "asyncIterator"
+@val @scope("Symbol")
+external hasInstance: t = "hasInstance"
+@val @scope("Symbol") external isConcatSpreadable: t = "isConcatSpreadable"
+@val @scope("Symbol") external iterator: t = "iterator"
+@val @scope("Symbol") external match: t = "match"
+@val @scope("Symbol") external matchAll: t = "matchAll"
+@val @scope("Symbol") external replace: t = "replace"
+@val @scope("Symbol") external search: t = "search"
+@val @scope("Symbol") external species: t = "species"
+@val @scope("Symbol") external split: t = "split"
+@val @scope("Symbol") external toPrimitive: t = "toPrimitive"
+@val @scope("Symbol") external toStringTag: t = "toStringTag"
+@val @scope("Symbol") external unscopables: t = "unscopables"

runtime/Stdlib_Symbol.resi

@@ -0,0 +1,105 @@
+/***
+A built-in object that serves as a namespace for globally-unique identifiers.
+
+Compiles to a regular JavaScript Symbol.
+*/
+
+/**
+Type representing a Symbol.
+*/
+type t
+
+/**
+`make(key)`
+
+Makes a new unique Symbol value.
+
+## Examples
+
+```rescript
+Symbol.make("sym1")
+->Symbol.description
+->assertEqual(Some("sym1"))
+```
+*/
+@val
+external make: string => t = "Symbol"
+
+/**
+`getFor(key)`
+
+Searches for existing registered Symbols in the global Symbol registry with the given key and returns it if found. 
+Otherwise a new Symbol gets created and registered with key.
+
+## Examples
+
+```rescript
+Symbol.getFor("sym1")->assertEqual(Symbol.getFor("sym1"))
+```
+*/
+@val
+@scope("Symbol")
+external getFor: string => option<t> = "for"
+
+/**
+`keyFor(key)`
+
+Retrieves a shared Symbol key from the global Symbol registry for the given Symbol.
+
+## Examples
+
+```rescript
+let globalSym = Symbol.getFor("sym1") // Global symbol
+
+globalSym->Option.flatMap(Symbol.description)->assertEqual(Some("sym1"))
+```
+*/
+@val
+@scope("Symbol")
+external keyFor: t => option<string> = "keyFor"
+
+/**
+`description`
+
+Returns `Some(string)` containing the description of this symbol, or `None` if the symbol has no description.
+## Examples
+
+```rescript
+let sym = Symbol.make("sym1")
+Symbol.description(sym)->assertEqual(Some("sym1"))
+```
+*/
+@get
+external description: t => option<string> = "description"
+
+/**
+`toString`
+
+// Returns a string representing this symbol value.
+
+## Examples
+
+```rescript
+let sym = Symbol.make("sym1")
+
+Symbol.toString(sym)->assertEqual("Symbol(sym1)")
+```
+*/
+@send
+external toString: t => string = "toString"
+
+@val @scope("Symbol")
+external asyncIterator: t = "asyncIterator"
+@val @scope("Symbol")
+external hasInstance: t = "hasInstance"
+@val @scope("Symbol") external isConcatSpreadable: t = "isConcatSpreadable"
+@val @scope("Symbol") external iterator: t = "iterator"
+@val @scope("Symbol") external match: t = "match"
+@val @scope("Symbol") external matchAll: t = "matchAll"
+@val @scope("Symbol") external replace: t = "replace"
+@val @scope("Symbol") external search: t = "search"
+@val @scope("Symbol") external species: t = "species"
+@val @scope("Symbol") external split: t = "split"
+@val @scope("Symbol") external toPrimitive: t = "toPrimitive"
+@val @scope("Symbol") external toStringTag: t = "toStringTag"
+@val @scope("Symbol") external unscopables: t = "unscopables"