More docstrings.

docs/docs/usage.rst

@@ -4,8 +4,8 @@ Usage
 =====
 
 |parso| works around grammars. You can simply create Python grammars by calling
-``load_grammar``. Grammars (with a custom tokenizer and custom parser trees)
-can also be created by directly instantiating ``Grammar``. More information
+:py:func:`parso.load_grammar`. Grammars (with a custom tokenizer and custom parser trees)
+can also be created by directly instantiating :py:func:`parso.Grammar`. More information
 about the resulting objects can be found in the :ref:`parser tree documentation
 <parser-tree>`.
 
@@ -18,14 +18,21 @@ The simplest way of using parso is without even loading a grammar
    >>> parso.parse('foo + bar')
    <Module: @1-1>
 
+Loading a Grammar
+-----------------
+
 Typically if you want to work with one specific Python version, use:
 
 .. autofunction:: parso.load_grammar
 
+
+Grammar methods
+---------------
+
 You will get back a grammar object that you can use to parse code and find
 issues in it:
 
-.. autoclass:: parso.grammar.Grammar
+.. autoclass:: parso.Grammar
     :members:
     :undoc-members:
 

parso/__init__.py

@@ -29,8 +29,10 @@ __version__ = '0.0.5'
 
 def parse(code=None, **kwargs):
     """
-    A utility function to parse Python with the current Python version. Params
-    are documented in ``Grammar.parse``.
+    A utility function to avoid loading grammars.
+    Params are documented in :py:meth:`parso.Grammar.parse`
+
+    :param string version: The version used by :py:func:`parso.Grammar.load_grammar`.
     """
     version = kwargs.pop('version', None)
     grammar = load_grammar(version=version)

parso/utils.py

@@ -11,7 +11,7 @@ Version = namedtuple('Version', 'major, minor, micro')
 
 def split_lines(string, keepends=False):
     r"""
-    A str.splitlines for Python code. In contrast to Python's ``str.splitlines``,
+    Intended for Python code. In contrast to Python's :py:meth:`str.splitlines`,
     looks at form feeds and other special characters as normal text. Just
     splits ``\n`` and ``\r\n``.
     Also different: Returns ``['']`` for an empty string input.
@@ -48,9 +48,14 @@ def split_lines(string, keepends=False):
         return re.split('\n|\r\n', string)
 
 
-def python_bytes_to_unicode(source, default_encoding='utf-8', errors='strict'):
+def python_bytes_to_unicode(source, encoding='utf-8', errors='strict'):
     """
-    `errors` can be 'strict', 'replace' or 'ignore'.
+    Checks for unicode BOMs and PEP 263 encoding declarations. Then returns a
+    unicode object like in :py:meth:`str.decode`.
+
+    :param encoding: See :py:meth:`str.decode` documentation.
+    :param errors: See :py:meth:`str.decode` documentation. ``errors`` can be
+        ``'strict'``, ``'replace'`` or ``'ignore'``.
     """
     def detect_encoding():
         """
@@ -70,7 +75,7 @@ def python_bytes_to_unicode(source, default_encoding='utf-8', errors='strict'):
             return possible_encoding.group(1)
         else:
             # the default if nothing else has been set -> PEP 263
-            return default_encoding
+            return encoding
 
     if isinstance(source, unicode):
         # only cast str/bytes