feat(graindoc): Add test harness (#1767)

* feat: Create `graindoc` test harness

* chore: Add Some Initial tests

* chore: Apply suggestions from code review

Author: spotandjake

compiler/test/TestFramework.re

@@ -32,6 +32,8 @@ let test_snapshots_dir = Fp.At.(test_dir / "__snapshots__");
 let test_formatter_in_dir = Fp.At.(test_dir / "formatter_inputs");
 let test_formatter_out_dir = Fp.At.(test_dir / "formatter_outputs");
 
+let test_gaindoc_dir = Fp.At.(test_dir / "graindoc");
+
 let clean_grain_output = stdlib_dir =>
   Array.iter(
     file => {

compiler/test/graindoc/descriptions.expected.md

@@ -0,0 +1,56 @@
+---
+title: DescriptionGrainDoc
+---
+
+## Types
+
+Type declarations included in the DescriptionGrainDoc module.
+
+### DescriptionGrainDoc.**DocAlias**
+
+```grain
+type DocAlias = Bool
+```
+
+Alias Doc
+
+### DescriptionGrainDoc.**DocRecord**
+
+```grain
+record DocRecord {
+  docField: Bool,
+}
+```
+
+Record Doc
+
+### DescriptionGrainDoc.**DocEnum**
+
+```grain
+enum DocEnum {
+  DocCase,
+}
+```
+
+Enum Doc
+
+## Values
+
+Functions and constants included in the DescriptionGrainDoc module.
+
+### DescriptionGrainDoc.**docValue**
+
+```grain
+docValue : Number
+```
+
+Value Doc
+
+### DescriptionGrainDoc.**docFunction**
+
+```grain
+docFunction : (x: Number) -> Number
+```
+
+Function Doc
+

compiler/test/graindoc/descriptions.input.gr

@@ -0,0 +1,52 @@
+module DescriptionGrainDoc
+
+// No Documentation
+/**
+ * No Alias Doc
+ */
+type NoDocAlias = Bool
+/**
+ * No Record Doc
+ */
+record NoDocRecord {
+  noDocField: Bool
+}
+/**
+ * No Enum Doc
+ */
+enum NoDocEnum {
+  NoDocCase
+}
+/**
+ * No Value Doc
+ */
+let noDocValue = 1
+/**
+ * No Function Doc
+ */
+let noDocFunction = (x: Number) => x + 1
+// Documentation
+/**
+ * Alias Doc
+ */
+provide type DocAlias = Bool
+/**
+ * Record Doc
+ */
+provide record DocRecord {
+  docField: Bool
+}
+/**
+ * Enum Doc
+ */
+provide enum DocEnum {
+  DocCase
+}
+/**
+ * Value Doc
+ */
+provide let docValue = 1
+/**
+ * Function Doc
+ */
+provide let docFunction = (x: Number) => x + 1

compiler/test/graindoc/example.expected.md

@@ -0,0 +1,121 @@
+---
+title: ExampleDoc
+---
+
+## Values
+
+Functions and constants included in the ExampleDoc module.
+
+### ExampleDoc.**singleLineExample**
+
+```grain
+singleLineExample : (index: a, array: b) -> Number
+```
+
+SingleLineExample
+
+Examples:
+
+```grain
+singleLineExample(1, [1, 2, 3])
+```
+
+### ExampleDoc.**multiLineExample**
+
+```grain
+multiLineExample : (index: a, array: b) -> Number
+```
+
+MultiLineExample
+
+Examples:
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+print(x) // 1
+```
+
+### ExampleDoc.**multipleSingleLineExamples**
+
+```grain
+multipleSingleLineExamples : (index: a, array: b) -> Number
+```
+
+SingleLineExample
+
+Examples:
+
+```grain
+singleLineExample(1, [1, 2, 3]) == 1
+```
+
+```grain
+assert singleLineExample(1, [1, 2, 3]) == 1
+```
+
+```grain
+print(singleLineExample(1, [1, 2, 3]))
+```
+
+### ExampleDoc.**multipleMultiLineExample**
+
+```grain
+multipleMultiLineExample : (index: a, array: b) -> Number
+```
+
+MultiLineExample
+
+Examples:
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+print(x) // 1
+```
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+assert x == 1
+```
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+x == 1
+```
+
+### ExampleDoc.**mixedLineExample**
+
+```grain
+mixedLineExample : (index: a, array: b) -> Number
+```
+
+MultiLineExample
+
+Examples:
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+print(x) // 1
+```
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+assert x == 1
+```
+
+```grain
+let x = multiLineExample(1, [1, 2, 3])
+x == 1
+```
+
+```grain
+singleLineExample(1, [1, 2, 3]) == 1
+```
+
+```grain
+assert singleLineExample(1, [1, 2, 3]) == 1
+```
+
+```grain
+print(singleLineExample(1, [1, 2, 3]))
+```
+

compiler/test/graindoc/example.input.gr

@@ -0,0 +1,66 @@
+module ExampleDoc
+
+/**
+ * SingleLineExample
+ *
+ * @example singleLineExample(1, [1, 2, 3])
+ */
+provide let singleLineExample = (index, array) => 1
+
+/**
+ * MultiLineExample
+ *
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * print(x) // 1
+ */
+provide let multiLineExample = (index, array) => 1
+
+
+/**
+ * SingleLineExample
+ *
+ * @example singleLineExample(1, [1, 2, 3]) == 1
+ * @example assert singleLineExample(1, [1, 2, 3]) == 1
+ *
+ * @example print(singleLineExample(1, [1, 2, 3]))
+ */
+provide let multipleSingleLineExamples = (index, array) => 1
+
+/**
+ * MultiLineExample
+ *
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * print(x) // 1
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * assert x == 1
+ *
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * x == 1
+ */
+provide let multipleMultiLineExample = (index, array) => 1
+
+
+/**
+ * MultiLineExample
+ *
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * print(x) // 1
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * assert x == 1
+ *
+ * @example
+ * let x = multiLineExample(1, [1, 2, 3])
+ * x == 1
+ *
+ * @example singleLineExample(1, [1, 2, 3]) == 1
+ * @example assert singleLineExample(1, [1, 2, 3]) == 1
+ *
+ * @example print(singleLineExample(1, [1, 2, 3]))
+ */
+provide let mixedLineExample = (index, array) => 1

compiler/test/graindoc/functionDoc.expected.md

@@ -0,0 +1,44 @@
+---
+title: FunctionGrainDoc
+---
+
+## Values
+
+Functions and constants included in the FunctionGrainDoc module.
+
+### FunctionGrainDoc.**get**
+
+<details>
+<summary>Added in <code>0.1.0</code></summary>
+<table>
+<thead>
+<tr><th>version</th><th>changes</th></tr>
+</thead>
+<tbody>
+<tr><td><code>0.2.0</code></td><td>Argument order changed to data-last</td></tr>
+</tbody>
+</table>
+</details>
+
+```grain
+get : (index: Number, array: Array<a>) -> a
+```
+
+An alias for normal syntactic array access, i.e. `array[n]`.
+
+Retrieves the element from the array at the specified index.
+A negative index is treated as an offset from the end of the array.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`index`|`Number`|The index to access|
+|`array`|`Array<a>`|The array to access|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`a`|The element from the array|
+

compiler/test/graindoc/functionDoc.input.gr

@@ -0,0 +1,17 @@
+module FunctionGrainDoc
+/**
+ * An alias for normal syntactic array access, i.e. `array[n]`.
+ *
+ * Retrieves the element from the array at the specified index.
+ * A negative index is treated as an offset from the end of the array.
+ *
+ * @param index: The index to access
+ * @param array: The array to access
+ * @returns The element from the array
+ *
+ * @since v0.1.0
+ * @history v0.2.0: Argument order changed to data-last
+ */
+provide let get = (index, array) => {
+  array[index]
+}