advance customization docs, enhance docstrings, add more reference object docs.

--HG--
branch : trunk

pytest/collect.py

@@ -25,13 +25,20 @@ class HookProxy:
 
 class Node(object):
     """ base class for all Nodes in the collection tree.
-        Collector subclasses have children, Items are terminal nodes.
-    """
+    Collector subclasses have children, Items are terminal nodes."""
+
     def __init__(self, name, parent=None, config=None, collection=None):
+        #: a unique name with the scope of the parent
         self.name = name
+
+        #: the parent collector node.
         self.parent = parent
+        
         self.config = config or parent.config
+        #: the collection this node is part of.
         self.collection = collection or getattr(parent, 'collection', None)
+        
+        #: the file where this item is contained/collected from.
         self.fspath = getattr(parent, 'fspath', None)
         self.ihook = HookProxy(self)
         self.keywords = self.readkeywords()
@@ -130,13 +137,8 @@ class Node(object):
     repr_failure = _repr_failure_py
 
 class Collector(Node):
-    """
-        Collector instances create children through collect()
-        and thus iteratively build a tree.  attributes::
-
-        parent: attribute pointing to the parent collector
-                (or None if this is the root collector)
-        name:   basename of this collector object
+    """ Collector instances create children through collect()
+        and thus iteratively build a tree.
     """
     Directory = configproperty('Directory')
     Module = configproperty('Module')
@@ -166,6 +168,15 @@ class Collector(Node):
         """ internal helper method to cache results of calling collect(). """
         return self._memoizedcall('_collected', self.collect)
 
+    def _prunetraceback(self, traceback):
+        if hasattr(self, 'fspath'):
+            path = self.fspath
+            ntraceback = traceback.cut(path=self.fspath)
+            if ntraceback == traceback:
+                ntraceback = ntraceback.cut(excludepath=py._pydir)
+            traceback = ntraceback.filter()
+        return traceback
+
     # **********************************************************************
     # DEPRECATED METHODS
     # **********************************************************************
@@ -197,15 +208,6 @@ class Collector(Node):
         """
         return self.collect_by_name(name)
 
-    def _prunetraceback(self, traceback):
-        if hasattr(self, 'fspath'):
-            path = self.fspath
-            ntraceback = traceback.cut(path=self.fspath)
-            if ntraceback == traceback:
-                ntraceback = ntraceback.cut(excludepath=py._pydir)
-            traceback = ntraceback.filter()
-        return traceback
-
 class FSCollector(Collector):
     def __init__(self, fspath, parent=None, config=None, collection=None):
         fspath = py.path.local(fspath)
@@ -264,7 +266,10 @@ class Directory(FSCollector):
         return self.ihook.pytest_collect_directory(path=path, parent=self)
 
 class Item(Node):
-    """ a basic test item. """
+    """ a basic test invocation item. Note that for a single function
+    there might be multiple test invocation items. Attributes:
+    
+    """
     def _deprecated_testexecution(self):
         if self.__class__.run != Item.run:
             warnoldtestrun(function=self.run)

pytest/hookspec.py

@@ -53,18 +53,20 @@ def pytest_log_finishcollection(collection):
     """ called after collection has finished. """
 
 def pytest_ignore_collect(path, config):
-    """ return true value to prevent considering this path for collection.
-    This hook is consulted for all files and directories prior to considering
-    collection hooks.
+    """ return True to prevent considering this path for collection.
+    This hook is consulted for all files and directories prior to calling
+    more specific hooks.
     """
 pytest_ignore_collect.firstresult = True
 
 def pytest_collect_directory(path, parent):
-    """ return Collection node or None for the given path. """
+    """ return collection Node or None for the given path. Any new node
+    needs to have the specified ``parent`` as a parent."""
 pytest_collect_directory.firstresult = True
 
 def pytest_collect_file(path, parent):
-    """ return Collection node or None for the given path. """
+    """ return collection Node or None for the given path. Any new node
+    needs to have the specified ``parent`` as a parent."""
 
 # logging hooks for collection
 def pytest_collectstart(collector):
@@ -113,23 +115,30 @@ def pytest_itemstart(item, node=None):
     """ (deprecated, use pytest_runtest_logstart). """
 
 def pytest_runtest_protocol(item):
-    """ implement fixture, run and report about the given test item. """
+    """ implements the standard runtest_setup/call/teardown protocol including
+    capturing exceptions and calling reporting hooks on the results accordingly.
+
+    :return boolean: True if no further hook implementations should be invoked.
+    """
 pytest_runtest_protocol.firstresult = True
 
 def pytest_runtest_logstart(nodeid, location, fspath):
     """ signal the start of a test run. """
 
 def pytest_runtest_setup(item):
-    """ called before pytest_runtest_call(). """
+    """ called before ``pytest_runtest_call(item)``. """
 
 def pytest_runtest_call(item):
-    """ execute test item. """
+    """ called to execute the test ``item``. """
 
 def pytest_runtest_teardown(item):
-    """ called after pytest_runtest_call(). """
+    """ called after ``pytest_runtest_call``. """
 
 def pytest_runtest_makereport(item, call):
-    """ make a test report for the given item and call outcome. """
+    """ return a :py:class:`pytest.plugin.runner.TestReport` object
+    for the given :py:class:`pytest.collect.Item` and
+    :py:class:`pytest.plugin.runner.CallInfo`.
+    """
 pytest_runtest_makereport.firstresult = True
 
 def pytest_runtest_logreport(report):

pytest/plugin/runner.py

@@ -113,8 +113,11 @@ def call_runtest_hook(item, when):
     return CallInfo(lambda: ihook(item=item), when=when)
 
 class CallInfo:
+    """ Call Information about a hook call. """
+    #: None or ExceptionInfo object.
     excinfo = None
     def __init__(self, func, when):
+        #: one of "setup", "call", "teardown" specifying the runtest phase.
         self.when = when
         try:
             self.result = func()
@@ -169,15 +172,36 @@ def pytest_runtest_makereport(item, call):
         keywords, outcome, longrepr, when)
 
 class TestReport(BaseReport):
+    """ Basic test report object (also used for setup and teardown calls if
+    they fail).
+    """
     def __init__(self, nodeid, nodenames, fspath, location,
             keywords, outcome, longrepr, when):
+        #: normalized collection node id
         self.nodeid = nodeid
+
+        #: list of names indicating position in collection tree.
         self.nodenames = nodenames
+
+        #: the collected path of the file containing the test.
         self.fspath = fspath  # where the test was collected
+
+        #: a (filesystempath, lineno, domaininfo) tuple indicating the
+        #: actual location of a test item - it might be different from the
+        #: collected one e.g. if a method is inherited from a different module.
         self.location = location
+
+        #: a name -> value dictionary containing all keywords and
+        #: markers associated with a test invocation.
         self.keywords = keywords
+        
+        #: test outcome, always one of "passed", "failed", "skipped".
         self.outcome = outcome
+
+        #: None or a failure representation.
         self.longrepr = longrepr
+        
+        #: one of 'setup', 'call', 'teardown' to indicate runtest phase.
         self.when = when
 
     def __repr__(self):