Add documentation about test-data generation.

gnark-prover/merkle-tree/tree_test.go

@@ -93,7 +93,7 @@ func TestCombined(t *testing.T) {
 		InclusionParameters:    tree1,
 		NonInclusionParameters: tree2,
 	}
-	// print the combined parameters
+
 	var json, err2 = combinedParams.MarshalJSON()
 	if err2 != nil {
 		t.Errorf("Error marshalling JSON: %v", err)
@@ -142,6 +142,47 @@ type InclusionTreeValidPair struct {
 	Valid bool
 }
 
+// Function
+//
+// `MakeTestIncludedTrees`
+//
+// ```go
+// func MakeTestIncludedTrees(depth int, numberOfUtxos int) []InclusionTreeValidPair
+// ```
+//
+// # Description
+//
+// The `MakeTestIncludedTrees` function creates an array of InclusionTreeValidPair instances for testing.
+// The variation between valid and invalid trees helps simulate real-world scenarios and assists in better
+// testing for robustness and error-handling.
+//
+// Parameters:
+//
+//   - `depth (int)`: Defines the depth of each included tree.
+//   - `numberOfUtxos (int)`: Number of unspent transaction outputs (UTXOs) to include in each tree.
+//
+// Returns:
+// - `[]InclusionTreeValidPair`: An array of `InclusionTreeValidPair` instances, each containing
+// an `InclusionParameters` instance and a boolean value indicating whether the tree is valid.
+//
+// Pairs Explanation:
+//
+// - `validPair`: A valid tree constructed with input parameters. The Valid field is set to `true`.
+// - `invalidRootPair`: A valid tree but the root value is invalidated by setting it to an integer 999. The Valid field is set to `false`.
+// - `invalidLeafPair`: A valid tree where a leaf value is invalidated by setting it to an integer 999. The Valid field is set to `false`.
+// - `invalidInPathIndicesPair`: A valid tree but the InPathIndices value is invalidated by setting it to an integer 999. The Valid field is set to `false`.
+// - `invalidInPathElementsPair`: A valid tree where the InPathElements is invalidated by setting a value to an integer 999. The Valid field is set to `false`.
+//
+// Example usage:
+//
+// ```go
+// trees := MakeTestIncludedTrees(4, 2)
+//
+//	for _, tree := range trees {
+//	    // perform operations on tree
+//	}
+//
+// ```
 func MakeTestIncludedTrees(depth int, numberOfUtxos int) []InclusionTreeValidPair {
 	var trees []InclusionTreeValidPair
 
@@ -177,6 +218,51 @@ type NonInclusionTreeValidPair struct {
 	Valid bool
 }
 
+// Function
+//
+// `MakeTestNonInclusionTrees`
+//
+// ```go
+// func MakeTestNonInclusionTrees(depth int, numberOfUtxos int) []NonInclusionTreeValidPair
+// ```
+//
+// # Description
+//
+// The `MakeTestNonInclusionTrees` function creates an array of `NonInclusionTreeValidPair` instances for testing. These instances include various valid and invalid cases to simulate diverse scenarios and strengthen code robustness and error handling. This function helps in creating a testing environment that closely mimics a variety of real-world scenarios.
+//
+// # Parameters
+//
+// - `depth (int)`: Defines the depth of each included tree.
+// - `numberOfUtxos (int)`: Number of unspent transaction outputs (UTXOs) to include in each tree.
+//
+// # Returns
+//
+// - `[]NonInclusionTreeValidPair`: An array of `NonInclusionTreeValidPair` instances, each containing an `InclusionParameters` instance and a boolean value indicating whether the tree is valid.
+//
+// # Pairs Explanation
+//
+// - `validPair`: A tree constructed with input parameters. The `Valid` field is set to `true`.
+//
+// - `invalidRootPair`: A valid tree but the root value is invalidated by setting it to an integer 999. The `Valid` field is set to `false`.
+//
+// - `invalidLowValuePair`: An invalid tree with a low value. The `Valid` field is set to `false`.
+//
+// - `invalidHighValuePair`: An invalid tree with a high value. The `Valid` field is set to `false`.
+//
+// - `invalidInPathIndicesPair`: A valid tree but the `InPathIndices` value is invalidated by setting it to an integer 999. The `Valid` field is set to `false`.
+//
+// - `invalidInPathElementsPair`: A valid tree where the `InPathElements` are invalidated by an integer 999. The `Valid` field is set to `false`.
+//
+// # Example Usage
+//
+// ```go
+// trees := MakeTestNonInclusionTrees(4, 2)
+//
+//	for _, tree := range trees {
+//	    // perform operations on tree
+//	}
+//
+// ```
 func MakeTestNonInclusionTrees(depth int, numberOfUtxos int) []NonInclusionTreeValidPair {
 	var trees []NonInclusionTreeValidPair