fix: warn about missing descriptions and return "" not None

src/pytkdocs/parsers/docstrings/numpy.py

@@ -89,11 +89,16 @@ def read_parameters_section(
                 if signature_param.default is not empty:
                     default = signature_param.default
                 kind = signature_param.kind
+
+            description = param.description if param.description else ""
+            if not description:
+                self.error(f"No description for parameter '{name}'")
+
             parameters.append(
                 Parameter(
                     name=param.arg_name,
                     annotation=type_name,
-                    description=param.description,
+                    description=description,
                     default=default,
                     kind=kind,
                 )
@@ -124,6 +129,9 @@ def read_attributes_section(
         docstring_attributes = [p for p in docstring_obj.params if p.args[0] == "attribute"]
 
         for attr in docstring_attributes:
+            description = attr.description if attr.description else ""
+            if not description:
+                self.error(f"No description for attribute '{attr.arg_name}'")
             attributes.append(
                 Attribute(
                     name=attr.arg_name,
@@ -157,6 +165,9 @@ def read_exceptions_section(
         except_obj = docstring_obj.raises
 
         for exception in except_obj:
+            description = exception.description if exception.description else ""
+            if not description:
+                self.error(f"No description for exception '{exception.type_name}'")
             exceptions.append(AnnotatedObject(exception.type_name, exception.description))
 
         if exceptions:
@@ -178,26 +189,31 @@ def read_return_section(
         Returns:
             A `Section` object (or `None` if section is empty).
         """
-        return_obj = docstring_obj.returns if docstring_obj.returns else []
-        text = return_obj.description if return_obj else ""
-
-        if self.context["signature"]:
-            annotation = self.context["signature"].return_annotation
-        else:
-            annotation = self.context["annotation"]
-
-        if annotation is empty:
-            if text:
-                annotation = return_obj.type_name or empty
-                text = return_obj.description
-            elif return_obj and annotation is empty:
+        if docstring_obj.returns:
+            return_obj =  docstring_obj.returns
+
+            if return_obj.description:
+                description = return_obj.description
+            else: 
+                self.error("Empty return description")
+                description = ""
+
+            if self.context["signature"]:
+                annotation = self.context["signature"].return_annotation
+            else:
+                annotation = self.context["annotation"]
+
+            if annotation is empty and return_obj.type_name:
+                annotation = return_obj.type_name
+
+            if not annotation:
                 self.error("No return type annotation")
+                annotation = ""
 
-        if return_obj and not text:
-            self.error("Empty return description")
-        if not return_obj or annotation is empty or not text:
-            return None
-        return Section(Section.Type.RETURN, AnnotatedObject(annotation, text))
+            if annotation or description:
+                return Section(Section.Type.RETURN, AnnotatedObject(annotation, description))
+
+        return None
 
     def read_examples_section(
         self,

tests/test_parsers/test_docstrings/test_numpy.py

@@ -81,6 +81,37 @@ def test_sections_without_signature():
         assert "param" in error
 
 
+def test_sections_without_description():
+    """Parse a docstring without descriptions."""
+    # type of return value always required
+    sections, errors = parse(
+        """
+        Sections without descriptions.
+
+        Parameters
+        ----------
+        void : str
+        niet : str
+        nada : str
+        rien : str
+
+        Raises
+        ------
+        GlobalError
+
+        Returns
+        -------
+        bool
+        """
+    )
+    assert len(sections) == 4
+    assert len(errors) == 10
+    for error in errors[:8]:
+        assert "param" in error
+    assert "exception" in errors[8]
+    assert "return description" in errors[9]
+
+
 def test_property_docstring():
     """Parse a property docstring."""
     class_ = Loader().get_object_documentation("tests.fixtures.parsing.docstrings.NotDefinedYet")