add a Documentation() class to the API, which will be used in the future for all kind of docstrings. Also add a documentation method on BaseDefinition that returns a Documentation object. Deprecate at the same time its doc and raw_doc functions

jedi/api/classes.py

@@ -202,8 +202,7 @@ class BaseDefinition(object):
             return None
         return self._start_pos[1]
 
-    @property
-    def doc(self):
+    def documentation(self):
         r"""
         Return a document string for this completion object.
 
@@ -215,31 +214,38 @@ class BaseDefinition(object):
         ...     "Document for function f."
         ... '''
         >>> script = Script(source, 1, len('def f'), 'example.py')
-        >>> d = script.goto_definitions()[0]
-        >>> print(d.doc)
+        >>> doc = script.goto_definitions()[0].documentation()
+        >>> print(doc)
         f(a, b = 1)
         <BLANKLINE>
         Document for function f.
 
         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_doc` instead.
+        actual docstring, use :attr:`raw` instead.
 
-        >>> print(d.raw_doc)
+        >>> print(doc.raw())
         Document for function f.
 
         """
-        try:
-            return self._definition.doc
-        except AttributeError:
-            return self.raw_doc
+        return Documentation(self._definition)
+
+    @property
+    def doc(self):
+        """
+        .. deprecated:: 0.8.0
+           Use :meth:`.documentation` instead.
+        .. todo:: Remove!
+        """
+        warnings.warn("Use documentation() instead.", DeprecationWarning)
+        return self.documentation()
 
     @property
     def raw_doc(self):
         """
-        The raw docstring ``__doc__`` for any object.
-
-        See :attr:`doc` for example.
+        .. deprecated:: 0.8.0
+           Use :meth:`.documentation` instead.
+        .. todo:: Remove!
         """
         try:
             return self._definition.raw_doc
@@ -637,3 +643,25 @@ class _Param(Definition):
         """
         warnings.warn("Use description instead.", DeprecationWarning)
         return self.description
+
+
+class Documentation(object):
+    def __init__(self, definition):
+        self._definition = definition
+
+    def __str__(self):
+        try:
+            return self._definition.doc
+        except AttributeError:
+            return self.raw_doc
+
+    def raw(self):
+        """
+        The raw docstring ``__doc__`` for any object.
+
+        See :attr:`doc` for example.
+        """
+        try:
+            return self._definition.raw_doc
+        except AttributeError:
+            return ''

test/test_api/test_api_classes.py

@@ -93,7 +93,7 @@ def test_function_call_signature_in_doc():
         pass
     f""").goto_definitions()
     doc = defs[0].doc
-    assert "f(x, y = 1, z = 'a')" in doc
+    assert "f(x, y = 1, z = 'a')" in str(doc)
 
 
 def test_class_call_signature():
@@ -103,7 +103,7 @@ def test_class_call_signature():
             pass
     Foo""").goto_definitions()
     doc = defs[0].doc
-    assert "Foo(self, x, y = 1, z = 'a')" in doc
+    assert "Foo(self, x, y = 1, z = 'a')" in str(doc)
 
 
 def test_position_none_if_builtin():

test/test_api/test_call_signatures.py

@@ -193,7 +193,7 @@ def test_signature_is_definition():
 
     # Now compare all the attributes that a CallSignature must also have.
     for attr_name in dir(definition):
-        dont_scan = ['defined_names', 'line_nr', 'start_pos']
+        dont_scan = ['defined_names', 'line_nr', 'start_pos', 'documentation', 'doc']
         if attr_name.startswith('_') or attr_name in dont_scan:
             continue
         attribute = getattr(definition, attr_name)