Better examples

docs/docs/api.rst

@@ -126,11 +126,12 @@ References:
     >>> rns = script.get_references(5, 8)
     >>> rns
     [<Definition full_name='__main__.x', description='x = 3'>,
-     <Definition full_name='__main__.x', description='x'>]
+     <Definition full_name='__main__.x', description='x = 4'>,
+     <Definition full_name='__main__.x', description='del x'>]
     >>> rns[1].line
-    5
-    >>> rns[0].column
-    8
+    3
+    >>> rns[1].column
+    4
 
 Deprecations
 ------------
@@ -138,5 +139,5 @@ Deprecations
 The deprecation process is as follows:
 
 1. A deprecation is announced in the next major/minor release.
-2. We wait either at least a year & at least two minor releases until we remove
-   the deprecated functionality.
+2. We wait either at least a year and at least two minor releases until we
+   remove the deprecated functionality.

jedi/api/__init__.py

@@ -661,6 +661,8 @@ class Interpreter(Script):
     """
     Jedi API for Python REPLs.
 
+    Implements all of the methods that are present in :class:`.Script` as well.
+
     In addition to completion of simple attribute access, Jedi
     supports code completion based on static code analysis.
     Jedi can complete attributes of object which is not initialized
@@ -676,17 +678,15 @@ class Interpreter(Script):
 
     def __init__(self, source, namespaces, **kwds):
         """
-        Parse `source` and mixin interpreted Python objects from `namespaces`.
+        Parse ``source`` and mixin interpreted Python objects from ``namespaces``.
 
         :type source: str
         :arg  source: Code to parse.
         :type namespaces: list of dict
         :arg  namespaces: a list of namespace dictionaries such as the one
-                          returned by :func:`locals`.
+                          returned by :func:`globals`.
 
-        Other optional arguments are same as the ones for :class:`Script`.
-        If `line` and `column` are None, they are assumed be at the end of
-        `source`.
+        Other optional arguments are same as the ones for :class:`.Script`.
         """
         try:
             namespaces = [dict(n) for n in namespaces]