From 88c766afb05c2bb710d84c6cf8fc9a9751e071a6 Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Sat, 14 Mar 2020 15:00:47 +0100
Subject: [PATCH] Better docstrings for search

---
 jedi/__init__.py     |  2 +-
 jedi/api/__init__.py | 26 +++++++++++++++++++++++---
 jedi/api/project.py  | 26 ++++++++++++++++++++++++--
 3 files changed, 48 insertions(+), 6 deletions(-)

diff --git a/jedi/__init__.py b/jedi/__init__.py
index 309ac3e8..f361cf46 100644
--- a/jedi/__init__.py
+++ b/jedi/__init__.py
@@ -33,7 +33,7 @@ As you see Jedi is pretty simple and allows you to concentrate on writing a
 good text editor, while still having very good IDE features for Python.
 """
 
-__version__ = '0.16.1'
+__version__ = '0.17.0'
 
 from jedi.api import Script, Interpreter, set_debug_function, \
     preload_module, names
diff --git a/jedi/api/__init__.py b/jedi/api/__init__.py
index cb15abd8..64122f45 100644
--- a/jedi/api/__init__.py
+++ b/jedi/api/__init__.py
@@ -12,6 +12,7 @@ arguments.
 import os
 import sys
 import warnings
+from functools import wraps
 
 import parso
 from parso.python import tree
@@ -54,6 +55,7 @@ sys.setrecursionlimit(3000)
 
 def no_py2_support(func):
     # TODO remove when removing Python 2/3.5
+    @wraps(func)
     def wrapper(self, *args, **kwargs):
         if self._inference_state.grammar.version_info < (3, 6) or sys.version_info < (3, 6):
             raise NotImplementedError(
@@ -339,10 +341,16 @@ class Script(object):
     @no_py2_support
     def search(self, string, **kwargs):
         """
-        Searches a symbol in the current file.
+        Searches a name in the current file. For a description of how the
+        string should look like, please have a look at :meth:`.Project.search`.
 
-        :param all_scopes: If True lists the symbols of all scopes instead of
-            only the module.
+        :param bool fuzzy: Default False; searches not only for
+            definitions on the top level of a module level, but also in
+            functions and classes.
+        :param bool all_scopes: Default False; searches not only for
+            definitions on the top level of a module level, but also in
+            functions and classes.
+        :yields: :class:`.Definition`
         """
         return self._search(string, **kwargs)  # Python 2 ...
 
@@ -364,6 +372,18 @@ class Script(object):
         )
 
     def complete_search(self, string, **kwargs):
+        """
+        Like :meth:`.Script.search`, but returns completions for the current
+        string. If you want to have all possible definitions in a file you can
+        also provide an empty string.
+
+        :param bool all_scopes: Default False; searches not only for
+            definitions on the top level of a module level, but also in
+            functions and classes.
+        :param fuzzy: Default False. Will return fuzzy completions, which means
+            that e.g. ``ooa`` will match ``foobar``.
+        :yields: :class:`.Completion`
+        """
         return self._search_func(string, complete=True, **kwargs)
 
     @validate_line_column
diff --git a/jedi/api/project.py b/jedi/api/project.py
index f8fbd8f4..279c554b 100644
--- a/jedi/api/project.py
+++ b/jedi/api/project.py
@@ -199,14 +199,36 @@ class Project(object):
 
     def search(self, string, **kwargs):
         """
-        Returns a generator of names
+        Tries to look in a whole project for names. If the project is very big,
+        at some point Jedi will stop searching. However it's also very much
+        recommended to not exhaust the generator. Just display the first ten
+        results to the user.
+
+        There are currently three different search patterns:
+
+        - ``foo`` to search for a definition foo in any file or a file called
+          ``foo.py`` or ``foo.pyi``.
+        - ``foo.bar`` to search for the ``foo`` and then an attribute ``bar``
+          in it.
+        - ``class foo.bar.Bar`` or ``def foo.bar.baz`` to search for a specific
+          API type.
+
+        :param bool all_scopes: Default False; searches not only for
+            definitions on the top level of a module level, but also in
+            functions and classes.
+        :yields: :class:`.Definition`
         """
         return self._search(string, **kwargs)
 
     def complete_search(self, string, **kwargs):
         """
-        XXX
+        Like :meth:`.Project.search`, but returns completions for the current
+        string. An empty string lists all definitions in a project, so be
+        careful with that.
 
+        :param bool all_scopes: Default False; searches not only for
+            definitions on the top level of a module level, but also in
+            functions and classes.
         :yields: :class:`.Completion`
         """
         return self._search_func(string, complete=True, **kwargs)