From 2855a2f6cba203cef4910103b0dee672b985142f Mon Sep 17 00:00:00 2001
From: holger krekel <holger@merlinux.eu>
Date: Tue, 16 Oct 2012 16:27:51 +0200
Subject: [PATCH] remove outdated IMPL.txt and move up-to-date doc bits to
 FixtureMapper class.

---
 IMPL.txt          | 40 ----------------------------------------
 _pytest/python.py | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 40 deletions(-)
 delete mode 100644 IMPL.txt

diff --git a/IMPL.txt b/IMPL.txt
deleted file mode 100644
index f2dce0275..000000000
--- a/IMPL.txt
+++ /dev/null
@@ -1,40 +0,0 @@
-
-internal fixture mechanics
-----------------------------
-
-fixture mechanics are contained in the python.py plugin.
-
-pytest fixtures are stored and managed from the FixtureManager (fm) class.
-Upon collection fm.parsefactories() is called multiple times to parse
-fixture function definitions into FixtureDef objects.
-
-During collection of test functions, metafunc needs to grow a "fixturenames"
-list so that pytest_generate_tests() hooks can check it.   These fixturenames
-are a closure of all known fixtures to be used for this function:
-
-- ini-defined usefixtures
-- autouse-marked fixtures along the collection chain up from the function
-- usefixtures markers at module/class/function level
-- test function funcargs
-
-The latter list (without the closure) is also called "_initialfixtures"
-and will be used during the test setup phase.
-
-Upon the test-setup phases initialfixtures are instantiated which
-will subsequently create the full fixture closure (as was computed in
-metafunc.fixturenames during collection).  As fixture functions
-can invoke request.getfuncargvalue() the actual closure may be even
-bigger.
-
-object model
----------------------
-
-As part of the metafunc-protocol parents of Function nodes get a
-ParentFixtures() object, containing helping/caching for 
-for a function. .getfixtureinfo(func) returns a FixtureInfo with these
-attributes:
-
-- names_initial: list of initial fixture names (see above)
-- names_closure: closure of all fixture names
-- name2fixturedefs: for creating the value
-
diff --git a/_pytest/python.py b/_pytest/python.py
index 1b1fde898..7f7d89b42 100644
--- a/_pytest/python.py
+++ b/_pytest/python.py
@@ -327,6 +327,38 @@ class PyCollector(PyobjMixin, pytest.Collector):
                                keywords={callspec.id:True})
 
 class FixtureMapper:
+    """
+    pytest fixtures definitions and information is stored and managed
+    from this class.
+
+    During collection fm.parsefactories() is called multiple times to parse
+    fixture function definitions into FixtureDef objects and internal
+    data structures.
+
+    During collection of test functions, metafunc-mechanics instantiate
+    a FuncFixtureInfo object which is cached in a FixtureMapper instance
+    which itself lives on the parent collector.  This FuncFixtureInfo object
+    is later retrieved by Function nodes which themselves offer a fixturenames
+    attribute.
+
+    The FuncFixtureInfo object holds information about fixtures and FixtureDefs
+    relevant for a particular function.  An initial list of fixtures is
+    assembled like this:
+
+    - ini-defined usefixtures
+    - autouse-marked fixtures along the collection chain up from the function
+    - usefixtures markers at module/class/function level
+    - test function funcargs
+
+    Subsequently the funcfixtureinfo.fixturenames attribute is computed
+    as the closure of the fixtures needed to setup the initial fixtures,
+    i. e. fixtures needed by fixture functions themselves are appended
+    to the fixturenames list.
+
+    Upon the test-setup phases all fixturenames are instantiated, retrieved
+    by a lookup on a FixtureMapper().
+    """
+
     def __init__(self, node, funcargs=True):
         self.node = node
         self.fm = node.session._fixturemanager