Prefer variable comments

Resolves #2042

CHANGELOG.md

@@ -5,6 +5,10 @@
 -   TypeDoc will now treat `@typedef {import("foo").Bar<Z>} Baz` type declarations which forward type parameters to the imported
     symbol as re-exports of that symbol, #2044.
 
+### Bug Fixes
+
+-   TypeDoc will now prefer comments on variable declarations over signature comments, #2042.
+
 ## v0.23.14 (2022-09-03)
 
 ### Features

src/lib/converter/factories/signature.ts

@@ -1,6 +1,7 @@
 import * as ts from "typescript";
 import * as assert from "assert";
 import {
+    ConversionFlags,
     DeclarationReflection,
     IntrinsicType,
     ParameterReflection,
@@ -41,7 +42,15 @@ export function createSignature(
         kind,
         context.scope
     );
-    if (declaration) {
+
+    // If we are creating signatures for a variable and the variable has a comment associated with it
+    // then we should prefer that variable's comment over any comment on the signature. The comment plugin
+    // will copy the comment down if this signature doesn't have one, so don't set one.
+    if (
+        declaration &&
+        (!context.scope.comment ||
+            !(context.scope.conversionFlags & ConversionFlags.VariableSource))
+    ) {
         sigRef.comment = getSignatureComment(
             declaration,
             context.converter.config,

src/lib/converter/symbols.ts

@@ -8,6 +8,7 @@ import {
     Reflection,
     ReflectionFlag,
     ReflectionKind,
+    ConversionFlags,
 } from "../models";
 import {
     getEnumFlags,
@@ -894,7 +895,7 @@ function convertVariableAsFunction(
         exportSymbol
     );
     setModifiers(symbol, accessDeclaration, reflection);
-
+    reflection.conversionFlags |= ConversionFlags.VariableSource;
     context.finalizeDeclarationReflection(reflection);
 
     const reflectionContext = context.withScope(reflection);

src/lib/models/reflections/declaration.ts

@@ -29,6 +29,14 @@ export interface DeclarationHierarchy {
     isTarget?: boolean;
 }
 
+/**
+ * @internal
+ */
+export enum ConversionFlags {
+    None = 0,
+    VariableSource = 1,
+}
+
 /**
  * A reflection that represents a single declaration emitted by the TypeScript compiler.
  *
@@ -140,6 +148,12 @@ export class DeclarationReflection extends ContainerReflection {
      */
     version?: string;
 
+    /**
+     * Flags for information about a reflection which is needed solely during conversion.
+     * @internal
+     */
+    conversionFlags = ConversionFlags.None;
+
     override hasGetterOrSetter(): boolean {
         return !!this.getSignature || !!this.setSignature;
     }

src/lib/models/reflections/index.ts

@@ -6,7 +6,7 @@ export {
 } from "./abstract";
 export type { TraverseCallback } from "./abstract";
 export { ContainerReflection } from "./container";
-export { DeclarationReflection } from "./declaration";
+export { DeclarationReflection, ConversionFlags } from "./declaration";
 export type { DeclarationHierarchy } from "./declaration";
 export { ReflectionKind } from "./kind";
 export { ParameterReflection } from "./parameter";

src/test/converter2/issues/gh2042.ts

@@ -0,0 +1,23 @@
+function factory() {
+    /** inner docs */
+    function fn() {}
+    return fn;
+}
+
+export const built = factory();
+
+/** outer docs */
+export const built2 = factory();
+
+const obj = {
+    /** inner docs */
+    fn(x: unknown) {},
+};
+
+export const fn = obj.fn;
+
+/**
+ * outer docs
+ * @param x param-docs
+ */
+export const fn2 = obj.fn;

src/test/issueTests.ts

@@ -768,6 +768,25 @@ export const issueTests: {
         equal(AnotherCtor.type.declaration.signatures?.length, 1);
     },
 
+    gh2042(project) {
+        for (const [name, docs] of [
+            ["built", "inner docs"],
+            ["built2", "outer docs"],
+            ["fn", "inner docs"],
+            ["fn2", "outer docs"],
+        ]) {
+            const refl = query(project, name);
+            ok(refl.signatures?.[0]);
+            equal(
+                Comment.combineDisplayParts(
+                    refl.signatures[0].comment?.summary
+                ),
+                docs,
+                name
+            );
+        }
+    },
+
     gh2044(project) {
         for (const [name, ref] of [
             ["Foo", false],