feat(graindoc)!: Allow @since and @returns once per export (#1946)

Author: spotandjake

compiler/graindoc/docblock.re

@@ -80,6 +80,7 @@ exception
 exception MissingLabeledParamType({name: string});
 exception MissingUnlabeledParamType({idx: int});
 exception MissingReturnType;
+exception AttributeAppearsMultipleTimes({attr: string});
 exception
   InvalidAttribute({
     name: string,
@@ -115,6 +116,10 @@ let () =
     | MissingReturnType =>
       let msg = "Unable to find a return type. Please file an issue!";
       Some(msg);
+    | AttributeAppearsMultipleTimes({attr}) =>
+      let msg =
+        Printf.sprintf("Attribute @%s is only allowed to appear once.", attr);
+      Some(msg);
     | InvalidAttribute({name, attr}) =>
       let msg = Printf.sprintf("Invalid attribute @%s on %s", attr, name);
       Some(msg);
@@ -292,16 +297,18 @@ let for_value_description =
             examples,
           )
         | Since({attr_version}) =>
-          // TODO(#787): Should we fail if more than one `@since` attribute?
-          (
-            deprecations,
-            Some({since_version: attr_version}),
-            history,
-            params,
-            returns,
-            throws,
-            examples,
-          )
+          switch (since) {
+          | Some(_) => raise(AttributeAppearsMultipleTimes({attr: "since"}))
+          | None => (
+              deprecations,
+              Some({since_version: attr_version}),
+              history,
+              params,
+              returns,
+              throws,
+              examples,
+            )
+          }
         | History({attr_version: history_version, attr_desc: history_msg}) => (
             deprecations,
             since,
@@ -347,20 +354,25 @@ let for_value_description =
             examples,
           );
         | Returns({attr_desc: returns_msg}) =>
-          let returns_type =
-            switch (return_type) {
-            | Some(typ) => Printtyp.string_of_type_sch(typ)
-            | None => raise(MissingReturnType)
-            };
-          (
-            deprecations,
-            since,
-            history,
-            params,
-            Some({returns_msg, returns_type}),
-            throws,
-            examples,
-          );
+          switch (returns) {
+          | Some(_) =>
+            raise(AttributeAppearsMultipleTimes({attr: "returns"}))
+          | None =>
+            let returns_type =
+              switch (return_type) {
+              | Some(typ) => Printtyp.string_of_type_sch(typ)
+              | None => raise(MissingReturnType)
+              };
+            (
+              deprecations,
+              since,
+              history,
+              params,
+              Some({returns_msg, returns_type}),
+              throws,
+              examples,
+            );
+          }
         | Throws({attr_type: throw_type, attr_desc: throw_msg}) => (
             deprecations,
             since,
@@ -427,13 +439,15 @@ let for_type_declaration =
             examples,
           )
         | Since({attr_version}) =>
-          // TODO(#787): Should we fail if more than one `@since` attribute?
-          (
-            deprecations,
-            Some({since_version: attr_version}),
-            history,
-            examples,
-          )
+          switch (since) {
+          | Some(_) => raise(AttributeAppearsMultipleTimes({attr: "since"}))
+          | None => (
+              deprecations,
+              Some({since_version: attr_version}),
+              history,
+              examples,
+            )
+          }
         | History({attr_version: history_version, attr_desc: history_msg}) => (
             deprecations,
             since,
@@ -554,13 +568,15 @@ and for_signature_items =
             examples,
           )
         | Since({attr_version}) =>
-          // TODO(#787): Should we fail if more than one `@since` attribute?
-          (
-            deprecations,
-            Some({since_version: attr_version}),
-            history,
-            examples,
-          )
+          switch (since) {
+          | Some(_) => raise(AttributeAppearsMultipleTimes({attr: "since"}))
+          | None => (
+              deprecations,
+              Some({since_version: attr_version}),
+              history,
+              examples,
+            )
+          }
         | History({attr_version: history_version, attr_desc: history_msg}) => (
             deprecations,
             since,

compiler/test/graindoc/singleReturn.input.gr

@@ -0,0 +1,7 @@
+module SingleReturn
+
+/**
+ * @returns first return
+ * @returns second return
+ */
+provide let test = () => 1

compiler/test/graindoc/singleSince.input.gr

@@ -0,0 +1,7 @@
+module SingleSince
+
+/**
+ * @since v1.0.0
+ * @since v1.0.0
+ */
+provide let test = () => print("t")

compiler/test/runner.re

@@ -487,3 +487,14 @@ let makeGrainDocRunner = (test, name, filename, arguments) => {
     },
   );
 };
+
+let makeGrainDocErrorRunner = (test, name, filename, expected, arguments) => {
+  test(
+    name,
+    ({expect}) => {
+      let infile = gaindoc_in_file(filename);
+      let (result, _) = doc(infile, arguments);
+      expect.string(result).toMatch(expected);
+    },
+  );
+};

compiler/test/suites/graindoc.re

@@ -9,6 +9,7 @@ describe("graindoc", ({test, testSkip}) => {
     Sys.backend_type == Other("js_of_ocaml") ? testSkip : test;
 
   let assertGrianDocOutput = makeGrainDocRunner(test_or_skip);
+  let assertGrainDocError = makeGrainDocErrorRunner(test_or_skip);
   ();
   assertGrianDocOutput("noDoc", "noDoc", [||]);
   assertGrianDocOutput(
@@ -18,4 +19,16 @@ describe("graindoc", ({test, testSkip}) => {
   );
   assertGrianDocOutput("since", "since", [|"--current-version=v0.2.0"|]);
   assertGrianDocOutput("example", "example", [|"--current-version=v0.2.0"|]);
+  assertGrainDocError(
+    "singleSince",
+    "singleSince",
+    "Attribute @since is only allowed to appear once.",
+    [|"--current-version=v0.2.0"|],
+  );
+  assertGrainDocError(
+    "singleReturn",
+    "singleReturn",
+    "Attribute @returns is only allowed to appear once.",
+    [|"--current-version=v0.2.0"|],
+  );
 });