Clarify documentation

Signed-off-by: Werner Lewis <werner.lewis@arm.com>

tests/scripts/generate_bignum_tests.py

@@ -6,25 +6,33 @@ generate only the specified files.
 
 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 BignumTarget(test_generation.BaseTarget, metaclass=ABCMeta):
 
 
 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 @@ class BignumOperation(BignumTarget, metaclass=ABCMeta):
         """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 @@ class BignumOperation(BignumTarget, metaclass=ABCMeta):
 
     @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 BignumOperation(BignumTarget, metaclass=ABCMeta):
 
 
 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 BignumCmp(BignumOperation):
 
 
 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 BignumCmpAbs(BignumCmp):
 
 
 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 BignumAdd(BignumOperation):
 
 
 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__()