Format docstrings with the new format tools command (#7623)

* format docstrings with the new format tools command

* handle piped assertEqual

* compiled files

* add extraction command for code blocks

* change transform to only work on structure items

* refactor

* change code block extraction approach to use the typed artifacts instead, since we need more info for each block than we do for formatting

* add ExtractCodeBlocks to RescriptTools for simplicity

* integrate code block extraction into doctests script

* only include code blocks with tests in them

* update analysis examples

* fix last remaining format issues in runtime docstrings

* update analysis test files

* more test output

* changelog

* fix changelog

Author: zth

CHANGELOG.md

@@ -25,6 +25,10 @@
 - Clean up `config.ml`. https://github.com/rescript-lang/rescript/pull/7636
 - Rewatch: simplify getting bsc path. https://github.com/rescript-lang/rescript/pull/7634
 
+#### :rocket: New Feature
+
+- Add experimental command to `rescript-tools` for extracting all ReScript code blocks from markdown, either a md-file directly, or inside of docstrings in ReScript code. https://github.com/rescript-lang/rescript/pull/7623
+
 # 12.0.0-beta.1
 
 #### :rocket: New Feature

analysis/src/Protocol.ml

@@ -137,6 +137,11 @@ let optWrapInQuotes s =
   | None -> None
   | Some s -> Some (wrapInQuotes s)
 
+let stringifyResult = function
+  | Ok r -> stringifyObject [("TAG", Some (wrapInQuotes "Ok")); ("_0", Some r)]
+  | Error e ->
+    stringifyObject [("TAG", Some (wrapInQuotes "Error")); ("_0", Some e)]
+
 let stringifyCompletionItem c =
   stringifyObject
     [

lib/es6/RescriptTools.js

@@ -3,7 +3,10 @@
 
 let Docgen;
 
+let ExtractCodeBlocks;
+
 export {
   Docgen,
+  ExtractCodeBlocks,
 }
 /* No side effect */

lib/es6/RescriptTools_ExtractCodeBlocks.js

@@ -0,0 +1 @@
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

lib/es6/Stdlib.js

@@ -12,7 +12,7 @@ function assertEqual(a, b) {
     RE_EXN_ID: "Assert_failure",
     _1: [
       "Stdlib.res",
-      124,
+      122,
       4
     ],
     Error: new Error()

lib/js/RescriptTools.js

@@ -3,5 +3,8 @@
 
 let Docgen;
 
+let ExtractCodeBlocks;
+
 exports.Docgen = Docgen;
+exports.ExtractCodeBlocks = ExtractCodeBlocks;
 /* No side effect */

lib/js/RescriptTools_ExtractCodeBlocks.js

@@ -0,0 +1 @@
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

lib/js/Stdlib.js

@@ -12,7 +12,7 @@ function assertEqual(a, b) {
     RE_EXN_ID: "Assert_failure",
     _1: [
       "Stdlib.res",
-      124,
+      122,
       4
     ],
     Error: new Error()

runtime/Belt.res

@@ -130,16 +130,15 @@ let letters = ["a", "b", "c"]
 let a = letters[0]
 
 // Use a switch statement:
-let capitalA =
-  switch a {
-  | Some(a) => Some(Js.String.toUpperCase(a))
-  | None => None
-  }
+let capitalA = switch a {
+| Some(a) => Some(Js.String.toUpperCase(a))
+| None => None
+}
 
 let k = letters[10] // k == None
 ```
 
-With that little bit of tweaking, our code now compiles successfully and is 100% free of runtime errors!
+With that little bit of tweaking, our code now compiles successfully and is 100% free of runtime errors\!
 
 ### A Special Encoding for Collection Safety
 
@@ -150,31 +149,25 @@ We use a phantom type to solve the problem:
 ## Examples
 
 ```rescript
-module Comparable1 =
-  Belt.Id.MakeComparable(
-    {
-      type t = (int, int)
-      let cmp = ((a0, a1), (b0, b1)) =>
-        switch Pervasives.compare(a0, b0) {
-        | 0 => Pervasives.compare(a1, b1)
-        | c => c
-        }
+module Comparable1 = Belt.Id.MakeComparable({
+  type t = (int, int)
+  let cmp = ((a0, a1), (b0, b1)) =>
+    switch Pervasives.compare(a0, b0) {
+    | 0 => Pervasives.compare(a1, b1)
+    | c => c
     }
-  )
+})
 
 let mySet1 = Belt.Set.make(~id=module(Comparable1))
 
-module Comparable2 =
-  Belt.Id.MakeComparable(
-    {
-      type t = (int, int)
-      let cmp = ((a0, a1), (b0, b1)) =>
-        switch Pervasives.compare(a0, b0) {
-        | 0 => Pervasives.compare(a1, b1)
-        | c => c
-        }
+module Comparable2 = Belt.Id.MakeComparable({
+  type t = (int, int)
+  let cmp = ((a0, a1), (b0, b1)) =>
+    switch Pervasives.compare(a0, b0) {
+    | 0 => Pervasives.compare(a1, b1)
+    | c => c
     }
-  )
+})
 
 let mySet2 = Belt.Set.make(~id=module(Comparable2))
 ```
@@ -184,8 +177,8 @@ Here, the compiler would infer `mySet1` and `mySet2` having different type, so e
 ## Examples
 
 ```rescript
-let mySet1: t<(int, int), Comparable1.identity>
-let mySet2: t<(int, int), Comparable2.identity>
+let mySet1: t<(int, int), Comparable1.identity> = %todo
+let mySet2: t<(int, int), Comparable2.identity> = %todo
 ```
 
 `Comparable1.identity` and `Comparable2.identity` are not the same using our encoding scheme.