From 4674ff44aa8de29a6de4cfee77aa4750c19da791 Mon Sep 17 00:00:00 2001
From: Hood Chatham <roberthoodchatham@gmail.com>
Date: Wed, 27 Sep 2023 18:59:47 -0700
Subject: [PATCH] NFC Improve comment getters (#78)

This makes a few comment getters return more useful comments from children
rather than their own generally empty comment fields.
---
 sphinx_js/typedoc.py | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py
index 598860b1..b2b14b55 100644
--- a/sphinx_js/typedoc.py
+++ b/sphinx_js/typedoc.py
@@ -366,6 +366,9 @@ def get_tag_one(self, tag: str) -> Sequence[ir.DescriptionItem]:
         return description_to_ir(l[0])
 
 
+DEFAULT_COMMENT = Comment()
+
+
 class Flags(BaseModel):
     isAbstract: bool = False
     isExternal: bool = False
@@ -525,6 +528,12 @@ class Callable(NodeBase):
     ]
     signatures: list["Signature"] = []
 
+    @property
+    def comment(self) -> Comment:
+        if self.comment_ != DEFAULT_COMMENT:
+            return self.comment_
+        return self.signatures[0].comment_
+
     def _path_segments(self, base_dir: str) -> list[str]:
         return [self.name]
 
@@ -686,6 +695,14 @@ class TypeLiteral(NodeBase):
     indexSignature: "Signature | None" = None
     children: Sequence["Member"] = []
 
+    @property
+    def comment(self) -> Comment:
+        if self.comment_ != DEFAULT_COMMENT:
+            return self.comment_
+        if self.signatures:
+            return self.signatures[0].comment
+        return DEFAULT_COMMENT
+
     def render(self, converter: Converter) -> Iterator[str | ir.TypeXRef]:
         if self.signatures:
             yield from self.signatures[0].render(converter)
@@ -767,7 +784,11 @@ class Param(Base):
 
     @property
     def comment(self) -> Comment:
-        return self.comment_
+        if self.comment_ != DEFAULT_COMMENT:
+            return self.comment_
+        if isinstance(self.type, ReflectionType):
+            return self.type.declaration.comment
+        return DEFAULT_COMMENT
 
     defaultValue: str | None
     flags: Flags