+docs for SuiteFactory.Vector

src/test/Test.winxed

@@ -1,19 +1,28 @@
 namespace Rosella
 {
     /* The Rosella Test Library
-        This library is used to implement unit tests, although not a test
+        This library is used to implement the logic of unit tests. It is not
+        used to implement a test harness. Use the Rosella Harness for making a
         harness. By default, the test library produces TAP output, although
-        that and much other behavior can be overridden by subclassing
+        that and much other behavior can be overridden by subclassing.
+
+        The routines in this namespace are convenience facade routines for
+        interacting with the Test library. This is not the only way to use the
+        library, just the most convenient.
     */
     namespace Test
     {
+        /* Public API functions
+        */
+
         /* Test options:
             suite_type: The type of Suite object to use.
             testcase_type: The type of TestCase object to use.
             context: The TestContext object instance to use. Stored in $!context
             test_prefix: A prefix string that all test methods must have.
             asserter: The assertion object. Stored in $!assert
         */
+
         // Setup and run a test using Testcase-based tests. This is basically
         // a thin facade over SuiteFactory and Suite with some defaults thrown
         // in. Returns 1 if the test was a success, 0 otherwise.
@@ -26,6 +35,8 @@ namespace Rosella
             return result.was_successful();
         }
 
+        // Setup and run a single test function over a sequence of data
+        // objects.
         function test_vector(var func, var tests, var options [slurpy,named])
         {
             __default_options(options);
@@ -35,6 +46,11 @@ namespace Rosella
             return result.was_successful();
         }
 
+        /* Private or Internal Routines
+        */
+
+        // Make sure that we have some values for the important option keys.
+        // If the user has provided an override for any of these, ignore.
         function __default_options(var options)
         {
             if (!(exists options["suite_type"]))

src/test/suitefactory/Vector.winxed

@@ -1,30 +1,45 @@
 namespace Rosella { namespace Test { namespace SuiteFactory
 {
+    /* Vectorized SuiteFactory
+        This class is a SuiteFactory which creates a suite for a vectorized
+        test file. Vectorized tests are a test where a single function is
+        executed on each item in an array or hash of data. This SuiteFactory
+        creates a test method for each item in the data array.
+    */
     class Vector : Rosella.Test.SuiteFactory
     {
-        var data;
-        var func;
+        var data;   // The data. Can be an array, a hash, or any other scalar
+        var func;   // The function to execute.
 
+        /* Public Methods
+        */
+
+        // Constructor
         function Vector(var func, var data, var options)
         {
             self.SuiteFactory(null, options);
             self.data = data;
             self.func = func;
         }
 
+        // Get a hash of test methods, one for each item in the data aggregate
         function get_test_methods()
         {
             int is_role = 0;
             var data = self.data;
             ${ does is_role, data, "array" };
             if (is_role)
-                return self.get_test_methods_from_array();
+                return self.__get_test_methods_from_array();
             ${ does is_role, data, "hash" };
             if (is_role)
-                return self.get_test_methods_from_hash();
-            return self.get_test_method_from_scalar();
+                return self.__get_test_methods_from_hash();
+            return self.__get_test_method_from_scalar();
         }
 
+        /* Private Helper Methods
+        */
+
+        // Create a closure over the function and the particular datum
         function __make_test_method(var n, var f, var d)
         {
             var func = f;
@@ -36,7 +51,8 @@ namespace Rosella { namespace Test { namespace SuiteFactory
             };
         }
 
-        function get_test_methods_from_array()
+        // The data is an array. Get test methods from that.
+        function __get_test_methods_from_array()
         {
             var test_methods = {};
             for (int i = 0; i < elements(self.data); i++) {
@@ -46,15 +62,17 @@ namespace Rosella { namespace Test { namespace SuiteFactory
             return test_methods;
         }
 
-        function get_test_methods_from_hash()
+        // The data is a hash
+        function __get_test_methods_from_hash()
         {
             var test_methods = {};
             for (string key in self.data)
                 test_methods[key] = self.__make_test_method(key, self.func, self.data[key]);
             return test_methods;
         }
 
-        function get_test_methods_from_scalar()
+        // The data is not an array or a hash, treat it as a single value
+        function __get_test_methods_from_scalar()
         {
             return {
                 "test" : self.__make_test_method("test", self.func, self.data)