feat(graindoc): Refactored Graindoc parser (#1658)

.github/workflows/ci.yml

@@ -73,6 +73,7 @@ jobs:
       - name: Check parser error messages exhaustiveness
         run: |
           npm run compiler parser:check-errors
+          npm run compiler graindoc-parser:check-errors
 
       # Formatting lint last because building is more important
       - name: Run formatting lint

compiler/esy.json

@@ -38,7 +38,7 @@
     "@opam/dune-configurator": ">= 3.6.1 < 4.0.0",
     "@opam/fp": "0.0.1",
     "@opam/fs": "0.0.2",
-    "@opam/menhir": "20211125",
+    "@opam/menhir": "20220210",
     "@opam/ocamlgraph": ">= 2.0.0 < 3.0.0",
     "@opam/ppx_deriving": ">= 5.2.1 < 6.0.0",
     "@opam/ppx_deriving_cmdliner": ">= 0.6.1",

compiler/graindoc/docblock.re

@@ -8,7 +8,7 @@ type t = {
   name: string,
   type_sig: string,
   description: option(string),
-  attributes: list(Comments.Attribute.t),
+  attributes: Comments.Attribute.attributes,
 };
 
 exception
@@ -163,7 +163,7 @@ let for_value_description =
 
   let (args, returns) = types_for_function(~ident, vd);
   // This replaces the default `None` for `attr_type` on `Param` and `Returns` attributes
-  let apply_types: (int, Comments.Attribute.t) => Comments.Attribute.t =
+  let apply_types: (int, Comment_attributes.t) => Comment_attributes.t =
     (idx, attr) => {
       switch (attr) {
       | Param(attr) =>
@@ -252,7 +252,7 @@ let to_markdown = (~current_version, docblock) => {
   let deprecations =
     docblock.attributes
     |> List.filter(Comments.Attribute.is_deprecated)
-    |> List.map((attr: Comments.Attribute.t) => {
+    |> List.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | Deprecated({attr_desc}) => attr_desc
          | _ =>
@@ -275,7 +275,7 @@ let to_markdown = (~current_version, docblock) => {
   let since_attr =
     docblock.attributes
     |> List.find_opt(Comments.Attribute.is_since)
-    |> Option.map((attr: Comments.Attribute.t) => {
+    |> Option.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | Since({attr_version}) =>
            output_for_since(~current_version, attr_version)
@@ -286,7 +286,7 @@ let to_markdown = (~current_version, docblock) => {
   let history_attrs =
     docblock.attributes
     |> List.filter(Comments.Attribute.is_history)
-    |> List.map((attr: Comments.Attribute.t) => {
+    |> List.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | History({attr_version, attr_desc}) =>
            output_for_history(~current_version, attr_version, attr_desc)
@@ -315,7 +315,7 @@ let to_markdown = (~current_version, docblock) => {
   let params =
     docblock.attributes
     |> List.filter(Comments.Attribute.is_param)
-    |> List.map((attr: Comments.Attribute.t) => {
+    |> List.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | Param({attr_name, attr_type, attr_desc}) => [
              Markdown.code(attr_name),
@@ -336,7 +336,7 @@ let to_markdown = (~current_version, docblock) => {
   let returns =
     docblock.attributes
     |> List.filter(Comments.Attribute.is_returns)
-    |> List.map((attr: Comments.Attribute.t) => {
+    |> List.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | Returns({attr_type, attr_desc}) => [
              Option.fold(~none="", ~some=Markdown.code, attr_type),
@@ -357,7 +357,7 @@ let to_markdown = (~current_version, docblock) => {
     docblock.attributes
     |> List.filter(Comments.Attribute.is_throws)
     |> List.fold_left(
-         (map, attr: Comments.Attribute.t) => {
+         (map, attr: Comment_attributes.t) => {
            switch (attr) {
            | Throws({attr_type: Some(attr_type), attr_desc}) =>
              StringMap.update(
@@ -400,7 +400,7 @@ let to_markdown = (~current_version, docblock) => {
   let examples =
     docblock.attributes
     |> List.filter(Comments.Attribute.is_example)
-    |> List.map((attr: Comments.Attribute.t) => {
+    |> List.map((attr: Comment_attributes.t) => {
          switch (attr) {
          | Example({attr_desc}) => attr_desc
          | _ =>

compiler/graindoc/graindoc.re

@@ -100,7 +100,7 @@ let generate_docs =
     let deprecations =
       attrs
       |> List.filter(Comments.Attribute.is_deprecated)
-      |> List.map((attr: Comments.Attribute.t) => {
+      |> List.map((attr: Comment_attributes.t) => {
            switch (attr) {
            | Deprecated({attr_desc}) => attr_desc
            | _ =>
@@ -130,7 +130,7 @@ let generate_docs =
     let since_attr =
       attrs
       |> List.find_opt(Comments.Attribute.is_since)
-      |> Option.map((attr: Comments.Attribute.t) => {
+      |> Option.map((attr: Comment_attributes.t) => {
            switch (attr) {
            | Since({attr_version}) =>
              Docblock.output_for_since(~current_version, attr_version)
@@ -141,7 +141,7 @@ let generate_docs =
     let history_attrs =
       attrs
       |> List.filter(Comments.Attribute.is_history)
-      |> List.map((attr: Comments.Attribute.t) => {
+      |> List.map((attr: Comment_attributes.t) => {
            switch (attr) {
            | History({attr_version, attr_desc}) =>
              Docblock.output_for_history(
@@ -168,7 +168,7 @@ let generate_docs =
     let example_attrs = attrs |> List.filter(Comments.Attribute.is_example);
     if (List.length(example_attrs) > 0) {
       List.iter(
-        (attr: Comments.Attribute.t) => {
+        (attr: Comment_attributes.t) => {
           switch (attr) {
           | Example({attr_desc}) =>
             Buffer.add_string(buf, Markdown.code_block(attr_desc))
@@ -218,7 +218,7 @@ let generate_docs =
             next_section_start_line,
           );
         List.iter(
-          (attr: Comments.Attribute.t) => {
+          (attr: Comment_attributes.t) => {
             switch (attr) {
             | Section({attr_name, attr_desc}) =>
               Buffer.add_string(buf, Markdown.heading(~level=2, attr_name));

compiler/package.json

@@ -31,6 +31,11 @@
     "parser:list-errors": "esy b menhir src/parsing/parser.mly --unused-tokens --list-errors > src/parsing/parser.messages.generated",
     "parser:update-errors": "esy b menhir src/parsing/parser.mly --unused-tokens --update-errors src/parsing/parser.messages > src/parsing/parser.messages.generated && cp src/parsing/parser.messages.generated src/parsing/parser.messages",
     "parser:check-errors": "npm run parser:list-errors && esy b menhir src/parsing/parser.mly --unused-tokens --compare-errors src/parsing/parser.messages.generated --compare-errors src/parsing/parser.messages",
+    "graindoc-parser:interpret": "esy b menhir src/diagnostics/graindoc_parser.mly --unused-tokens --interpret",
+    "graindoc-parser:interpret-error": "esy b menhir src/diagnostics/graindoc_parser.mly --unused-tokens --interpret-error",
+    "graindoc-parser:list-errors": "esy b menhir src/diagnostics/graindoc_parser.mly --unused-tokens --list-errors > src/diagnostics/graindoc_parser.messages.generated",
+    "graindoc-parser:update-errors": "esy b menhir src/diagnostics/graindoc_parser.mly --unused-tokens --update-errors src/diagnostics/graindoc_parser.messages > src/diagnostics/graindoc_parser.messages.generated && cp src/diagnostics/graindoc_parser.messages.generated src/diagnostics/graindoc_parser.messages",
+    "graindoc-parser:check-errors": "npm run graindoc-parser:list-errors && esy b menhir src/diagnostics/graindoc_parser.mly --unused-tokens --compare-errors src/diagnostics/graindoc_parser.messages.generated --compare-errors src/diagnostics/graindoc_parser.messages",
     "import-dependencies": "esy import-dependencies _export",
     "export-dependencies": "esy export-dependencies",
     "build-dependencies": "esy build-dependencies"

compiler/src/diagnostics/comment_attributes.re

@@ -0,0 +1,37 @@
+exception InvalidAttribute(string);
+exception MalformedAttribute(string, string);
+
+type attr_name = string;
+type attr_desc = string;
+// The `attr_type` always starts as `None` and is applied later by something like Graindoc
+type attr_type = option(string);
+type attr_version = string;
+
+type t =
+  | Param({
+      attr_name,
+      attr_type,
+      attr_desc,
+    })
+  | Returns({
+      attr_desc,
+      attr_type,
+    })
+  // Currently only accepts single-line examples
+  | Example({attr_desc})
+  | Section({
+      attr_name,
+      attr_desc,
+    })
+  | Deprecated({attr_desc})
+  | Since({attr_version})
+  | History({
+      attr_version,
+      attr_desc,
+    })
+  | Throws({
+      attr_type,
+      attr_desc,
+    });
+
+type parsed_graindoc = (option(string), list(t));