refine docs

5 files changed, 44 insertions, 15 deletions

diff --git a/README.rst b/README.rst
index c107df0..9935581 100644
--- a/README.rst
+++ b/README.rst
@@ -21,5 +21,5 @@ For more information and the repository please checkout:
 
 have fun,
 
-holger krekel, 2014
+holger krekel, 2015
 
diff --git a/doc/index.txt b/doc/index.txt
index 1a123fc..e1bc20e 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -65,8 +65,7 @@ Current features
 
 * :doc:`(new in 2.0) plugin system <plugins>` to modify tox execution with simple hooks.
 
-* uses pip_ and setuptools_ by default.  Experimental
-  support for configuring the installer command
+* uses pip_ and setuptools_ by default.  Support for configuring the installer command
   through :confval:`install_command=ARGV`.
 
 * **cross-Python compatible**: CPython-2.6, 2.7, 3.2 and higher,
diff --git a/doc/plugins.txt b/doc/plugins.txt
index 61e4408..bd3ceda 100644
--- a/doc/plugins.txt
+++ b/doc/plugins.txt
@@ -6,8 +6,9 @@ tox plugins
 .. versionadded:: 2.0
 
 With tox-2.0 a few aspects of tox running can be experimentally modified
-by writing hook functions.  We expect the list of hook function to grow
-over time.
+by writing hook functions.  The list of of available hook function is
+to grow over time on a per-need basis.
+
 
 writing a setuptools entrypoints plugin
 ---------------------------------------
@@ -30,19 +31,23 @@ Python packaging index::
             install_requires=['tox>=2.0'],
         )
 
-You can then install the plugin to develop it via::
+If installed, the ``entry_points`` part will make tox see and integrate
+your plugin during startup.
+
+You can install the plugin for development ("in-place") via::
 
     pip install -e .
 
-and later publish it.
+and later publish it via something like::
 
-The ``entry_points`` part allows tox to see your plugin during startup.
+    python setup.py sdist register upload
 
 
 Writing hook implementations
 ----------------------------
 
-A plugin module needs can define one or more hook implementation functions::
+A plugin module defines one or more hook implementation functions
+by decorating them with tox's ``hookimpl`` marker::
 
     from tox import hookimpl
 
@@ -65,5 +70,9 @@ tox hook specifications
 ----------------------------
 
 .. automodule:: tox.hookspecs
+
+.. autoclass:: tox.config.Parser
     :members:
 
+.. autoclass:: tox.config.Config
+    :members:
diff --git a/tox/config.py b/tox/config.py
index d6dfcff..52da961 100644
--- a/tox/config.py
+++ b/tox/config.py
@@ -38,29 +38,48 @@ def get_plugin_manager():
     return pm
 
 
-class MyParser:
+class Parser:
+    """ command line and ini-parser control object. """
+
     def __init__(self):
         self.argparser = argparse.ArgumentParser(
             description="tox options", add_help=False)
         self._testenv_attr = []
 
     def add_argument(self, *args, **kwargs):
+        """ add argument to command line parser.  This takes the
+        same arguments that ``argparse.ArgumentParser.add_argument``.
+        """
         return self.argparser.add_argument(*args, **kwargs)
 
     def add_testenv_attribute(self, name, type, help, default=None, postprocess=None):
+        """ add an ini-file variable for "testenv" section.
+
+        Types are specified as strings like "bool", "line-list", "string", "argv", "path",
+        "argvlist".  The ``postprocess`` function will be called for each testenv
+        like ``postprocess(config=config, reader=reader, section_val=section_val)``
+        where ``section_val`` is the value as read from the ini (or the default value).
+        Any postprocess function must return a value which will then become the
+        eventual value in the testenv section.
+        """
         self._testenv_attr.append(VenvAttribute(name, type, default, help, postprocess))
 
     def add_testenv_attribute_obj(self, obj):
+        """ add an ini-file variable as an object.
+
+        This works as ``add_testenv_attribute`` but expects "name", "type", "help",
+        and "postprocess" attributes on the object.
+        """
         assert hasattr(obj, "name")
         assert hasattr(obj, "type")
         assert hasattr(obj, "help")
         assert hasattr(obj, "postprocess")
         self._testenv_attr.append(obj)
 
-    def parse_args(self, args):
+    def _parse_args(self, args):
         return self.argparser.parse_args(args)
 
-    def format_help(self):
+    def _format_help(self):
         return self.argparser.format_help()
 
 
@@ -168,11 +187,11 @@ def parseconfig(args=None):
         args = sys.argv[1:]
 
     # prepare command line options
-    parser = MyParser()
+    parser = Parser()
     pm.hook.tox_addoption(parser=parser)
 
     # parse command line options
-    option = parser.parse_args(args)
+    option = parser._parse_args(args)
     interpreters = tox.interpreters.Interpreters(hook=pm.hook)
     config = Config(pluginmanager=pm, option=option, interpreters=interpreters)
     config._parser = parser
@@ -440,10 +459,12 @@ def tox_addoption(parser):
 
 class Config(object):
     def __init__(self, pluginmanager, option, interpreters):
+        #: dictionary containing envname to envconfig mappings
         self.envconfigs = {}
         self.invocationcwd = py.path.local()
         self.interpreters = interpreters
         self.pluginmanager = pluginmanager
+        #: option namespace containing all parsed command line options
         self.option = option
 
     @property
diff --git a/tox/session.py b/tox/session.py
index e886274..4fd8706 100644
--- a/tox/session.py
+++ b/tox/session.py
@@ -44,7 +44,7 @@ def main(args=None):
 
 def show_help(config):
     tw = py.io.TerminalWriter()
-    tw.write(config._parser.format_help())
+    tw.write(config._parser._format_help())
     tw.line()