Pretty docstrings (#6417)

* add metatag rescript codeblocks

* remove deprecated attr to js_promise.res

* remove deprecated attr from docstrings

* update

* remove deprecated comments

* add  header

* dedent comments

* fixes

* fixes

* last edits

* update js_math.ml

* update CHANGELOG.md

* more polish

* update CHANGELOG.md

* restore release.ninja

* restore release.ninja

* [skip ci]: update CHANGELOG.md

CHANGELOG.md

@@ -21,6 +21,10 @@
 
 - GenType: now emits full suffix on JS import path to be compatible with `.res.js`. https://github.com/rescript-lang/rescript-compiler/pull/6541
 
+#### :nail_care: Polish
+
+- Format docstrings. https://github.com/rescript-lang/rescript-compiler/pull/6417
+
 # 11.0.0-rc.8
 
 #### :rocket: New Feature

jscomp/others/belt.res

@@ -40,7 +40,9 @@ Belt provides:
 
 To use modules from Belt, either refer to them by their fully qualified name (`Belt.List`, `Belt.Array` etc.) or open the `Belt` module by putting
 
-```
+## Examples
+
+```rescript
 open Belt
 ```
 
@@ -49,7 +51,9 @@ at the top of your source files. After opening Belt this way, `Array` will refer
 If you want to open Belt globally for all files in your project instead, you can put
 
 ```json
-  "bsc-flags": ["-open Belt"],
+{
+  "bsc-flags": ["-open Belt"]
+}
 ```
 
 into your `bsconfig.json`.
@@ -58,7 +62,9 @@ into your `bsconfig.json`.
 
 Example usage:
 
-```
+## Examples
+
+```rescript
 let someNumbers = [1, 1, 4, 2, 3, 6, 3, 4, 2]
 
 let greaterThan2UniqueAndSorted =
@@ -81,7 +87,9 @@ available:
 
 E.g.:
 
-```
+## Examples
+
+```rescript
 let forEach: (t<'a>, 'a => unit) => unit
 
 let forEachU: (t<'a>, (. 'a) => unit) => unit
@@ -91,7 +99,9 @@ The uncurried version will be faster in some cases, but for simplicity we recomm
 
 The two versions can be invoked as follows:
 
-```
+## Examples
+
+```rescript
 ["a", "b", "c"]->Belt.Array.forEach(x => Js.log(x))
 
 ["a", "b", "c"]->Belt.Array.forEachU((. x) => Js.log(x))
@@ -104,16 +114,18 @@ For collections types like set or map, Belt provides both a generic module as we
 For example, Belt has the following set modules:
 
 - [Belt.Set](belt/set)
-- [Belt.Set.Int](belt/set-int)
-- [Belt.Set.String](belt/set-string)
+- [Belt.Set.Int](belt/set/int)
+- [Belt.Set.String](belt/set/string)
 
 ## Implementation Details
 
 ### Array access runtime safety
 
 One common confusion comes from the way Belt handles array access. It differs from than the default standard library's.
 
-```
+## Examples
+
+```rescript
 let letters = ["a", "b", "c"]
 let a = letters[0] // a == "a"
 let capitalA = Js.String.toUpperCase(a)
@@ -122,7 +134,9 @@ let k = letters[10] // Raises an exception! The 10th index doesn't exist.
 
 Because Belt avoids exceptions and returns `options` instead, this code behaves differently:
 
-```
+## Examples
+
+```rescript
 open Belt
 let letters = ["a", "b", "c"]
 let a = letters[0] // a == Some("a")
@@ -138,7 +152,9 @@ Although we've fixed the problem where `k` raises an exception, we now have a ty
 
 Fortunately, this is easy to fix:
 
-```res example
+## Examples
+
+```rescript
 open Belt
 let letters = ["a", "b", "c"]
 let a = letters[0]
@@ -161,7 +177,9 @@ When we create a collection library for a custom data type we need a way to prov
 
 We use a phantom type to solve the problem:
 
-```
+## Examples
+
+```rescript
 module Comparable1 =
   Belt.Id.MakeComparable(
     {
@@ -193,7 +211,9 @@ let mySet2 = Belt.Set.make(~id=module(Comparable2))
 
 Here, the compiler would infer `mySet1` and `mySet2` having different type, so e.g. a `merge` operation that tries to merge these two sets will correctly fail.
 
-```
+## Examples
+
+```rescript
 let mySet1: t<(int, int), Comparable1.identity>
 let mySet2: t<(int, int), Comparable2.identity>
 ```