Merge pull request #148 from tkf/docstring-improvements

Improve docstrings

jedi/evaluate.py

@@ -87,9 +87,17 @@ import docstrings
 
 def get_defined_names_for_position(scope, position=None, start_scope=None):
     """
-    Deletes all names that are ahead of the position, except for some special
+    Return filtered version of ``scope.get_defined_names()``.
-    objects like instances, where the position doesn't matter.
 
+    This function basically does what :meth:`scope.get_defined_names
+    <parsing_representation.Scope.get_defined_names>` does.
+
+    - If `position` is given, delete all names defined after `position`.
+    - For special objects like instances, `position` is ignored and all
+      names are returned.
+
+    :type     scope: :class:`parsing_representation.IsScope`
+    :param    scope: Scope in which names are searched.
     :param position: the position as a line/column tuple, default is infinity.
     """
     names = scope.get_defined_names()
@@ -112,6 +120,39 @@ def get_names_of_scope(scope, position=None, star_search=True,
     Get all completions (names) possible for the current scope.
     The star search option is only here to provide an optimization. Otherwise
     the whole thing would probably start a little recursive madness.
+
+    This function is used to include names from outer scopes.  For example,
+    when the current scope is function:
+
+    >>> from jedi.parsing import Parser
+    >>> parser = Parser('''
+    ... x = ['a', 'b', 'c']
+    ... def func():
+    ...     y = None
+    ... ''')
+    >>> scope = parser.scope.subscopes[0]
+    >>> scope
+    <Function: func@3-6>
+
+    `get_names_of_scope` is a generator.  First it yields names from
+    most inner scope.
+
+    >>> pairs = list(get_names_of_scope(scope))
+    >>> pairs[0]
+    (<Function: func@3-6>, [<Name: y@4,4>])
+
+    Then it yield the names from one level outer scope.  For this
+    example, this is the most outer scope.
+
+    >>> pairs[1]
+    (<SubModule: None@1-6>, [<Name: x@2,0>, <Name: func@3,4>])
+
+    Finally, it yields names from builtin, if `include_builtin` is
+    true (default).
+
+    >>> pairs[2]                                        #doctest: +ELLIPSIS
+    (<Module: ...builtin...>, [<Name: ...>, ...])
+
     """
     in_func_scope = scope
     non_flow = scope.get_parent_until(pr.Flow, reverse=True)

jedi/parsing_representation.py

@@ -14,6 +14,25 @@ One special thing:
 ``[1, 2+33]`` for example would be an Array with two ``Statement`` inside. This
 is the easiest way to write a parser. The same behaviour applies to ``Param``,
 which is being used in a function definition.
+
+The easiest way to play with this module is to use :class:`parsing.Parser`.
+:attr:`parsing.Parser.scope` holds an instance of :class:`SubModule`:
+
+>>> from jedi.parsing import Parser
+>>> parser = Parser('import os', 'example.py')
+>>> submodule = parser.scope
+>>> submodule
+<SubModule: example.py@1-2>
+
+Any subclasses of :class:`Scope`, including :class:`SubModule` has
+attribute :attr:`imports <Scope.imports>`.  This attribute has import
+statements in this scope.  Check this out:
+
+>>> submodule.imports
+[<Import: import os @1,0>]
+
+See also :attr:`Scope.subscopes` and :attr:`Scope.statements`.
+
 """
 
 import os
@@ -50,6 +69,16 @@ class Simple(Base):
                  '_end_pos')
 
     def __init__(self, module, start_pos, end_pos=(None, None)):
+        """
+        Initialize :class:`Simple`.
+
+        :type      module: :class:`SubModule`
+        :param     module: The module in which this Python object locates.
+        :type   start_pos: 2-tuple of int
+        :param  start_pos: Position (line, column) of the Statement.
+        :type     end_pos: 2-tuple of int
+        :param    end_pos: Same as `start_pos`.
+        """
         self._sub_module = module
         self._start_pos = start_pos
         self._end_pos = end_pos
@@ -183,7 +212,7 @@ class Scope(Simple, IsScope):
     def get_set_vars(self):
         """
         Get all the names, that are active and accessible in the current
-        scope.
+        scope.  See :meth:`get_defined_names` for examples.
 
         :return: list of Name
         :rtype: list
@@ -204,6 +233,26 @@ class Scope(Simple, IsScope):
         return n
 
     def get_defined_names(self):
+        """
+        Get all defined names in this scope.
+
+        >>> from jedi.parsing import Parser
+        >>> parser = Parser('''
+        ... a = x
+        ... b = y
+        ... b.c = z
+        ... ''')
+        >>> parser.scope.get_defined_names()
+        [<Name: a@2,0>, <Name: b@3,0>]
+
+        Note that unlike :meth:`get_set_vars`, assignment to object
+        attribute does not change the result because it does not change
+        the defined names in this scope.
+
+        >>> parser.scope.get_set_vars()
+        [<Name: a@2,0>, <Name: b@3,0>, <Name: b.c@4,0>]
+
+        """
         return [n for n in self.get_set_vars()
                   if isinstance(n, Import) or len(n) == 1]
 
@@ -259,12 +308,22 @@ class Module(IsScope):
 
 
 class SubModule(Scope, Module):
+
     """
     The top scope, which is always a module.
     Depending on the underlying parser this may be a full module or just a part
     of a module.
     """
+
     def __init__(self, path, start_pos=(1, 0), top_module=None):
+        """
+        Initialize :class:`SubModule`.
+
+        :type path: str
+        :arg  path: File path to this module.
+
+        .. todo:: Document `top_module`.
+        """
         super(SubModule, self).__init__(self, start_pos)
         self.path = path
         self.global_vars = []
@@ -577,9 +636,6 @@ class Import(Simple):
     """
     Stores the imports of any Scopes.
 
-    >>> 1+1
-    2
-
     :param start_pos: Position (line, column) of the Import.
     :type start_pos: tuple(int, int)
     :param namespace: The import, can be empty if a star is given
@@ -663,14 +719,18 @@ class Statement(Simple):
     stores pretty much all the Python code, except functions, classes, imports,
     and flow functions like if, for, etc.
 
+    :type    set_vars: list of :class:`Name`
     :param   set_vars: The variables which are defined by the statement.
-    :param set_vars: str
+    :type   used_vars: list of :class:`Name`
     :param  used_vars: The variables which are used by the statement.
-    :param used_vars: str
+    :type  token_list: list
-    :param token_list: Token list which is also peppered with Name.
+    :param token_list:
-    :param token_list: list
+        List of tokens or names.  Each element is either an instance
+        of :class:`Name` or a tuple of token type value (e.g.,
+        :data:`tokenize.NUMBER`), token string (e.g., ``'='``), and
+        start position (e.g., ``(1, 0)``).
+    :type   start_pos: 2-tuple of int
     :param  start_pos: Position (line, column) of the Statement.
-    :type start_pos: tuple(int, int)
     """
     __slots__ = ('token_list', 'used_vars',
                  'set_vars', '_commands', '_assignment_details')
@@ -692,11 +752,11 @@ class Statement(Simple):
 
     def _remove_executions_from_set_vars(self, set_vars):
         """
-        Important mainly for assosiative arrays:
+        Important mainly for assosiative arrays::
 
-        >>> a = 3
+            a = 3
-        >>> b = {}
+            b = {}
-        >>> b[a] = 3
+            b[a] = 3
 
         `a` is in this case not a set_var, it is used to index the dict.
         """