Improved documentation.

4 files changed, 62 insertions, 35 deletions

diff --git a/prompt_toolkit/buffer.py b/prompt_toolkit/buffer.py
index 3c5a68bd..305044fc 100644
--- a/prompt_toolkit/buffer.py
+++ b/prompt_toolkit/buffer.py
@@ -134,7 +134,7 @@ class Buffer(object):
     current input line and implements all text manipulations on top of it. It
     also implements the history, undo stack and the completion state.
 
-    :param eventloop: :class:`~prompt_toolkit.eventloop.base.EventLoop` instance.
+    :param eventloop: :class:`~prompt_toolkit.eventloop.EventLoop` instance.
     :param completer: :class:`~prompt_toolkit.completion.Completer` instance.
     :param history: :class:`~prompt_toolkit.history.History` instance.
     :param get_tempfile_suffix: Callable that returns the tempfile suffix to be
@@ -157,20 +157,22 @@ class Buffer(object):
     Filters:
 
     :param complete_while_typing: :class:`~prompt_toolkit.filters.Filter`
-        instance. Decide whether or not to do asynchronous autocompleting while
+        or `bool`. Decide whether or not to do asynchronous autocompleting while
         typing.
     :param validate_while_typing: :class:`~prompt_toolkit.filters.Filter`
-        instance. Decide whether or not to do asynchronous validation while
+        or `bool`. Decide whether or not to do asynchronous validation while
         typing.
-    :param enable_history_search: :class:`~prompt_toolkit.filters.Filter`
-        to indicate when up-arrow partial string matching is enabled. It is
-        advised to not enable this at the same time as `complete_while_typing`,
-        because when there is an autocompletion found, the up arrows usually
-        browse through the completions, rather than through the history.
+    :param enable_history_search: :class:`~prompt_toolkit.filters.Filter` or
+        `bool` to indicate when up-arrow partial string matching is enabled. It
+        is advised to not enable this at the same time as
+        `complete_while_typing`, because when there is an autocompletion found,
+        the up arrows usually browse through the completions, rather than
+        through the history.
     :param read_only: :class:`~prompt_toolkit.filters.Filter`. When True,
         changes will not be allowed.
-    :param multiline: When not set, pressing `Enter` will call the `accept_handler`.
-        Otherwise, pressing `Esc-Enter` is required.
+    :param multiline: :class:`~prompt_toolkit.filters.Filter` or `bool`. When
+        not set, pressing `Enter` will call the `accept_handler`.  Otherwise,
+        pressing `Esc-Enter` is required.
     """
     def __init__(self, completer=None, auto_suggest=None, history=None,
                  validator=None, get_tempfile_suffix=None, tempfile_suffix='',
diff --git a/prompt_toolkit/shortcuts/progress_bar/base.py b/prompt_toolkit/shortcuts/progress_bar/base.py
index f65fb3d9..b111396d 100644
--- a/prompt_toolkit/shortcuts/progress_bar/base.py
+++ b/prompt_toolkit/shortcuts/progress_bar/base.py
@@ -32,7 +32,7 @@ import time
 import traceback
 import sys
 
-from . import formatters as f
+from .formatters import create_default_formatters, Formatter
 
 __all__ = [
     'progress_bar',
@@ -58,23 +58,6 @@ def create_key_bindings():
     return kb
 
 
-def create_default_formatters():
-    return [
-        f.Label(),
-        f.Text(' '),
-        f.Percentage(),
-        f.Text(' '),
-        f.Bar(),
-        f.Text(' '),
-        f.Progress(),
-        f.Text(' '),
-        f.Text('eta [', style='class:time-left'),
-        f.TimeLeft(),
-        f.Text(']', style='class:time-left'),
-        f.Text(' '),
-    ]
-
-
 class progress_bar(object):
     """
     Progress bar context manager.
@@ -90,19 +73,19 @@ class progress_bar(object):
     :param formatters: List of `Formatter` instances.
     :param bottom_toolbar: Text to be displayed in the bottom toolbar.
         This can be a callable or formatted text.
-    :param style: `prompt_toolkit` ``Style`` instance.
-    :param key_bindings: `KeyBindings` instance.
+    :param style: :class:`prompt_toolkit.styles.BaseStyle` instance.
+    :param key_bindings: :class:`.KeyBindings` instance.
     :param file: The file object used for rendering, by default `sys.stderr` is used.
 
     :param color_depth: `prompt_toolkit` `ColorDepth` instance.
-    :param output: `prompt_toolkit` `Output` instance.
-    :param input: `prompt_toolkit` `Input` instance.
+    :param output: :class:`~prompt_toolkit.output.Output` instance.
+    :param input: :class:`~prompt_toolkit.input.Input` instance.
     """
     def __init__(self, title=None, formatters=None, bottom_toolbar=None,
                  style=None, key_bindings=None, file=None, color_depth=None,
                  output=None, input=None):
         assert formatters is None or (
-            isinstance(formatters, list) and all(isinstance(fo, f.Formatter) for fo in formatters))
+            isinstance(formatters, list) and all(isinstance(fo, Formatter) for fo in formatters))
         assert style is None or isinstance(style, BaseStyle)
         assert key_bindings is None or isinstance(key_bindings, KeyBindings)
 
diff --git a/prompt_toolkit/shortcuts/progress_bar/formatters.py b/prompt_toolkit/shortcuts/progress_bar/formatters.py
index 8cd2bb2a..e3d5ecb4 100644
--- a/prompt_toolkit/shortcuts/progress_bar/formatters.py
+++ b/prompt_toolkit/shortcuts/progress_bar/formatters.py
@@ -25,6 +25,7 @@ __all__ = [
     'IterationsPerSecond',
     'SpinningWheel',
     'Rainbow',
+    'create_default_formatters',
 ]
 
 
@@ -101,6 +102,9 @@ class Label(Formatter):
 
 
 class Percentage(Formatter):
+    """
+    Display the progress as a percentage.
+    """
     template = '<percentage>{percentage:>5}%</percentage>'
 
     def format(self, progress_bar, progress, width):
@@ -112,6 +116,9 @@ class Percentage(Formatter):
 
 
 class Bar(Formatter):
+    """
+    Display the progress bar itself.
+    """
     template = '<bar>{start}<bar-a>{bar_a}</bar-a><bar-b>{bar_b}</bar-b><bar-c>{bar_c}</bar-c>{end}</bar>'
 
     def __init__(self, start='[', end=']', sym_a='=', sym_b='>', sym_c=' ', unknown='#'):
@@ -153,6 +160,9 @@ class Bar(Formatter):
 
 
 class Progress(Formatter):
+    """
+    Display the progress as text.  E.g. "8/20"
+    """
     template = '<current>{current:>3}</current>/<total>{total:>3}</total>'
 
     def format(self, progress_bar, progress, width):
@@ -177,6 +187,9 @@ def _format_timedelta(timedelta):
 
 
 class TimeElapsed(Formatter):
+    """
+    Display the elapsed time.
+    """
     def format(self, progress_bar, progress, width):
         text = _format_timedelta(progress.time_elapsed).rjust(width)
         return HTML('<time-elapsed>{time_elapsed}</time-elapsed>').format(time_elapsed=text)
@@ -189,6 +202,9 @@ class TimeElapsed(Formatter):
 
 
 class TimeLeft(Formatter):
+    """
+    Display the time left.
+    """
     template = '<time-left>{time_left}</time-left>'
     unknown = '?:??:??'
 
@@ -209,6 +225,9 @@ class TimeLeft(Formatter):
 
 
 class IterationsPerSecond(Formatter):
+    """
+    Display the iterations per second.
+    """
     template = '<iterations-per-second>{iterations_per_second:.2f}</iterations-per-second>'
 
     def format(self, progress_bar, progress, width):
@@ -224,6 +243,9 @@ class IterationsPerSecond(Formatter):
 
 
 class SpinningWheel(Formatter):
+    """
+    Display a spinning wheel.
+    """
     characters = r'/-\|'
 
     def format(self, progress_bar, progress, width):
@@ -279,3 +301,23 @@ class Rainbow(Formatter):
 
     def get_width(self, progress_bar):
         return self.formatter.get_width(progress_bar)
+
+
+def create_default_formatters():
+    """
+    Return the list of default formatters.
+    """
+    return [
+        Label(),
+        Text(' '),
+        Percentage(),
+        Text(' '),
+        Bar(),
+        Text(' '),
+        Progress(),
+        Text(' '),
+        Text('eta [', style='class:time-left'),
+        TimeLeft(),
+        Text(']', style='class:time-left'),
+        Text(' '),
+    ]
diff --git a/prompt_toolkit/shortcuts/prompt.py b/prompt_toolkit/shortcuts/prompt.py
index cc80aa31..5734e09a 100644
--- a/prompt_toolkit/shortcuts/prompt.py
+++ b/prompt_toolkit/shortcuts/prompt.py
@@ -169,8 +169,8 @@ class PromptSession(object):
         string matching.
     :param search_ignore_case:
         :class:`~prompt_toolkit.filters.Filter`. Search case insensitive.
-    :param lexer: :class:`~prompt_toolkit.layout.lexers.Lexer` to be used for
-        the syntax highlighting.
+    :param lexer: :class:`~prompt_toolkit.lexers.Lexer` to be used for the
+        syntax highlighting.
     :param validator: :class:`~prompt_toolkit.validation.Validator` instance
         for input validation.
     :param completer: :class:`~prompt_toolkit.completion.Completer` instance