chore(graindoc)!: Remove section attribute (#1681)

* chore(graindoc)!: Remove section attribute

* chore(stdlib): Remove section docblocks

* chore(stdlib): Regenerate markdown docs

Author: phated

compiler/graindoc/docblock.re

@@ -32,7 +32,7 @@ let () =
     }
   });
 
-let enumerate_exports = stmts => {
+let enumerate_provides = program => {
   let id_tbl = ref(Ident.empty);
 
   let rec pattern_ids = ({pat_desc, pat_loc}: Typedtree.pattern) => {
@@ -48,7 +48,7 @@ let enumerate_exports = stmts => {
     };
   };
 
-  module ExportIterator =
+  module ProvideIterator =
     TypedtreeIter.MakeIterator({
       include TypedtreeIter.DefaultIteratorArgument;
 
@@ -89,13 +89,14 @@ let enumerate_exports = stmts => {
       };
     });
 
-  List.iter(ExportIterator.iter_toplevel_stmt, stmts);
+  ProvideIterator.iter_typed_program(program);
 
   id_tbl^;
 };
 
-let location_for_ident = (~exports, ident) => {
-  snd(Ident.find_name(Ident.name(ident), exports));
+let location_for_ident =
+    (~provides: Ident.tbl(Grain_parsing.Location.t), ident) => {
+  snd(Ident.find_name(Ident.name(ident), provides));
 };
 
 let title_for_api = (~module_name, ident: Ident.t) => {
@@ -145,11 +146,12 @@ let lookup_type_expr = (~idx, type_exprs) => {
 let for_value_description =
     (
       ~comments,
-      ~loc: Grain_parsing.Location.t,
+      ~provides,
       ~module_name,
       ~ident: Ident.t,
       vd: Types.value_description,
     ) => {
+  let loc = location_for_ident(~provides, ident);
   let name = title_for_api(~module_name, ident);
   let type_sig = Printtyp.string_of_value_description(~ident, vd);
   let comment =
@@ -185,11 +187,12 @@ let for_value_description =
 let for_type_declaration =
     (
       ~comments,
-      ~loc: Grain_parsing.Location.t,
+      ~provides,
       ~module_name,
       ~ident: Ident.t,
       td: Types.type_declaration,
     ) => {
+  let loc = location_for_ident(~provides, ident);
   let name = title_for_api(~module_name, ident);
   let type_sig = Printtyp.string_of_type_declaration(~ident, td);
   let comment =
@@ -204,45 +207,6 @@ let for_type_declaration =
   {module_name, name, type_sig, description, attributes};
 };
 
-let for_signature_item =
-    (
-      ~comments,
-      ~exports: Ident.tbl(Grain_parsing.Location.t),
-      ~module_name,
-      sig_item: Types.signature_item,
-    ) => {
-  switch (sig_item) {
-  | TSigValue(ident, vd) =>
-    let loc = location_for_ident(~exports, ident);
-    let docblock =
-      for_value_description(~comments, ~module_name, ~ident, ~loc, vd);
-    Some(docblock);
-  | TSigType(ident, td, _rec) =>
-    let loc = location_for_ident(~exports, ident);
-    let docblock =
-      for_type_declaration(~comments, ~module_name, ~ident, ~loc, td);
-    Some(docblock);
-  | _ => None
-  };
-};
-
-let signature_item_in_range =
-    (
-      ~exports: Ident.tbl(Grain_parsing.Location.t),
-      sig_item: Types.signature_item,
-      range: Grain_utils.Range.t,
-    ) => {
-  switch (sig_item) {
-  | TSigValue(ident, vd) =>
-    let loc = location_for_ident(~exports, ident);
-    Grain_utils.Range.inRange(loc.loc_start.pos_lnum, range);
-  | TSigType(ident, td, _rec) =>
-    let loc = location_for_ident(~exports, ident);
-    Grain_utils.Range.inRange(loc.loc_start.pos_lnum, range);
-  | _ => false
-  };
-};
-
 // Used for joining multiple `@throws` annotations with the exact same type
 module StringMap = Map.Make(String);
 

compiler/graindoc/graindoc.re

@@ -82,7 +82,7 @@ let generate_docs =
     (~current_version, ~output=?, program: Typedtree.typed_program) => {
   let comments = Comments.to_ordered(program.comments);
 
-  let exports = Docblock.enumerate_exports(program.statements);
+  let provides = Docblock.enumerate_provides(program);
 
   let signature_items = program.signature.cmi_sign;
 
@@ -182,61 +182,99 @@ let generate_docs =
   | None => ()
   };
 
-  let add_docblock = sig_item => {
-    let docblock =
-      Docblock.for_signature_item(
-        ~comments,
-        ~exports,
-        ~module_name,
-        sig_item,
-      );
-    switch (docblock) {
-    | Some(docblock) =>
-      Buffer.add_buffer(
-        buf,
-        Docblock.to_markdown(~current_version, docblock),
-      )
-    | None => ()
-    };
-  };
+  let sig_types =
+    List.filter(
+      (sig_item: Types.signature_item) => {
+        switch (sig_item) {
+        | TSigTypeExt(_)
+        | TSigModule(_)
+        | TSigModType(_)
+        | TSigValue(_) => false
+        | TSigType(_) => true
+        }
+      },
+      signature_items,
+    );
+
+  switch (sig_types) {
+  | [] => ()
+  | _ =>
+    Buffer.add_string(buf, Markdown.heading(~level=2, "Types"));
+    Buffer.add_string(
+      buf,
+      Markdown.paragraph(
+        "Type declarations included in the " ++ module_name ++ " module.",
+      ),
+    );
 
-  let section_comments = Comments.Doc.find_sections(comments);
-  if (List.length(section_comments) == 0) {
-    List.iter(add_docblock, signature_items);
-  } else {
-    List.iteri(
-      (idx, (comment, desc, attrs)) => {
-        let next_section_start_line =
-          Option.fold(
-            ~none=max_int,
-            ~some=((comment, _, _)) => Comments.start_line(comment),
-            List.nth_opt(section_comments, idx + 1),
+    List.iter(
+      (sig_type: Types.signature_item) => {
+        switch (sig_type) {
+        | TSigType(ident, td, _rec) =>
+          let docblock =
+            Docblock.for_type_declaration(
+              ~comments,
+              ~provides,
+              ~module_name,
+              ~ident,
+              td,
+            );
+          Buffer.add_buffer(
+            buf,
+            Docblock.to_markdown(~current_version, docblock),
           );
-        let range =
-          Grain_utils.Range.Exclusive(
-            Comments.end_line(comment),
-            next_section_start_line,
+        | _ => failwith("Unreachable: TSigType-only list")
+        }
+      },
+      sig_types,
+    );
+  };
+
+  let sig_values =
+    List.filter(
+      (sig_item: Types.signature_item) => {
+        switch (sig_item) {
+        | TSigType(_)
+        | TSigTypeExt(_)
+        | TSigModule(_)
+        | TSigModType(_) => false
+        | TSigValue(_) => true
+        }
+      },
+      signature_items,
+    );
+
+  switch (sig_values) {
+  | [] => ()
+  | _ =>
+    Buffer.add_string(buf, Markdown.heading(~level=2, "Values"));
+    Buffer.add_string(
+      buf,
+      Markdown.paragraph(
+        "Functions and constants included in the " ++ module_name ++ " module.",
+      ),
+    );
+
+    List.iter(
+      (sig_value: Types.signature_item) => {
+        switch (sig_value) {
+        | TSigValue(ident, vd) =>
+          let docblock =
+            Docblock.for_value_description(
+              ~comments,
+              ~provides,
+              ~module_name,
+              ~ident,
+              vd,
+            );
+          Buffer.add_buffer(
+            buf,
+            Docblock.to_markdown(~current_version, docblock),
           );
-        List.iter(
-          (attr: Comment_attributes.t) => {
-            switch (attr) {
-            | Section({attr_name, attr_desc}) =>
-              Buffer.add_string(buf, Markdown.heading(~level=2, attr_name));
-              Buffer.add_string(buf, Markdown.paragraph(attr_desc));
-            | _ => ()
-            }
-          },
-          attrs,
-        );
-        List.iter(
-          sig_item =>
-            if (Docblock.signature_item_in_range(~exports, sig_item, range)) {
-              add_docblock(sig_item);
-            },
-          signature_items,
-        );
+        | _ => failwith("Unreachable: TSigValue-only list")
+        }
       },
-      section_comments,
+      sig_values,
     );
   };
 

compiler/src/diagnostics/comment_attributes.re

@@ -17,12 +17,7 @@ type t =
       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({

compiler/src/diagnostics/comments.re

@@ -90,13 +90,6 @@ module Attribute = {
     };
   };
 
-  let is_section = attr => {
-    switch (attr) {
-    | Section(_) => true
-    | _ => false
-    };
-  };
-
   let is_deprecated = attr => {
     switch (attr) {
     | Deprecated(_) => true
@@ -255,16 +248,6 @@ module Doc = {
     };
     ending_on_lnum_help(lnum, true);
   };
-
-  let find_sections = (module C: OrderedComments) => {
-    let section_comments = ref([]);
-    C.iter((_, (_comment, _desc, attrs) as comment) =>
-      if (List.exists(Attribute.is_section, attrs)) {
-        section_comments := [comment, ...section_comments^];
-      }
-    );
-    List.rev(section_comments^);
-  };
 };
 
 let print_comment = (comment: Parsetree.comment) => {

compiler/src/diagnostics/graindoc_lexer.re

@@ -60,7 +60,6 @@ and lexer_mode =
   | Start
   | Default
   | Param
-  | Section
   | Since
   | History
   | Throws
@@ -71,7 +70,6 @@ let rec token = (state, lexbuf) => {
   | Start => start(state, lexbuf)
   | Default => default(state, lexbuf)
   | Param => param(state, lexbuf)
-  | Section => section(state, lexbuf)
   | Since => since(state, lexbuf)
   | History => history(state, lexbuf)
   | Throws => throws(state, lexbuf)
@@ -102,9 +100,6 @@ and default = (state, lexbuf) => {
   | "@example" =>
     state.lexer_mode = FreeTextAttribute;
     EXAMPLE;
-  | "@section" =>
-    state.lexer_mode = Section;
-    SECTION;
   | "@deprecated" =>
     state.lexer_mode = FreeTextAttribute;
     DEPRECATED;

compiler/src/diagnostics/graindoc_parser.messages

@@ -125,15 +125,6 @@ graindoc: THROWS CONSTRUCTOR THROWS
 ## The known suffix of the stack is as follows:
 ## THROWS CONSTRUCTOR
 ##
-graindoc: SECTION TEXT THROWS
-##
-## Ends in an error in state: 24.
-##
-## attribute -> SECTION TEXT . COLON attribute_text [ THROWS SINCE SECTION RETURNS PARAM HISTORY EXAMPLE EOL EOF DEPRECATED ]
-##
-## The known suffix of the stack is as follows:
-## SECTION TEXT
-##
 graindoc: PARAM IDENT THROWS
 ##
 ## Ends in an error in state: 30.
@@ -175,15 +166,6 @@ graindoc: DEPRECATED EOL THROWS
 ## The known suffix of the stack is as follows:
 ## eols
 ##
-graindoc: SECTION TEXT COLON THROWS
-##
-## Ends in an error in state: 25.
-##
-## attribute -> SECTION TEXT COLON . attribute_text [ THROWS SINCE SECTION RETURNS PARAM HISTORY EXAMPLE EOL EOF DEPRECATED ]
-##
-## The known suffix of the stack is as follows:
-## SECTION TEXT COLON
-##
 graindoc: RETURNS THROWS
 ##
 ## Ends in an error in state: 27.
@@ -253,18 +235,6 @@ graindoc: HISTORY THROWS
 
 Expected a version number in Semantic Versioning format, e.g. `v1.2.3`.
 
-graindoc: SECTION THROWS
-##
-## Ends in an error in state: 23.
-##
-## attribute -> SECTION . TEXT COLON attribute_text [ THROWS SINCE SECTION RETURNS PARAM HISTORY EXAMPLE EOL EOF DEPRECATED ]
-##
-## The known suffix of the stack is as follows:
-## SECTION
-##
-
-Expected a section title.
-
 graindoc: PARAM THROWS
 ##
 ## Ends in an error in state: 29.

compiler/src/diagnostics/graindoc_parser.mly

@@ -30,7 +30,6 @@ attribute:
   | PARAM IDENT COLON attribute_text { Param({ attr_name=$2; attr_type=None; attr_desc=$4 }) }
   | RETURNS attribute_text { Returns({ attr_desc=$2; attr_type=None }) }
   | EXAMPLE attribute_text { Example({attr_desc=$2}) }
-  | SECTION TEXT COLON attribute_text { Section({ attr_name=$2; attr_desc=$4; }) }
   | DEPRECATED attribute_text { Deprecated({attr_desc=$2}) }
   | SINCE SEMVER { Since({attr_version=$2}) }
   | HISTORY SEMVER COLON attribute_text { History({ attr_version=$2; attr_desc=$4; }) }