parser: add a description property to docstrings

Adds the ability to access the full description of a parsed docstring.
This is the short description, an optional newline, and the long
description added together.

docstring_parser/common.py

@@ -161,6 +161,25 @@ def __init__(
         self.meta = []  # type: T.List[DocstringMeta]
         self.style = style  # type: T.Optional[DocstringStyle]
 
+    @property
+    def description(self) -> T.Optional[str]:
+        """Return the full description of the function
+
+        Returns None if the docstring did not include any description
+        """
+        ret = []
+        if self.short_description:
+            ret.append(self.short_description)
+            if self.blank_after_short_description:
+                ret.append("")
+        if self.long_description:
+            ret.append(self.long_description)
+
+        if not ret:
+            return None
+
+        return "\n".join(ret)
+
     @property
     def params(self) -> T.List[DocstringParam]:
         """Return a list of information on function params."""

docstring_parser/tests/test_parse_from_object.py

@@ -37,6 +37,7 @@ class StandardCase:
 
     assert docstring.short_description == "Short description"
     assert docstring.long_description == "Long description"
+    assert docstring.description == "Short description\nLong description"
     assert len(docstring.params) == 2
     assert docstring.params[0].arg_name == "attr_one"
     assert docstring.params[0].type_name == "str"
@@ -57,6 +58,7 @@ class WithoutType:  # pylint: disable=missing-class-docstring
 
     assert docstring.short_description is None
     assert docstring.long_description is None
+    assert docstring.description is None
     assert len(docstring.params) == 1
     assert docstring.params[0].arg_name == "attr_one"
     assert docstring.params[0].type_name is None
@@ -78,6 +80,8 @@ class WithoutSource:
         docstring = parse_from_object(WithoutSource)
 
     assert docstring.short_description == "Short description"
+    assert docstring.long_description is None
+    assert docstring.description == "Short description"
     assert len(docstring.params) == 0
 
 
@@ -95,6 +99,7 @@ def a_function(param1: str, param2: int = 2):
     docstring = parse_from_object(a_function)
 
     assert docstring.short_description == "Short description"
+    assert docstring.description == "Short description"
     assert len(docstring.params) == 2
     assert docstring.params[0].arg_name == "param1"
     assert docstring.params[0].type_name is None

docstring_parser/tests/test_parser.py

@@ -31,6 +31,12 @@ def test_rest() -> None:
         "Causing people to indent:\n\n"
         "    A lot sometimes"
     )
+    assert docstring.description == (
+        "Short description\n\n"
+        "Long description\n\n"
+        "Causing people to indent:\n\n"
+        "    A lot sometimes"
+    )
     assert len(docstring.params) == 3
     assert docstring.params[0].arg_name == "spam"
     assert docstring.params[0].type_name is None
@@ -83,6 +89,12 @@ def test_google() -> None:
         "Causing people to indent:\n\n"
         "    A lot sometimes"
     )
+    assert docstring.description == (
+        "Short description\n\n"
+        "Long description\n\n"
+        "Causing people to indent:\n\n"
+        "    A lot sometimes"
+    )
     assert len(docstring.params) == 3
     assert docstring.params[0].arg_name == "spam"
     assert docstring.params[0].type_name is None
@@ -157,6 +169,12 @@ def test_numpydoc() -> None:
         "Causing people to indent:\n\n"
         "    A lot sometimes"
     )
+    assert docstring.description == (
+        "Short description\n\n"
+        "Long description\n\n"
+        "Causing people to indent:\n\n"
+        "    A lot sometimes"
+    )
     assert len(docstring.params) == 4
     assert docstring.params[0].arg_name == "spam"
     assert docstring.params[0].type_name is None

docstring_parser/tests/test_rest.py

@@ -20,6 +20,7 @@ def test_short_description(source: str, expected: str) -> None:
     """Test parsing short description."""
     docstring = parse(source)
     assert docstring.short_description == expected
+    assert docstring.description == expected
     assert docstring.long_description is None
     assert not docstring.meta
 
@@ -103,7 +104,8 @@ def test_long_description(
 
 @pytest.mark.parametrize(
     "source, expected_short_desc, expected_long_desc, "
-    "expected_blank_short_desc, expected_blank_long_desc",
+    "expected_blank_short_desc, expected_blank_long_desc, "
+    "expected_full_desc",
     [
         (
             """
@@ -114,6 +116,7 @@ def test_long_description(
             None,
             False,
             False,
+            "Short description",
         ),
         (
             """
@@ -125,6 +128,7 @@ def test_long_description(
             "Long description",
             False,
             False,
+            "Short description\nLong description",
         ),
         (
             """
@@ -137,6 +141,7 @@ def test_long_description(
             "First line\n    Second line",
             False,
             False,
+            "Short description\nFirst line\n    Second line",
         ),
         (
             """
@@ -150,6 +155,7 @@ def test_long_description(
             "First line\n    Second line",
             True,
             False,
+            "Short description\n\nFirst line\n    Second line",
         ),
         (
             """
@@ -164,6 +170,7 @@ def test_long_description(
             "First line\n    Second line",
             True,
             True,
+            "Short description\n\nFirst line\n    Second line",
         ),
         (
             """
@@ -173,6 +180,7 @@ def test_long_description(
             None,
             False,
             False,
+            None,
         ),
     ],
 )
@@ -182,13 +190,15 @@ def test_meta_newlines(
     expected_long_desc: T.Optional[str],
     expected_blank_short_desc: bool,
     expected_blank_long_desc: bool,
+    expected_full_desc: T.Optional[str],
 ) -> None:
     """Test parsing newlines around description sections."""
     docstring = parse(source)
     assert docstring.short_description == expected_short_desc
     assert docstring.long_description == expected_long_desc
     assert docstring.blank_after_short_description == expected_blank_short_desc
     assert docstring.blank_after_long_description == expected_blank_long_desc
+    assert docstring.description == expected_full_desc
     assert len(docstring.meta) == 1