diff --git a/CHANGELOG b/CHANGELOG
index 8905d86ec..c0a14427f 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -7,6 +7,9 @@ Changes between 2.3.1 and 2.3.2.dev
 
 - fix teardown-ordering for parametrized setups
 
+- fix issue127 - better documentation for pytest_addoption
+  and related objects.
+
 - fix unittest behaviour: TestCase.runtest only called if there are
   test methods defined
 
diff --git a/_pytest/config.py b/_pytest/config.py
index 7e0f9ead6..29b4e1eaa 100644
--- a/_pytest/config.py
+++ b/_pytest/config.py
@@ -19,7 +19,7 @@ def pytest_unconfigure(config):
         fin()
 
 class Parser:
-    """ Parser for command line arguments. """
+    """ Parser for command line arguments and ini-file values.  """
 
     def __init__(self, usage=None, processopt=None):
         self._anonymous = OptionGroup("custom options", parser=self)
@@ -38,9 +38,14 @@ class Parser:
     def getgroup(self, name, description="", after=None):
         """ get (or create) a named option Group.
 
-        :name: unique name of the option group.
+        :name: name of the option group.
         :description: long description for --help output.
         :after: name of other group, used for ordering --help output.
+
+        The returned group object has an ``addoption`` method with the same
+        signature as :py:func:`parser.addoption
+        <_pytest.config.Parser.addoption>` but will be shown in the
+        respective group in the output of ``pytest. --help``.
         """
         for group in self._groups:
             if group.name == name:
@@ -54,7 +59,19 @@ class Parser:
         return group
 
     def addoption(self, *opts, **attrs):
-        """ add an optparse-style option. """
+        """ register a command line option.
+
+        :opts: option names, can be short or long options.
+        :attrs: same attributes which the ``add_option()`` function of the
+           `optparse library
+           <http://docs.python.org/library/optparse.html#module-optparse>`_
+           accepts.
+
+        After command line parsing options are available on the pytest config
+        object via ``config.option.NAME`` where ``NAME`` is usually set
+        by passing a ``dest`` attribute, for example
+        ``addoption("--long", dest="NAME", ...)``.
+        """
         self._anonymous.addoption(*opts, **attrs)
 
     def parse(self, args):
@@ -75,7 +92,15 @@ class Parser:
         return args
 
     def addini(self, name, help, type=None, default=None):
-        """ add an ini-file option with the given name and description. """
+        """ register an ini-file option.
+
+        :name: name of the ini-variable
+        :type: type of the variable, can be ``pathlist``, ``args`` or ``linelist``.
+        :default: default value if no ini-file option exists but is queried.
+
+        The value of ini-variables can be retrieved via a call to
+        :py:func:`config.getini(name) <_pytest.config.Config.getini>`.
+        """
         assert type in (None, "pathlist", "args", "linelist")
         self._inidict[name] = (help, type, default)
         self._ininames.append(name)
@@ -246,8 +271,9 @@ class CmdOptions(object):
 class Config(object):
     """ access to configuration values, pluginmanager and plugin hooks.  """
     def __init__(self, pluginmanager=None):
-        #: command line option values, usually added via parser.addoption(...)
-        #: or parser.getgroup(...).addoption(...) calls
+        #: command line option values, which must have been previously added
+        #: via calls like ``parser.addoption(...)`` or
+        #: ``parser.getgroup(groupname).addoption(...)``
         self.option = CmdOptions()
         self._parser = Parser(
             usage="usage: %prog [options] [file_or_dir] [file_or_dir] [...]",
diff --git a/_pytest/hookspec.py b/_pytest/hookspec.py
index ec98b0de3..f9f8b4ded 100644
--- a/_pytest/hookspec.py
+++ b/_pytest/hookspec.py
@@ -23,8 +23,10 @@ def pytest_cmdline_preparse(config, args):
     """modify command line arguments before option parsing. """
 
 def pytest_addoption(parser):
-    """add optparse-style options and ini-style config values via calls
-    to ``parser.addoption`` and ``parser.addini(...)``.
+    """use the parser to add optparse-style options and ini-style
+    config values via calls, see :py:func:`parser.addoption(...)
+    <_pytest.config.Parser.addoption>`
+    and :py:func:`parser.addini(...) <_pytest.config.Parser.addini>`.
     """
 
 def pytest_cmdline_main(config):
diff --git a/doc/en/announce/index.txt b/doc/en/announce/index.txt
index a8e250eea..a36a7aeb3 100644
--- a/doc/en/announce/index.txt
+++ b/doc/en/announce/index.txt
@@ -5,6 +5,7 @@ Release announcements
 .. toctree::
    :maxdepth: 2
 
+   release-2.3.1
    release-2.3.0
    release-2.2.4
    release-2.2.2
diff --git a/doc/en/conf.py b/doc/en/conf.py
index 2019d08fd..f19610624 100644
--- a/doc/en/conf.py
+++ b/doc/en/conf.py
@@ -17,7 +17,7 @@
 #
 # The full version, including alpha/beta/rc tags.
 # The short X.Y version.
-version = release = "2.3.1"
+version = release = "2.3.2.dev9"
 
 import sys, os