From e28c686d28abfa85277fee723fab6abc43cc309d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= <zoe.spriggs@raspberrypi.org>
Date: Fri, 4 Sep 2026 14:05:13 -0600
Subject: [PATCH 1/2] docs: fall back to @returns label on api docs

---
 packages/blockly/core/block_svg.ts     |  1 -
 packages/docs/typedoc-member-index.mjs | 30 ++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/packages/blockly/core/block_svg.ts b/packages/blockly/core/block_svg.ts
index 6bd8b4aea4c..3aa066a6ed7 100644
--- a/packages/blockly/core/block_svg.ts
+++ b/packages/blockly/core/block_svg.ts
@@ -1455,7 +1455,6 @@ export class BlockSvg
     this.queueRender();
   }
 
-  /** @override */
   override appendInput(input: Input): Input {
     super.appendInput(input);
     this.queueRender();
diff --git a/packages/docs/typedoc-member-index.mjs b/packages/docs/typedoc-member-index.mjs
index 0d9e77714a5..37d0509f34f 100644
--- a/packages/docs/typedoc-member-index.mjs
+++ b/packages/docs/typedoc-member-index.mjs
@@ -10,6 +10,16 @@ import { ReflectionKind } from 'typedoc';
 /** Sections that get an index table, in the order the tables appear. */
 const INDEXED_SECTIONS = ['Properties', 'Methods'];
 
+/**
+ * Lowercases the first letter, leaving text that opens with an acronym (JSON,
+ * SVG, DOM) alone.
+ */
+function decapitalize(text) {
+  return /^[A-Z](?![A-Z])/.test(text)
+    ? text[0].toLowerCase() + text.slice(1)
+    : text;
+}
+
 /**
  * Adds Properties and Methods index tables to each generated reference page.
  *
@@ -21,6 +31,26 @@ class MemberIndexContext extends MarkdownThemeContext {
   constructor(theme, page, options) {
     super(theme, page, options);
     const base = { ...this.partials };
+    const baseHelpers = { ...this.helpers };
+
+    this.helpers = {
+      ...baseHelpers,
+      // Fall back to @returns text for index tables, if there is no description
+      getDescriptionForComment: (comment) => {
+        const description = baseHelpers.getDescriptionForComment(comment);
+        if (description) return description;
+
+        const returns = comment?.getTag('@returns');
+        if (!returns) return null;
+
+        const text = baseHelpers
+          .getCommentParts(returns.content)
+          .replace(/\r?\n/g, ' ')
+          .trim();
+
+        return text ? `Returns ${decapitalize(text)}` : null;
+      },
+    };
 
     this.partials = {
       ...base,

From 5a83e4f992f8d13d973fad875014f3cc887942e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zo=C3=AB=20Spriggs?= <zoe.spriggs@raspberrypi.org>
Date: Fri, 4 Sep 2026 14:59:38 -0600
Subject: [PATCH 2/2] docs: add tsdoc guidance for overriding

---
 packages/docs/docs/guides/contribute/core/style_guide.mdx | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/docs/docs/guides/contribute/core/style_guide.mdx b/packages/docs/docs/guides/contribute/core/style_guide.mdx
index 3f9a481c5f4..af50bae68d1 100644
--- a/packages/docs/docs/guides/contribute/core/style_guide.mdx
+++ b/packages/docs/docs/guides/contribute/core/style_guide.mdx
@@ -114,7 +114,7 @@ Annotations for functions should include
   will return a value, with a description of the returned value.
 
 Descriptions may omitted for functions, parameters, or return values if they are
-self-explanatory.
+self-explanatory. 
 
 For example:
 
@@ -129,3 +129,6 @@ export function getWorkspaceById(id: string): Workspace | null {
   return WorkspaceDB_[id] || null;
 }
 ```
+
+If you are overriding a function and would like it to inherit the parent's 
+TSDoc in the documentation, you should not include a TSDoc at all.