From c2c12894e07b6addaa282a90926115aa4dedc2bd Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Wed, 27 Nov 2024 16:12:04 -0700
Subject: [PATCH] Fix `@categoryDescription`, `@groupDescription` on modules

---
 CHANGELOG.md                                        |  1 +
 .../themes/default/partials/moduleReflection.tsx    |  7 ++++++-
 src/lib/output/themes/lib.tsx                       | 13 ++++++++++++-
 3 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index fca3b7629..dac8e368e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ title: Changelog
 ### Bug Fixes
 
 -   Fixed automatic discovery of entry points in packages mode.
+-   Fixed handling of `@categoryDescription` and `@groupDescription` on module pages, #2787.
 
 ## v0.27.0 (2024-11-27)
 
diff --git a/src/lib/output/themes/default/partials/moduleReflection.tsx b/src/lib/output/themes/default/partials/moduleReflection.tsx
index 1a3585d4f..281fcad60 100644
--- a/src/lib/output/themes/default/partials/moduleReflection.tsx
+++ b/src/lib/output/themes/default/partials/moduleReflection.tsx
@@ -29,7 +29,7 @@ export function moduleReflection(context: DefaultThemeRenderContext, mod: Declar
                 </section>
             )}
 
-            {sections.map(({ title, children }) => {
+            {sections.map(({ title, children, description }) => {
                 context.page.startNewSection(title);
 
                 return (
@@ -39,6 +39,11 @@ export function moduleReflection(context: DefaultThemeRenderContext, mod: Declar
                                 {context.icons.chevronDown()} {title}
                             </h2>
                         </summary>
+                        {description && (
+                            <div class="tsd-comment tsd-typography">
+                                <Raw html={context.markdown(description)} />
+                            </div>
+                        )}
                         <dl class="tsd-member-summaries">
                             {children.map((item) => context.moduleMemberSummary(item))}
                         </dl>
diff --git a/src/lib/output/themes/lib.tsx b/src/lib/output/themes/lib.tsx
index a7e392840..9f702cd61 100644
--- a/src/lib/output/themes/lib.tsx
+++ b/src/lib/output/themes/lib.tsx
@@ -1,7 +1,9 @@
 import type { DefaultThemeRenderContext } from "../index.js";
 import {
+    type CommentDisplayPart,
     type ContainerReflection,
     DeclarationReflection,
+    type DocumentReflection,
     ProjectReflection,
     ReferenceReflection,
     type Reflection,
@@ -189,16 +191,23 @@ export function getHierarchyRoots(project: ProjectReflection): DeclarationReflec
     return result;
 }
 
+export interface MemberSections {
+    title: string;
+    description?: CommentDisplayPart[];
+    children: Array<DocumentReflection | DeclarationReflection>;
+}
+
 export function getMemberSections(
     parent: ContainerReflection,
     childFilter: (refl: Reflection) => boolean = () => true,
-) {
+): MemberSections[] {
     if (parent.categories?.length) {
         return filterMap(parent.categories, (cat) => {
             const children = cat.children.filter(childFilter);
             if (!children.length) return;
             return {
                 title: cat.title,
+                description: cat.description,
                 children,
             };
         });
@@ -212,6 +221,7 @@ export function getMemberSections(
                     if (!children.length) return;
                     return {
                         title: `${group.title} - ${cat.title}`,
+                        description: cat.description,
                         children,
                     };
                 });
@@ -221,6 +231,7 @@ export function getMemberSections(
             if (!children.length) return [];
             return {
                 title: group.title,
+                description: group.description,
                 children,
             };
         });