fix(graindoc): Add all function parameters to the table, even if missing documentation

compiler/graindoc/docblock.re

@@ -376,6 +376,72 @@ let for_value_description =
 
   let (args, return_type) = types_for_function(~ident, vd);
 
+  // extract the documented parameters and put into a tuple for easy lookup
+  let param_attributes: list((string, Comment_attributes.t)) =
+    List.filter_map(
+      attr =>
+        switch (attr) {
+        | Comment_attributes.Param({attr_id}) =>
+          switch (attr_id) {
+          | PositionalParam(idx) => Some((string_of_int(idx), attr))
+          | LabeledParam(name) => Some((name, attr))
+          }
+        | _ => None
+        },
+      attributes,
+    );
+
+  let match_label_to_arg = arg => {
+    List.find_opt(((name, _)) => name == arg, param_attributes);
+  };
+
+  let documented_args =
+    switch (param_attributes) {
+    | [] => [] // no documented params so don't add to the table
+    | _ =>
+      switch (args) {
+      | None => []
+      | Some(function_args) =>
+        List.mapi(
+          (index, (lab, exp)) => {
+            let param_id =
+              switch (lab) {
+              | Typedtree.Labeled(l)
+              | Default(l) => l.txt
+              | _ => string_of_int(index)
+              };
+
+            // First try to match by name, then by position
+            let matched =
+              switch (match_label_to_arg(param_id)) {
+              | Some(_) as result => result
+              | None => match_label_to_arg(string_of_int(index))
+              };
+
+            // Extract documentation from the matched attribute
+            let documentation =
+              switch (matched) {
+              | Some((_, Comment_attributes.Param({attr_desc}))) => attr_desc
+              | _ => ""
+              };
+
+            // Get parameter type
+            let param_type =
+              switch (lookup_arg_by_label(param_id, args)) {
+              | Some((Labeled(_), typ)) => Printtyp.string_of_type_sch(typ)
+              | Some((Default(_), {desc: TTyConstr(_, [typ], _)})) =>
+                Printtyp.string_of_type_sch(typ)
+              | Some((_, typ)) => Printtyp.string_of_type_sch(typ)
+              | None => ""
+              };
+
+            {param_id, param_type, param_msg: documentation};
+          },
+          function_args,
+        )
+      }
+    };
+
   let (deprecations, since, history, params, returns, throws, examples) =
     List.fold_left(
       (
@@ -414,41 +480,9 @@ let for_value_description =
             throws,
             examples,
           )
-        | Param({attr_id: param_id, attr_desc: param_msg}) =>
-          let (param_id, param_type) =
-            switch (param_id) {
-            | PositionalParam(idx) =>
-              switch (lookup_type_expr(~idx, args)) {
-              | Some((_, typ)) => (
-                  string_of_int(idx),
-                  Printtyp.string_of_type_sch(typ),
-                )
-              | None => raise(MissingUnlabeledParamType({idx: idx}))
-              }
-            | LabeledParam(name) =>
-              switch (lookup_arg_by_label(name, args)) {
-              | Some((Labeled(_), typ)) => (
-                  name,
-                  Printtyp.string_of_type_sch(typ),
-                )
-              // Default parameters have the type Option<a>; extract the type from the Option
-              | Some((Default(_), {desc: TTyConstr(_, [typ], _)})) => (
-                  "?" ++ name,
-                  Printtyp.string_of_type_sch(typ),
-                )
-              | _ => raise(MissingLabeledParamType({name: name}))
-              }
-            };
-
-          (
-            deprecations,
-            since,
-            history,
-            [{param_id, param_type, param_msg}, ...params],
-            returns,
-            throws,
-            examples,
-          );
+        | Param(_) =>
+          // do nothing as we precomputed them
+          (deprecations, since, history, params, returns, throws, examples)
         | Returns({attr_desc: returns_msg}) =>
           switch (returns) {
           | Some(_) =>
@@ -502,7 +536,7 @@ let for_value_description =
     deprecations: List.rev(deprecations),
     since,
     history: List.rev(history),
-    params: List.rev(params),
+    params: documented_args,
     returns,
     throws: List.rev(throws),
     examples: List.rev(examples),

compiler/test/graindoc/params.expected.md

@@ -0,0 +1,63 @@
+---
+title: Params
+---
+
+## Values
+
+Functions and constants included in the Params module.
+
+### Params.**test1**
+
+```grain
+test1: (a: Number, b: Number) => Number
+```
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`a`|`Number`|This is the first|
+|`b`|`Number`|This is the second|
+
+### Params.**test2**
+
+```grain
+test2: (a: Number, b: Number) => Number
+```
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`a`|`Number`||
+|`b`|`Number`|This is the third|
+
+### Params.**test3**
+
+```grain
+test3: (a: Number, b: Number, c: Number) => Number
+```
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`a`|`Number`|This is the first|
+|`b`|`Number`|This is the third|
+|`c`|`Number`||
+
+### Params.**test4**
+
+```grain
+test4: (a: Number, b: Number, c: Number, a) => Number
+```
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`a`|`Number`|This is the a|
+|`b`|`Number`|This is the b|
+|`c`|`Number`||
+|`3`|``|This is the 3|
+

compiler/test/graindoc/params.input.gr

@@ -0,0 +1,25 @@
+module Params
+
+/**
+ * @param a: This is the first
+ * @param b: This is the second
+ */
+provide let test1 = (a, b) => a + b
+
+/**
+ * @param b: This is the third
+ */
+provide let test2 = (a, b) => a + b
+
+/**
+ * @param b: This is the third
+ * @param a: This is the first
+ */
+provide let test3 = (a, b, c) => a + b + c
+
+/**
+ * @param a: This is the a
+ * @param b: This is the b
+ * @param 3: This is the 3
+ */
+provide let test4 = (a, b, c, _) => a + b + c

compiler/test/suites/graindoc.re

@@ -37,4 +37,5 @@ describe("graindoc", ({test, testSkip}) => {
     "Attribute @returns is only allowed to appear once.",
     [|"--current-version=v0.2.0"|],
   );
+  assertGrianDocOutput("params", "params", [|"--current-version=v0.2.0"|]);
 });