Improved API documentation

docs/source/conf.py

@@ -26,7 +26,7 @@ sys.path.insert(0, os.path.abspath('../../jedi'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -241,3 +241,7 @@ texinfo_documents = [
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
+
+# -- Options for todo module ---------------------------------------------------
+
+todo_include_todos = False

jedi/api.py

@@ -45,7 +45,7 @@ from _compatibility import next, unicode
 
 
 class NotFoundError(Exception):
-    """ A custom error to avoid catching the wrong exceptions """
+    """A custom error to avoid catching the wrong exceptions."""
     pass
 
 
@@ -78,7 +78,7 @@ class Script(object):
 
     @property
     def parser(self):
-        """ The lazy parser """
+        """ The lazy parser."""
         return self.module.parser
 
     def complete(self):
@@ -210,7 +210,7 @@ class Script(object):
         """
         Return the definitions of a the path under the cursor. This is not a
         goto function! This follows complicated paths and returns the end, not
-        the first definition. The big difference of :meth:`goto` and
+        the first definition. The big difference between :meth:`goto` and
         :meth:`get_definition` is that :meth:`goto` doesn't follow imports and
         statements. Multiple objects may be returned, because Python itself is
         a dynamic language, which means depending on an option you can have two
@@ -311,7 +311,7 @@ class Script(object):
         is very useful for refactoring (renaming), or to show all usages of a
         variable.
 
-        TODO implement additional_module_paths
+        .. todo:: Implement additional_module_paths
         """
         user_stmt = self.parser.user_stmt
         definitions, search_name = self._goto(add_import_name=True)
@@ -340,13 +340,17 @@ class Script(object):
 
     def get_in_function_call(self):
         """
-        Return the function, that the cursor is in, e.g.:
-        >>> isinstance(| # | <-- cursor is here
+        Return the function object of the call you're currently in.
         
-        This would return the `isinstance` function. In contrary:
-        >>> isinstance()| # | <-- cursor is here
+        E.g. if the cursor is here::
 
-        This would return `None`.
+            >>> abs(# <-- cursor is here
+
+        This would return the ``abs`` function. On the other hand::
+
+            >>> abs()# <-- cursor is here
+
+        This would return ``None``.
         """
         def check_user_stmt(user_stmt):
             if user_stmt is None \

jedi/api_classes.py

@@ -135,8 +135,10 @@ class BaseDefinition(object):
 
 
 class Completion(BaseDefinition):
-    """ `Completion` objects are returned from `Script.complete`. Providing
-    some useful functions for IDE's. """
+    """
+    `Completion` objects are returned from :meth:`api.Script.complete`. They
+    provide additional information about a completion.
+    """
     def __init__(self, name, needs_dot, like_name_length, base):
         super(Completion, self).__init__(name.parent, name.start_pos)
 
@@ -149,11 +151,13 @@ class Completion(BaseDefinition):
 
     @property
     def complete(self):
-        """ Delievers the rest of the word, e.g. completing `isinstance`
-        >>> isinstan
+        """
+        Return the rest of the word, e.g. completing ``isinstance``::
+
+            >>> isinstan# <-- Cursor is here
 
         would return the string 'ce'. It also adds additional stuff, depending
-        on your `settings.py`
+        on your `settings.py`.
         """
         dot = '.' if self.needs_dot else ''
         append = ''
@@ -170,7 +174,9 @@ class Completion(BaseDefinition):
 
     @property
     def word(self):
-        """ In contrary to `complete` returns the whole word, e.g.
+        """
+        Similar to :meth:`Completion.complete`, but return the whole word, e.g. ::
+
             >>> isinstan
 
         would return 'isinstance'.
@@ -179,8 +185,11 @@ class Completion(BaseDefinition):
 
     @property
     def description(self):
-        """ Provides a description of the completion object
-        TODO return value is just __repr__ of some objects, improve! """
+        """
+        Provide a description of the completion object.
+
+        .. todo:: return value is just __repr__ of some objects, improve!
+        """
         parent = self.name.parent
         if parent is None:
             return ''
@@ -194,12 +203,13 @@ class Completion(BaseDefinition):
         return '%s: %s%s' % (t, desc, line_nr)
 
     def follow_definition(self):
-        """ Returns you the original definitions. I strongly recommend not
-        using it for your completions, because it might slow down Jedi. If you
-        want to read only a few objects (<=20). I think it might be useful,
-        especially to get the original docstrings.
-        The basic problem of this function is that it follows all results. This
-        means with 1000 completions (e.g. numpy), it's just PITA slow.
+        """
+        Return the original definitions. I strongly recommend not using it for
+        your completions, because it might slow down *Jedi*. If you want to read
+        only a few objects (<=20), it might be useful, especially to
+        get the original docstrings. The basic problem of this function is
+        that it follows all results. This means with 1000 completions (e.g.
+        numpy), it's just PITA-slow.
         """
         if self._followed_definitions is None:
             if self.definition.isinstance(parsing.Statement):
@@ -220,15 +230,19 @@ class Completion(BaseDefinition):
 
 
 class Definition(BaseDefinition):
-    """ These are the objects returned by either `Script.goto` or
-    `Script.get_definition`. """
+    """
+    *Definition* objects are returned from :meth:`api.Script.goto` or
+    :meth:`api.Script.get_definition`.
+    """
     def __init__(self, definition):
         super(Definition, self).__init__(definition, definition.start_pos)
 
     @property
     def description(self):
-        """ A description of the Definition object, which is heavily used in
-        testing. e.g. for `isinstance` it returns 'def isinstance' """
+        """
+        A description of the :class:`.Definition` object, which is heavily used
+        in testing. e.g. for ``isinstance`` it returns ``def isinstance``.
+        """
         d = self.definition
         if isinstance(d, evaluate.InstanceElement):
             d = d.var
@@ -252,10 +266,15 @@ class Definition(BaseDefinition):
 
     @property
     def desc_with_module(self):
-        """ In addition to the Definition, it also returns the module. Don't
-        use it yet, its behaviour may change. If you really need it, talk to me
-        TODO add full path. This function is should return a
-        module.class.function path. """
+        """
+        In addition to the definition, also return the module.
+        
+        .. warning:: Don't use this function yet, its behaviour may change. If
+            you really need it, talk to me.
+
+        .. todo:: Add full path. This function is should return a
+            `module.class.function` path.
+        """
         if self.module_path.endswith('.py') \
                     and not isinstance(self.definition, parsing.Module):
             position = '@%s' % (self.line_nr)