Clarify documentation
Signed-off-by: Werner Lewis <werner.lewis@arm.com>
diff --git a/tests/scripts/generate_bignum_tests.py b/tests/scripts/generate_bignum_tests.py
index 2443f65..4486d49 100755
--- a/tests/scripts/generate_bignum_tests.py
+++ b/tests/scripts/generate_bignum_tests.py
@@ -6,25 +6,33 @@
Class structure:
-Target classes are directly derived from test_generation.BaseTarget,
-representing a target file. These indicate where test cases will be written
-to in classes derived from the Target. Multiple Target classes must not
-represent the same target_basename.
+Child classes of test_generation.BaseTarget (file Targets) represent a target
+file. These indicate where test cases will be written to, for all subclasses of
+this Target. Multiple Target classes should not reuse a `target_basename`.
-Each subclass derived from a Target can either be:
+Each subclass derived from a file Target can either be:
- A concrete class, representing a test function, which generates test cases.
- An abstract class containing shared methods and attributes, not associated
- with a test function. An example is BignumOperation, which provides common
- features used in binary bignum operations.
+ with a test function. An example is BignumOperation, which provides
+ common features used for bignum binary operations.
+
+Both concrete and abstract subclasses can be derived from, to implement
+additional test cases (see BignumCmp and BignumCmpAbs for examples of deriving
+from abstract and concrete classes).
-Adding test generation for a function:
+Adding test case generation for a function:
A subclass representing the test function should be added, deriving from a
-Target class or a descendant. This subclass must set/implement the following:
+file Target. This test class must set/implement the following:
- test_function: the function name from the associated .function file.
- - arguments(): generation of the arguments required for the test_function.
- - generate_function_test(): generation of the test cases for the function.
+ - test_name: a descriptive name or brief summary to refer to the test
+ function.
+ - arguments(): a method to generate the list of arguments required for the
+ test_function.
+ - generate_function_test(): a method to generate TestCases for the function.
+ This should create instances of the class with required input data, and
+ call `.create_test_case()` to yield the TestCase.
Additional details and other attributes/methods are given in the documentation
of BaseTarget in test_generation.py.
@@ -71,7 +79,7 @@
class BignumOperation(BignumTarget, metaclass=ABCMeta):
- """Common features for test cases covering binary bignum operations.
+ """Common features for bignum binary operations.
This adds functionality common in binary operation tests. This includes
generation of case descriptions, using descriptions of values and symbols
@@ -130,7 +138,7 @@
"""Generate a description of the argument val.
This produces a simple description of the value, which are used in test
- case naming, to add context to the test cases.
+ case naming, to add context.
"""
if val == "":
return "0 (null)"
@@ -150,7 +158,7 @@
@classmethod
def get_value_pairs(cls) -> Iterator[Tuple[str, str]]:
- """Generator for pairs of inputs.
+ """Generator to yield pairs of inputs.
Combinations are first generated from all input values, and then
specific cases provided.
@@ -169,7 +177,7 @@
class BignumCmp(BignumOperation):
- """Target for bignum comparison test cases."""
+ """Test cases for bignum value comparison."""
count = 0
test_function = "mbedtls_mpi_cmp_mpi"
test_name = "MPI compare"
@@ -190,7 +198,7 @@
class BignumCmpAbs(BignumCmp):
- """Target for bignum comparison, absolute variant."""
+ """Test cases for absolute bignum value comparison."""
count = 0
test_function = "mbedtls_mpi_cmp_abs"
test_name = "MPI compare (abs)"
@@ -200,7 +208,7 @@
class BignumAdd(BignumOperation):
- """Target for bignum addition test cases."""
+ """Test cases for bignum value addition."""
count = 0
test_function = "mbedtls_mpi_add_mpi"
test_name = "MPI add"
@@ -223,7 +231,7 @@
class BignumTestGenerator(test_generation.TestGenerator):
- """Test generator subclass including bignum targets."""
+ """Test generator subclass setting bignum targets."""
TARGETS = {
subclass.target_basename: subclass.generate_tests for subclass in
test_generation.BaseTarget.__subclasses__()