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*");
+ });
 });