feat: add support for inheriting field descriptions from parent classes (#45)

* feat: add support for inheriting field descriptions from parent classes

* fix for 3.10

* fix: handle ValueError in _backfill_inherited_descriptions and improve comments

Author: tlambert03

src/griffe_fieldz/_extension.py

@@ -114,6 +114,17 @@ def on_class_members(
 
     # ------------------------------
 
+    def on_class(self, *, cls: Class, **kwargs: Any) -> None:
+        """Fill in missing descriptions for inherited fields.
+
+        This runs after the full object tree is built, so griffe's
+        inheritance APIs (mro, attributes, inherited_members) work here.
+        """
+        if self.include_inherited and cls.docstring:
+            _backfill_inherited_descriptions(cls)
+
+    # ------------------------------
+
     def _inject_fields(self, griffe_obj: Object, runtime_obj: Any) -> None:
         # update the object instance with the evaluated docstring
         docstring = inspect.cleandoc(getattr(runtime_obj, "__doc__", "") or "")
@@ -136,6 +147,56 @@ def _inject_fields(self, griffe_obj: Object, runtime_obj: Any) -> None:
         )
 
 
+def _backfill_inherited_descriptions(cls: Class) -> None:
+    """Fill in missing field descriptions from parent classes.
+
+    Uses griffe's MRO to find descriptions from parent docstring sections
+    and inherited attribute docstrings. Must be called after the full object
+    tree is built (e.g. from on_class), so that mro() works.
+    """
+    sections = cls.docstring.parsed  # pyright: ignore[reportOptionalMemberAccess]
+
+    # Collect descriptions with empty strings that we need to fill
+    empty_items: dict[str, DocstringParameter | DocstringAttribute] = {}
+    params_or_attrs = (DocstringSectionParameters, DocstringSectionAttributes)
+    for section in sections:
+        if isinstance(section, params_or_attrs):
+            for item in section.value:
+                if not item.description:
+                    empty_items[item.name] = item
+
+    if not empty_items:
+        return
+
+    # Walk parent classes looking for descriptions
+    try:
+        parents = cls.mro()
+    except ValueError:  # pragma: no cover
+        return
+
+    for parent in parents:
+        # Check parent's parsed docstring sections
+        if parent.docstring:
+            for section in parent.docstring.parsed:
+                if isinstance(section, params_or_attrs):
+                    for item in section.value:
+                        if item.name in empty_items and item.description:
+                            empty_items[item.name].description = item.description
+                            del empty_items[item.name]
+        # Check parent's direct member inline docstrings.
+        # This is a fallback for parents not processed by this extension
+        # (e.g. a base class from another package). possibly unreachable
+        for name in list(empty_items):  # pragma: no cover
+            if name in parent.members:
+                member = parent.members[name]
+                if member.docstring:
+                    empty_items[name].description = member.docstring.value
+                    del empty_items[name]
+
+        if not empty_items:
+            return
+
+
 def _to_annotation(
     type_: Any, docstring: Docstring, *, strip_annotated: bool = False
 ) -> str | Expr | None:
@@ -284,7 +345,11 @@ def _merged_kwargs(
     strip_annotated: bool = False,
 ) -> DocstringNamedElementKwargs:
     desc = field.description or field.metadata.get("description", "") or ""
-    if not desc and (doc := getattr(field.default_factory, "__doc__", None)):
+    if (
+        not desc
+        and field.default_factory is not field.MISSING
+        and (doc := getattr(field.default_factory, "__doc__", None))
+    ):
         desc = inspect.cleandoc(doc) or ""
 
     if not desc and field.name in griffe_obj.attributes:

tests/fake_module.py

@@ -37,6 +37,27 @@ class Gt:
     """Mock annotation."""
 
 
+@dataclass
+class ParentWithDocstringDesc:
+    """Parent with field descriptions in docstring.
+
+    Parameters:
+        x: x described in parent docstring
+    """
+
+    x: int = 1
+    y: int = field(default=2, metadata={"description": "y from metadata"})
+    z: int = 3
+    """z inline docstring"""
+
+
+@dataclass
+class ChildInheritsDocstringDesc(ParentWithDocstringDesc):
+    """Child that inherits all fields."""
+
+    pass
+
+
 @dataclass
 class WithAnnotated:
     """Class with Annotated fields."""

tests/test_griffe_fieldz.py

@@ -79,6 +79,51 @@ def test_add_if_missing_merges() -> None:
     assert section.value[0].value == "val"
 
 
+def test_inherited_docstring_descriptions() -> None:
+    """Test that child classes inherit field descriptions from parent docstrings.
+
+    https://github.com/pyapp-kit/griffe-fieldz/issues/19
+    """
+    loader = GriffeLoader(
+        extensions=Extensions(FieldzExtension(include_inherited=True)),
+        docstring_parser="google",
+    )
+    fake_mod = loader.load("tests.fake_module")
+
+    # First verify that the parent class itself has the descriptions
+    parent_cls = cast("griffe.Class", fake_mod["ParentWithDocstringDesc"])
+    parent_params = None
+    for section in parent_cls.docstring.parsed:
+        if isinstance(section, griffe.DocstringSectionParameters):
+            parent_params = section
+            break
+    assert parent_params is not None
+    parent_param_dict = {p.name: p for p in parent_params.value}
+    assert parent_param_dict["x"].description == "x described in parent docstring"
+    assert parent_param_dict["y"].description == "y from metadata"
+    assert parent_param_dict["z"].description == "z inline docstring"
+
+    # Now check the child class - inherited fields should have descriptions too
+    child_cls = cast("griffe.Class", fake_mod["ChildInheritsDocstringDesc"])
+    child_params = None
+    for section in child_cls.docstring.parsed:
+        if isinstance(section, griffe.DocstringSectionParameters):
+            child_params = section
+            break
+    assert child_params is not None
+    child_param_dict = {p.name: p for p in child_params.value}
+
+    # y has description via field metadata - this works because fieldz has it
+    assert child_param_dict["y"].description == "y from metadata"
+
+    # x has description only in parent's docstring Parameters section.
+    # z has an inline docstring on the parent class attribute.
+    # Both are lost when inheriting because _merged_kwargs doesn't look at
+    # the parent class's parsed docstring or inherited attributes.
+    assert child_param_dict["x"].description == "x described in parent docstring"
+    assert child_param_dict["z"].description == "z inline docstring"
+
+
 def test_strip_annotated() -> None:
     """Test that strip_annotated option works correctly."""
     # Test with strip_annotated=False (default)