lac  committed e074884

some grammar issues (less/fewer) and some typos but a fair number of
unresolved problems. What is written is unclear, and I don't know what
the intent was.

  • Participants
  • Parent commits 1967503
  • Branches default

Comments (0)

Files changed (1)

File doc/plugins.txt

      py.test a/  # will show "setting up"
 A note on ordering: ``py.test`` loads all ```` files upwards
-from the command line file arguments.  It usually performs look up
+from the command line file arguments. 
+XYZZY I don't know what you mean here.  But not 'upwards'  You don't
+load things upwards. Do you mean that py.test will start looking for files in the current directory, and then in its parent,
+and so on all the way to the root of the filesystem?
+It usually performs look up
 right-to-left, i.e.  the hooks in "closer" conftest files will be called
 earlier than further away ones.
+XYZZY I'm still confused.  I understand right to left but I don't understand
+the concept of one conftest file being closer than another one, or indeed
+that I have a position that things could be closer to or further away from.
 .. Note::
     If you have ```` files which do not reside in a
     python package directory (i.e. one containing an ````) then
 If you want to make your plugin externally available, you
-may define a so called entry point for your distribution so
+may define a so-called entry point for your distribution so
 that ``py.test`` finds your plugin module.  Entry points are
 a feature that is provided by `setuptools`_ or `Distribute`_.
-The concrete entry point is ``pytest11``.  To make your plugin
+The concrete entry point is ``pytest11``.  
+XYZZY I don't know whether every plugin must use this same entry point,
+      pytest11 or whether this is an example using the entry point pytest11
+      which you could name something else, or whether you could, but it is
+      the convention to all use the same one.
+To make your plugin
 available you can insert the following lines in your
 setuptools/distribute-based setup-invocation:
     py.test -p no:NAME
+XYZZY You've not been using capital letter before.  Is there a reason to
+use them now?  
 This means that any subsequent try to activate/load the named
 plugin will it already existing.  See :ref:`findpluginname` for
 how to obtain the name of a plugin.
+XYZZY The above sentence doesn't make sense.  Do you mean the that
+any subsequent attempt to activate or load the named plugin will fail?
+will raise an exception?  What happens if you try to unregister a
+plugin that you don't have loaded?
 .. _`builtin plugins`:
 py.test default plugin reference
 py.test calls hook functions to implement initialization, running,
 test execution and reporting.  When py.test loads a plugin it validates
-that all hook functions conform to their respective hook specification.
+that all hook functions conform to their respective hook specifications.
 Each hook function name and its argument names need to match a hook
-specification exactly but it is allowed for a hook function to accept
-*less* parameters than specified.  If you mistype argument names or the
+specification exactly but a hook function may accept
+*fewer* parameters than specified.  If you mistype argument names or the
 hook name itself you get useful errors.
 initialisation, command line and configuration hooks
 For deeper understanding you may look at the default implementation of
 these hooks in :py:mod:`_pytest.runner` and maybe also
-in :py:mod:`_pytest.pdb` which intercepts creation
-of reports in order to drop to interactive debugging.
+in :py:mod:`_pytest.pdb` which intercepts report creation
+in order to drop into interactive debugging.
 The :py:mod:`_pytest.terminal` reported specifically uses
 the reporting hook to print information about a test run.
 .. autofunction:: pytest_collect_directory
 .. autofunction:: pytest_collect_file
-For influencing the collection of objects in Python modules
+To influence the collection of objects in Python modules
 you can use the following hook:
+XYZZY: 'influence' is pretty wishy-washy.  It would be better to write
+something like: You can use the following hook to change the way py.test
+collects objects in Python modules.  If influence means something else,
+then it either needs to be explained, or a better synonym needs to be
 .. autofunction:: pytest_pycollect_makeitem