improve documentation/examples

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/tools/make/trunk@32149 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -1,3 +1,19 @@
+2011-01-13  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* TestFramework/Testing.h:
+	* TestFramework/example1.m:
+	* TestFramework/example2.m:
+	* TestFramework/example3.m:
+	* TestFramework/example4.m:
+	* TestFramework/example5.m:
+	* TestFramework/example6.m:
+	* TestFramework/example7.m:
+	* TestFramework/example8.m:
+	* TestFramework/README:
+	* GNUmakefile.in:
+	Fix header file in examples.  Add comments/documentation to explain
+	use of brackets in macro parameters.  Add an example to demonstrate it.
+
 2011-01-13  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* TestFramework/Testing.h:

GNUmakefile.in

@@ -142,7 +142,7 @@ INSTANCE_DOC_MAKE_FILES = autogsdoc.make gsdoc.make install_files.make \
 TEST_FRAMEWORK_FILES = \
 	GNUmakefile.in Testing.h ObjectTesting.h README \
 	example1.m example2.m example3.m example4.m example5.m \
-	example6.m example7.m
+	example6.m example7.m example8.m
 
 # Decide which version of the GNUstep.conf file we are going to
 # install; the standard one, or the strict gnustep-make v2 one ?

TestFramework/README

@@ -127,6 +127,7 @@ All have uppercase names beginning with 'PASS'.
 All wrap test code and a call to the pass() function in exception handlers.
 All provide file name and line number information in the description string.
 All are code blocks and do not need a semicolon terminator.
+Code fragments must be enclosed in round brackets if they contain commas.
 
 PASS		passes if an expression resulting in an integer value is
 		non-zero

TestFramework/Testing.h

@@ -131,6 +131,8 @@ static void unsupported(const char *format, ...)
 }
 
 /* Tests a code expression which evaluates to an integer value.
+ * The expression may not contain commas unless it is bracketed.
+ * The format must be a literal string printf style format.
  * If the expression evaluates to zero the test does not pass.
  * If the expression causes an exception to be raised, the exception
  * is caught and logged but the test does not pass.
@@ -155,6 +157,9 @@ static void unsupported(const char *format, ...)
   NS_ENDHANDLER
 
 /* Tests a code expression which evaluates to an object value.
+ * The expression may not contain commas unless it is bracketed.
+ * The expected value may not contain commas unless it is bracketed.
+ * The format must be a literal string printf style format.
  *
  * Where the expression evaluates to an object which is identical to
  * the expect value, or where [object isEqual: expect] returns YES,
@@ -206,6 +211,9 @@ static void unsupported(const char *format, ...)
  * or throws the wrong exception, then the code does not pass.
  * You can supply nil for expectedExceptionName if you don't care about the
  * type of exception.
+ * The code fragment may not contain commas unless it is surrounded by
+ * brackets. eg. PASS_EXCEPTION(({code here}), name, "hello")
+ * The format must be a literal string printf style format.
  */
 #define PASS_EXCEPTION(code, expectedExceptionName, format, ...) \
   NS_DURING \
@@ -226,6 +234,9 @@ static void unsupported(const char *format, ...)
 /* Please use the PASS_RUNS() macro to handle any code where you want the
  * code to run to completion without an exception being thrown, but you don't
  * have a particular expression to be checked.
+ * The code fragment may not contain commas unless it is surrounded by
+ * brackets. eg. PASS_EXCEPTION(({code here}), name, "hello")
+ * The format must be a literal string printf style format.
  */
 #define PASS_RUNS(code, format, ...) \
   NS_DURING \
@@ -269,8 +280,8 @@ static void unsupported(const char *format, ...)
 
 
 /* The END_SET() macro terminates a set of grouped tests.  It's argument is
- * a printf style format string and variable arguments to print a message
- * describing the set.
+ * a literal printf style format string and variable arguments to print a
+ * message describing the set.
  */
 #define END_SET(format, ...) \
 	} \

TestFramework/example1.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* This is the absolute minimal test program ...
  * a single test case involving plain C and no Objective-C code.

TestFramework/example2.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A second test ... your first go at testing with ObjectiveC
  *

TestFramework/example3.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A third test ... using test macros.
  *

TestFramework/example4.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A fourth test ... testing for an exception.
  *

TestFramework/example5.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A fifth test ... hope.
  *

TestFramework/example6.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A sixth test ... need.
  *

TestFramework/example7.m

@@ -1,4 +1,4 @@
-#import	<ObjectTesting.h>
+#import	<Testing.h>
 
 /* A seventh test ... nesting sets.
  *

TestFramework/example8.m

@@ -0,0 +1,33 @@
+#import	<Testing.h>
+#import	<NSFoundation/NSGeometry.h>
+
+/* An eighth test ... complex code fragments
+ *
+ * If you run the test with 'gnustep-tests example8.m' it should
+ * report a single test file completed, one test pass.
+ */
+int
+main()
+{
+  /* Start a set.
+   */
+  START_SET(YES)
+
+  /* Here we demonstrate that the 'expression' evaluated by the PASS
+   * macro can actually be an arbitrarily complex piece of code as
+   * long as the last statement returns an integral value which can
+   * be used to represent a pass (non zero) or fail (if zero).
+   * Where such a code fragment contains commas, it must be written
+   * inside brackets to let the macro preprocessor know that the whole
+   * code fragement is the first parameter to the macro.
+   */
+  PASS(({
+    NSRange	r = NSMakeRange(1, 10);
+    
+    NSEqualRanges(r, NSMakeRange(1, 10));
+  }), "a long code-fragment/expression works")
+
+  END_SET("test set")
+
+  return 0;
+}