From fa5144594b653e8fd6267f8ad73a4cb6c21ebb60 Mon Sep 17 00:00:00 2001
From: Gerrit Birkeland <gerrit@gerritbirkeland.com>
Date: Tue, 28 Jun 2022 21:15:51 -0600
Subject: [PATCH] Improve support for inheriting documentation from accessors

Resolves #1968
---
 CHANGELOG.md                                  |  5 +++++
 .../comments/declarationReference.ts          |  4 ++++
 .../comments/declarationReferenceResolver.ts  | 17 ++++++++++++++++-
 src/lib/converter/plugins/InheritDocPlugin.ts | 11 +++++++++++
 src/test/converter2/issues/gh1968.ts          | 19 +++++++++++++++++++
 src/test/issueTests.ts                        |  7 +++++++
 6 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 src/test/converter2/issues/gh1968.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02f81e920..456941071 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,11 @@
 ### Bug Fixes
 
 -   TypeDoc will no longer crash if a comment contains an empty `@example` tag, #1967.
+-   TypeDoc will now detect attempted inheritance from accessors and inherit from the getter or setter, #1968.
+
+### Features
+
+-   Added support for TypeDoc specific `:getter` and `:setter` meaning keywords in declaration references.
 
 ## v0.23.2 (2022-06-28)
 
diff --git a/src/lib/converter/comments/declarationReference.ts b/src/lib/converter/comments/declarationReference.ts
index 29c126e49..eb7b68096 100644
--- a/src/lib/converter/comments/declarationReference.ts
+++ b/src/lib/converter/comments/declarationReference.ts
@@ -23,6 +23,10 @@ export const MeaningKeywords = [
     "new", // SymbolFlags.Signature (for __new)
     "index", // SymbolFlags.Signature (for __index)
     "complex", // Any complex type
+
+    // TypeDoc specific
+    "getter",
+    "setter",
 ] as const;
 export type MeaningKeyword = typeof MeaningKeywords[number];
 
diff --git a/src/lib/converter/comments/declarationReferenceResolver.ts b/src/lib/converter/comments/declarationReferenceResolver.ts
index c30b9fd04..9184e4540 100644
--- a/src/lib/converter/comments/declarationReferenceResolver.ts
+++ b/src/lib/converter/comments/declarationReferenceResolver.ts
@@ -5,7 +5,7 @@ import {
     Reflection,
     ReflectionKind,
 } from "../../models";
-import { filterMap } from "../../utils";
+import { assertNever, filterMap } from "../../utils";
 import type {
     ComponentPath,
     DeclarationReference,
@@ -166,6 +166,21 @@ function resolveKeyword(
         case "complex":
             if (refl.kindOf(ReflectionKind.SomeType)) return [refl];
             break;
+
+        case "getter":
+            if ((refl as DeclarationReflection).getSignature) {
+                return [(refl as DeclarationReflection).getSignature!];
+            }
+            break;
+
+        case "setter":
+            if ((refl as DeclarationReflection).setSignature) {
+                return [(refl as DeclarationReflection).setSignature!];
+            }
+            break;
+
+        default:
+            assertNever(kw);
     }
 }
 
diff --git a/src/lib/converter/plugins/InheritDocPlugin.ts b/src/lib/converter/plugins/InheritDocPlugin.ts
index 64af5b1b6..268220f79 100644
--- a/src/lib/converter/plugins/InheritDocPlugin.ts
+++ b/src/lib/converter/plugins/InheritDocPlugin.ts
@@ -1,6 +1,7 @@
 import {
     Comment,
     DeclarationReflection,
+    ReflectionKind,
     SignatureReflection,
 } from "../../models";
 import { Component, ConverterComponent } from "../components";
@@ -77,6 +78,16 @@ export class InheritDocPlugin extends ConverterComponent {
                 }
             }
 
+            if (
+                sourceRefl instanceof DeclarationReflection &&
+                sourceRefl.kindOf(ReflectionKind.Accessor)
+            ) {
+                // Accessors, like functions, never have comments on their actual root reflection.
+                // If the user didn't specify whether to inherit from the getter or setter, then implicitly
+                // try to inherit from the getter, #1968.
+                sourceRefl = sourceRefl.getSignature || sourceRefl.setSignature;
+            }
+
             if (!sourceRefl) {
                 this.application.logger.warn(
                     `Failed to find "${source}" to inherit the comment from in the comment for ${reflection.getFullName()}`
diff --git a/src/test/converter2/issues/gh1968.ts b/src/test/converter2/issues/gh1968.ts
new file mode 100644
index 000000000..da5799249
--- /dev/null
+++ b/src/test/converter2/issues/gh1968.ts
@@ -0,0 +1,19 @@
+export class Foo {
+    /** getter */
+    get x() {
+        return 1;
+    }
+    /** setter */
+    set x(value: number) {
+        throw new Error();
+    }
+}
+
+export class Bar {
+    /** {@inheritDoc Foo.x} */
+    x = 1;
+    /** {@inheritDoc Foo.x:getter} */
+    y = 2;
+    /** {@inheritDoc Foo.x:setter} */
+    z = 3;
+}
diff --git a/src/test/issueTests.ts b/src/test/issueTests.ts
index 7f54bb49e..60352b652 100644
--- a/src/test/issueTests.ts
+++ b/src/test/issueTests.ts
@@ -548,4 +548,11 @@ export const issueTests: {
             },
         ]);
     },
+
+    gh1968(project) {
+        const comments = ["Bar.x", "Bar.y", "Bar.z"].map((n) =>
+            Comment.combineDisplayParts(query(project, n).comment?.summary)
+        );
+        equal(comments, ["getter", "getter", "setter"]);
+    },
 };