[py-svn] r11494 - py/dist/py/documentation

[hpk at codespeak.net]

Author: hpk
Date: Tue Apr 26 23:50:13 2005
New Revision: 11494

Modified:
   py/dist/py/documentation/test.txt
Log:
fixed ReST and some phrasings 



Modified: py/dist/py/documentation/test.txt
==============================================================================
--- py/dist/py/documentation/test.txt	(original)
+++ py/dist/py/documentation/test.txt	Tue Apr 26 23:50:13 2005
@@ -473,32 +473,40 @@
 are  reponsible for representing the testing process 
 to the user or other programs: 
 
-** session.header() and session.footer** 
+*session.header()* 
 
-    usually invoked once for a whole test session run. 
+    invoked once by ``session.run()`` before the whole 
+    test session starts.
 
-** session.start(colitem) ** 
 
-    invoked before the ``colitem.run()`` is invoked 
+*session.footer()*
 
-** session.finish(colitem, outcome) ** 
+    invoked once by ``session.run()`` after the collection
+    and running process finished. 
 
-    invoked after a colitem is run. 
 
-PLEASE NOTE that these methods are likely to change soon 
-because the session object now has too many names that aren't 
-easily distinguishable regarding their purposes. 
-It is also likely that collectors/test items will 
-become more self-responsible for presenting outcomes
-in textual ways.  Currently session object have to 
-know too much about the representation of 
-failures/successes to the user which makes it 
-harder than neccessary to write custom test items. 
+*session.start(colitem)*
+
+    invoked before for each ``colitem.run()`` invocation 
+
+
+*session.finish(colitem, outcome)*
+
+    invoked after each ``colitem.run()`` invocation 
+
+
+XXX the names of these session objects are likely to change
+soon because the session object now has too many names that
+aren't easily distinguishable regarding their purposes.  It is
+also likely that collectors/test items will become more
+self-responsible for presenting outcomes in textual ways.
+Currently, session object have to know too much about the
+representation of failures/successes to the user which makes
+it harder than neccessary to write custom test items. 
 
 Customizing the testing process 
 ===============================
 
-
 customizing the collecting and running process 
 -----------------------------------------------
 
@@ -562,6 +570,7 @@
 which themselves create ``ReSTSyntaxTest`` and ``LinkCheckerMaker`` 
 items.  All of this instances (need to) follow the `collector API`_. 
 
+
 Customizing the collection process in a module
 ---------------------------------------------- 
 
@@ -582,21 +591,25 @@
 is responsible for setting up and executing an underlying 
 test.  [XXX not working: You can integrate your custom ``py.test.Item`` subclass 
 by binding an ``Item`` name to a test class.]  Or you can 
-take over larger parts of the collection process by putting 
-Items in a ``conftest.py`` configuration file. 
+extend the collection process for a whole directory tree 
+by putting Items in a ``conftest.py`` configuration file. 
 The collection process constantly looks at according names 
 in the *chain of conftest.py* modules to determine collectors
 and items at ``Directory``, ``Module``, ``Class``, ``Function`` 
-or ``Generator`` level.  Note that except for ``Function`` 
-all classes are pure collectors, i.e. will return a list 
+or ``Generator`` level.  Note that, right now, except for ``Function`` 
+items all classes are pure collectors, i.e. will return a list 
 of names (possibly empty). 
 
+XXX implement doctests as alternatives to ``Function`` items. 
+
 Customizing execution of Functions 
 ---------------------------------- 
 
 - Function test items allow total control of executing their 
   contained test method.  ``function.run()`` will get called by the
-  session in order to actually run a test with proper setup/teardown. 
+  session in order to actually run a test.  The method is responsible
+  for performing proper setup/teardown ("Test Fixtures") for a 
+  Function test. 
 
 - ``Function.execute(target, *args)`` methods are invoked by
   the default ``Function.run()`` to actually execute a python