fix: Always return strings (not None) and warn about missing descriptions in numpy parser

Issue #137: #137
PR #138: #138

Author: JoeHCQ1

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 or ""
+            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 or ""
+            if not description:
+                self.error(f"No description for attribute '{attr.arg_name}'")
             attributes.append(
                 Attribute(
                     name=attr.arg_name,
@@ -157,7 +165,10 @@ def read_exceptions_section(
         except_obj = docstring_obj.raises
 
         for exception in except_obj:
-            exceptions.append(AnnotatedObject(exception.type_name, exception.description))
+            description = exception.description or ""
+            if not description:
+                self.error(f"No description for exception '{exception.type_name}'")
+            exceptions.append(AnnotatedObject(exception.type_name, description))
 
         if exceptions:
             return Section(Section.Type.EXCEPTIONS, 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

@@ -4,6 +4,7 @@
 from textwrap import dedent
 
 from pytkdocs.loader import Loader
+from pytkdocs.parsers.docstrings.base import Section
 from pytkdocs.parsers.docstrings.numpy import Numpy
 
 
@@ -81,6 +82,48 @@ 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
+
+        Raises
+        ------
+        GlobalError
+
+        Returns
+        -------
+        bool
+        """
+    )
+    
+    # Assert that errors are as expected
+    assert len(sections) == 4
+    assert len(errors) == 6
+    for error in errors[:4]:
+        assert "param" in error
+    assert "exception" in errors[4]
+    assert "return description" in errors[5]
+    
+    # Assert that no descriptions are ever None (can cause exceptions downstream)
+    assert sections[1].type is Section.Type.PARAMETERS
+    for p in sections[1].value:
+        assert p.description is not None
+    
+    assert sections[2].type is Section.Type.EXCEPTIONS
+    for p in sections[2].value:
+        assert p.description is not None
+    
+    assert sections[3].type is Section.Type.RETURN
+    assert sections[3].value.description is not None
+
 def test_property_docstring():
     """Parse a property docstring."""
     class_ = Loader().get_object_documentation("tests.fixtures.parsing.docstrings.NotDefinedYet")