fix(graindoc): Only extract attributes from Doc comments (grain-lang#970

)

compiler/graindoc/docblock.re

@@ -7,7 +7,7 @@ type t = {
   module_name: string,
   name: string,
   type_sig: string,
-  description: string,
+  description: option(string),
   attributes: list(Comments.Attribute.t),
 };
 
@@ -55,7 +55,7 @@ let for_value_description = (~ident: Ident.t, vd: Types.value_description) => {
   let (description, attributes) =
     switch (comment) {
     | Some((_, description, attributes)) => (description, attributes)
-    | None => ("", [])
+    | None => (None, [])
     };
 
   let (args, returns) = types_for_function(vd);
@@ -87,7 +87,7 @@ let for_type_declaration = (~ident: Ident.t, td: Types.type_declaration) => {
   let (description, attributes) =
     switch (comment) {
     | Some((_, description, _)) => (description, [])
-    | None => ("", [])
+    | None => (None, [])
     };
 
   {module_name, name, type_sig, description, attributes};
@@ -190,8 +190,11 @@ let to_markdown = (~current_version, docblock) => {
     Buffer.add_string(buf, Html.details(~disabled, ~summary, details));
   };
   Buffer.add_string(buf, Markdown.code_block(docblock.type_sig));
-  if (String.length(docblock.description) > 0) {
-    Buffer.add_string(buf, Markdown.paragraph(docblock.description));
+  switch (docblock.description) {
+  // Guard isn't be needed because we turn an empty string into None during extraction
+  | Some(description) =>
+    Buffer.add_string(buf, Markdown.paragraph(description))
+  | None => ()
   };
   let params =
     docblock.attributes

compiler/graindoc/graindoc.re

@@ -71,8 +71,10 @@ let generate_docs =
     | Module({attr_name, attr_desc}) =>
       Buffer.add_string(buf, Markdown.frontmatter([("title", attr_name)]));
       Buffer.add_string(buf, Markdown.paragraph(attr_desc));
-      if (desc != "") {
-        Buffer.add_string(buf, Markdown.paragraph(desc));
+      switch (desc) {
+      // Guard isn't be needed because we turn an empty string into None during extraction
+      | Some(desc) => Buffer.add_string(buf, Markdown.paragraph(desc))
+      | None => ()
       };
     | _ => failwith("Unreachable: Non-`module` attribute can't exist here.")
     };

compiler/src/diagnostics/comments.re

@@ -188,7 +188,14 @@ module Attribute = {
         comment,
       );
 
-    (String.trim(out), List.rev(attrs^));
+    let desc = String.trim(out);
+    let desc_opt =
+      if (desc != "") {
+        Some(desc);
+      } else {
+        None;
+      };
+    (desc_opt, List.rev(attrs^));
   };
 
   let is_param = (attr: t) => {
@@ -270,37 +277,38 @@ module Attribute = {
     );
 };
 
+type description = option(string);
 type attributes = list(Attribute.t);
 
 module IntMap = Map.Make(Int);
 
 type comments = {
-  mutable by_start_lnum: IntMap.t((Typedtree.comment, string, attributes)),
-  mutable by_end_lnum: IntMap.t((Typedtree.comment, string, attributes)),
+  mutable by_start_lnum:
+    IntMap.t((Typedtree.comment, description, attributes)),
+  mutable by_end_lnum:
+    IntMap.t((Typedtree.comment, description, attributes)),
 };
 
 let comments = {by_start_lnum: IntMap.empty, by_end_lnum: IntMap.empty};
 
 let setup_comments = (raw_comments: list(Typedtree.comment)) => {
   List.iter(
     (comment: Typedtree.comment) => {
-      switch (comment) {
-      | Line({cmt_loc, cmt_content})
-      | Shebang({cmt_loc, cmt_content})
-      | Block({cmt_loc, cmt_content})
-      | Doc({cmt_loc, cmt_content}) =>
-        let (description, attributes) = Attribute.extract(cmt_content);
-        let data = (comment, description, attributes);
-
-        comments.by_start_lnum =
-          IntMap.add(
-            cmt_loc.loc_start.pos_lnum,
-            data,
-            comments.by_start_lnum,
-          );
-        comments.by_end_lnum =
-          IntMap.add(cmt_loc.loc_end.pos_lnum, data, comments.by_end_lnum);
-      }
+      let (start_lnum, end_lnum, data) =
+        switch (comment) {
+        | Line({cmt_loc, _})
+        | Shebang({cmt_loc, _})
+        | Block({cmt_loc, _}) =>
+          let data = (comment, None, []);
+          (cmt_loc.loc_start.pos_lnum, cmt_loc.loc_end.pos_lnum, data);
+        | Doc({cmt_loc, cmt_content}) =>
+          let (description, attributes) = Attribute.extract(cmt_content);
+          let data = (comment, description, attributes);
+          (cmt_loc.loc_start.pos_lnum, cmt_loc.loc_end.pos_lnum, data);
+        };
+      comments.by_start_lnum =
+        IntMap.add(start_lnum, data, comments.by_start_lnum);
+      comments.by_end_lnum = IntMap.add(end_lnum, data, comments.by_end_lnum);
     },
     raw_comments,
   );