Fix #3012

Author: Gerrit0

CHANGELOG.md

@@ -7,6 +7,7 @@ title: Changelog
 ### Bug Fixes
 
 - Fixed bug introduced in 0.28.8 where TypeDoc could not render docs with some mixin classes, #3007.
+- `@inheritDoc` will now correctly overwrite `@remarks` and `@returns` blocks on the target comment, #3012.
 
 ## v0.28.12 (2025-09-01)
 

src/lib/converter/comments/parser.ts

@@ -346,6 +346,13 @@ function postProcessComment(
             ),
         );
     }
+    if ((inlineInheritDoc.length || inheritDoc.length) && returns.length) {
+        warning(
+            i18n.content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0(
+                getPosition(),
+            ),
+        );
+    }
 }
 
 const aliasedTags = new Map([["@return", "@returns"]]);

src/lib/converter/plugins/InheritDocPlugin.ts

@@ -150,6 +150,8 @@ export class InheritDocPlugin extends ConverterComponent {
         }
 
         target.comment.removeTags("@inheritDoc");
+        target.comment.removeTags("@remarks");
+        target.comment.removeTags("@returns");
         target.comment.summary = Comment.cloneDisplayParts(
             source.comment.summary,
         );

src/lib/internationalization/locales/en.cts

@@ -81,6 +81,8 @@ export = {
         "Content in the summary section will be overwritten by the @inheritDoc tag in comment at {0}",
     content_in_remarks_block_overwritten_by_inheritdoc_in_comment_at_0:
         "Content in the @remarks block will be overwritten by the @inheritDoc tag in comment at {0}",
+    content_in_returns_block_overwritten_by_inheritdoc_in_comment_at_0:
+        "Content in the @returns block will be overwritten by the @inheritDoc tag in comment at {0}",
     example_tag_literal_name:
         "The first line of an example tag will be taken literally as the example name, and should only contain text",
     inheritdoc_tag_properly_capitalized: "The @inheritDoc tag should be properly capitalized",

src/test/converter2/issues/gh3012.ts

@@ -0,0 +1,12 @@
+/**
+ * @remarks DictRemarks
+ */
+export const DictionarySchema = {};
+
+/**
+ * {@inheritDoc DictionarySchema}
+ *
+ * @remarks
+ * Alias of {@link DictionarySchema}
+ */
+export const NullProtoObjectSchema = DictionarySchema;

src/test/issues.c2.test.ts

@@ -2182,4 +2182,13 @@ describe("Issue Tests", () => {
         ok(x.comment.summary[1].target);
         ok(project.files.resolve(x.comment.summary[1].target, project) === doc);
     });
+
+    it("#3012 removes @remarks from inheriting comment", () => {
+        const project = convert();
+        const nullProto = query(project, "NullProtoObjectSchema");
+        equal(nullProto.comment?.blockTags.map(t => t.tag), ["@remarks"]);
+        equal(nullProto.comment?.blockTags.map(t => Comment.combineDisplayParts(t.content)), ["DictRemarks"]);
+
+        logger.expectMessage("warn: Content in the @remarks block will be overwritten*");
+    });
 });