From 0dc6f0fdda78ba7cce96dd4bb64cf751b48ebab7 Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Wed, 4 Nov 2026 15:51:30 -0800
Subject: [PATCH] Add docstring

---
 src/documents/models.py | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/src/documents/models.py b/src/documents/models.py
index e1dfdb5451..a8a075dd6c 100644
--- a/src/documents/models.py
+++ b/src/documents/models.py
@@ -133,6 +133,7 @@ class Tag(MatchingModel):
 
     @classmethod
     def get_hierarchy(cls) -> "TagHierarchy":
+        """Read the tag hierarchy in one query, ready to use across multiple tags."""
         from documents.tag_hierarchy import TagHierarchy
 
         return TagHierarchy(cls.objects.values_list("pk", "tn_parent_id"))
@@ -145,17 +146,37 @@ class Tag(MatchingModel):
         return self.tn_parent
 
     def get_ancestors_pks(self) -> list[int]:
+        """Return ancestor IDs ordered from root to parent.
+
+        Each call reads the full hierarchy. Use Tag.get_hierarchy() once and
+        reuse it when working with several tags.
+        """
         return self.get_hierarchy().ancestors(self.tn_parent_id)
 
     def get_ancestors(self) -> list["Tag"]:
+        """Return ancestors ordered from root to parent.
+
+        Each call reads the full hierarchy. Use Tag.get_hierarchy() once and
+        reuse it when working with several tags.
+        """
         ids = self.get_ancestors_pks()
         tags = self.__class__.objects.in_bulk(ids)
         return [tags[pk] for pk in ids]
 
     def get_descendants_pks(self) -> set[int]:
+        """Return all descendant IDs.
+
+        Each call reads the full hierarchy. Use Tag.get_hierarchy() once and
+        reuse it when working with several tags.
+        """
         return self.get_hierarchy().descendants([self.pk])
 
     def get_descendants(self) -> "models.QuerySet[Tag]":
+        """Return a queryset of all descendants.
+
+        Each call reads the full hierarchy. Use Tag.get_hierarchy() once and
+        reuse it when working with several tags.
+        """
         return self.__class__.objects.filter(pk__in=self.get_descendants_pks())
 
     def get_children_queryset(self) -> "models.QuerySet[Tag]":