From 0582979db5d7fc965cd12a05e3e6155a2d2a06a8 Mon Sep 17 00:00:00 2001
From: Dave Halter <davidhalter88@gmail.com>
Date: Thu, 17 Apr 2014 14:13:47 +0200
Subject: [PATCH] documentation to docstring, #395

---
 jedi/api/classes.py               | 39 +++++++++++++++----------------
 test/test_api/test_api_classes.py |  6 ++---
 2 files changed, 22 insertions(+), 23 deletions(-)

diff --git a/jedi/api/classes.py b/jedi/api/classes.py
index cf4326cd..b4e86a6d 100644
--- a/jedi/api/classes.py
+++ b/jedi/api/classes.py
@@ -204,7 +204,7 @@ class BaseDefinition(object):
             return None
         return self._start_pos[1]
 
-    def documentation(self):
+    def docstring(self, raw=False):
         r"""
         Return a document string for this completion object.
 
@@ -216,7 +216,7 @@ class BaseDefinition(object):
         ...     "Document for function f."
         ... '''
         >>> script = Script(source, 1, len('def f'), 'example.py')
-        >>> doc = script.goto_definitions()[0].documentation()
+        >>> doc = script.goto_definitions()[0].docstring()
         >>> print(doc)
         f(a, b = 1)
         <BLANKLINE>
@@ -224,35 +224,36 @@ class BaseDefinition(object):
 
         Notice that useful extra information is added to the actual
         docstring.  For function, it is call signature.  If you need
-        actual docstring, use :attr:`raw` instead.
+        actual docstring, use ``raw=True`` instead.
 
-        >>> print(doc.raw())
+        >>> print(script.goto_definitions()[0].docstring(raw=True))
         Document for function f.
 
         """
-        return Help(self._definition)
+        if raw:
+            return Help(self._definition).raw()
+        else:
+            return Help(self._definition).full()
 
     @property
     def doc(self):
         """
         .. deprecated:: 0.8.0
-           Use :meth:`.documentation` instead.
+           Use :meth:`.docstring` instead.
         .. todo:: Remove!
         """
         warnings.warn("Use documentation() instead.", DeprecationWarning)
-        return self.documentation()
+        return self.docstring()
 
     @property
     def raw_doc(self):
         """
         .. deprecated:: 0.8.0
-           Use :meth:`.documentation` instead.
+           Use :meth:`.docstring` instead.
         .. todo:: Remove!
         """
-        try:
-            return self._definition.raw_doc
-        except AttributeError:
-            return ''
+        warnings.warn("Use documentation() instead.", DeprecationWarning)
+        return self.docstring(raw=True)
 
     @property
     def description(self):
@@ -451,7 +452,7 @@ class Completion(BaseDefinition):
     def __repr__(self):
         return '<%s: %s>' % (type(self).__name__, self._name)
 
-    def documentation(self, fast=True):
+    def docstring(self, raw=False, fast=True):
         """
         :param fast: Don't follow imports that are only one level deep like
             ``import foo``, but follow ``from foo import bar``. This makes
@@ -467,7 +468,11 @@ class Completion(BaseDefinition):
                 if followed:
                     # TODO: Use all of the followed objects as input to Documentation.
                     definition = followed[0]
-        return Help(definition)
+
+        if raw:
+            return Help(definition).raw()
+        else:
+            return Help(definition).full()
 
     @property
     def type(self):
@@ -712,12 +717,6 @@ class Help(object):
     def __init__(self, definition):
         self._definition = definition
 
-    def __str__(self):
-        return self.full()
-
-    def __unicode__(self):
-        return self.full()
-
     def full(self):
         try:
             return self._definition.doc
diff --git a/test/test_api/test_api_classes.py b/test/test_api/test_api_classes.py
index 3f90db21..4ec87d0d 100644
--- a/test/test_api/test_api_classes.py
+++ b/test/test_api/test_api_classes.py
@@ -116,15 +116,15 @@ def test_position_none_if_builtin():
 
 
 @cwd_at('.')
-def test_completion_documentation():
+def test_completion_docstring():
     """
     Jedi should follow imports in certain conditions
     """
     c = Script('import jedi\njed').completions()[0]
-    assert str(c.documentation(fast=False)) == cleandoc(jedi_doc)
+    assert c.docstring(fast=False) == cleandoc(jedi_doc)
 
     c = Script('import jedi\njedi.Scr').completions()[0]
-    assert c.documentation(fast=False).raw() == cleandoc(Script.__doc__)
+    assert c.docstring(raw=True, fast=False) == cleandoc(Script.__doc__)
 
 
 def test_signature_params():