rewrite the documentation (#1519)

2 files changed, 23 insertions, 4 deletions

diff --git a/src/virtualenv/discovery/builtin.py b/src/virtualenv/discovery/builtin.py
index e4e0ea0..c5f4883 100644
--- a/src/virtualenv/discovery/builtin.py
+++ b/src/virtualenv/discovery/builtin.py
@@ -15,7 +15,7 @@ from .py_spec import PythonSpec
 
 class Builtin(Discover):
     def __init__(self, options):
-        super(Builtin, self).__init__()
+        super(Builtin, self).__init__(options)
         self.python_spec = options.python
 
     @classmethod
diff --git a/src/virtualenv/discovery/discover.py b/src/virtualenv/discovery/discover.py
index 13e258f..17d404e 100644
--- a/src/virtualenv/discovery/discover.py
+++ b/src/virtualenv/discovery/discover.py
@@ -7,20 +7,39 @@ import six
 
 @six.add_metaclass(ABCMeta)
 class Discover(object):
-    def __init__(self):
-        self._has_run = False
-        self._interpreter = None
+    """Discover and provide the requested Python interpreter"""
 
     @classmethod
     def add_parser_arguments(cls, parser):
+        """Add CLI arguments for this discovery mechanisms.
+
+        :param parser: the CLI parser
+        """
         raise NotImplementedError
 
+    # noinspection PyUnusedLocal
+    def __init__(self, options):
+        """Create a new discovery mechanism.
+
+        :param options: the parsed options as defined within :meth:`add_parser_arguments`
+        """
+        self._has_run = False
+        self._interpreter = None
+
     @abstractmethod
     def run(self):
+        """Discovers an interpreter.
+
+
+        :return: the interpreter ready to use for virtual environment creation
+        """
         raise NotImplementedError
 
     @property
     def interpreter(self):
+        """
+        :return: the interpreter as returned by :meth:`run`, cached
+        """
         if self._has_run is False:
             self._interpreter = self.run()
             self._has_run = True