Make automatic function conversion more conservative

Ref: #2881

Author: Gerrit0

CHANGELOG.md

@@ -13,7 +13,9 @@ title: Changelog
 - The `source-order` sort ordering now considers package names / package relative paths instead of using the absolute paths to a file.
 - TypeDoc will only check for a project README file next to the discovered `package.json` file if `--readme` is not set
   this change improves handling of monorepo setups where some packages have readme files and others do not, #2875.
-- Function-like variable declarations with a type annotation will now be converted as variables unless annotated with `@function`, #2881.
+- Function-like variable exports will now only be automatically converted as function types if
+  they are initialized with a function expression. TypeDoc can be instructed to convert them as functions
+  with the `@function` tag, #2881.
 
 ### API Breaking Changes
 

site/tags/function.md

@@ -6,14 +6,14 @@ title: "@function"
 
 **Tag Kind:** [Modifier](../tags.md#modifier-tags)
 
-If a variable declaration is callable and does not have a type declaration,
-TypeDoc may convert it as a function. Sometimes, even if a type declaration
-is specified, it is desirable to convert a variable as if it was a function.
+If a variable declaration is callable (but not constructable), TypeDoc can
+convert it as a function. TypeDoc will only automatically convert it as a function
+if the variable's initializer is a function expression and the variable is not
+explicitly typed.
 
-This tag will cause TypeDoc to convert the specified variable as a function
-even if it has a type declaration. TypeDoc will still refuse to convert the
-variable as a function if it contains construct signatures or does not contain
-any call signatures.
+TypeDoc can be instructed to convert a callable variable declaration as a function
+with the `@function` tag. The `@function` tag will have no effect if the variable
+it is placed on is not callable or is constructable.
 
 ## Example
 
@@ -32,6 +32,21 @@ export const Callable2: MultiCallSignature = () => "";
 
 // Documented as if it was a function
 export const Callable3 = () => "";
+
+// Documented as a variable
+export const Callable4 = Object.assign(function () {
+    return "";
+}, {
+    fnProp: "",
+});
+
+// Documented as if it was a function
+/** @function */
+export const Callable5 = Object.assign(function () {
+    return "";
+}, {
+    fnProp: "",
+});
 ```
 
 ## See Also

src/lib/converter/symbols.ts

@@ -995,7 +995,7 @@ function convertVariable(
     ) {
         if (
             comment?.hasModifier("@function") ||
-            !(declaration && ts.isVariableDeclaration(declaration) && declaration.type)
+            (declaration && shouldAutomaticallyConvertAsFunction(declaration))
         ) {
             return convertVariableAsFunction(context, symbol, exportSymbol);
         }
@@ -1418,3 +1418,48 @@ function setSymbolModifiers(symbol: ts.Symbol, reflection: Reflection) {
         hasAllFlags(symbol.flags, ts.SymbolFlags.Optional),
     );
 }
+
+function shouldAutomaticallyConvertAsFunction(node: ts.Declaration): boolean {
+    // const fn = () => {}
+    if (ts.isVariableDeclaration(node)) {
+        if (node.type || !node.initializer) return false;
+
+        return isFunctionLikeInitializer(node.initializer);
+    }
+
+    // { fn: () => {} }
+    if (ts.isPropertyAssignment(node)) {
+        return isFunctionLikeInitializer(node.initializer);
+    }
+
+    // exports.fn = () => {}
+    // exports.fn ||= () => {}
+    // exports.fn ??= () => {}
+    if (ts.isPropertyAccessExpression(node)) {
+        if (
+            ts.isBinaryExpression(node.parent) &&
+            [ts.SyntaxKind.EqualsToken, ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.QuestionQuestionEqualsToken]
+                .includes(node.parent.operatorToken.kind)
+        ) {
+            return isFunctionLikeInitializer(node.parent.right);
+        }
+    }
+
+    return false;
+}
+
+function isFunctionLikeInitializer(node: ts.Expression): boolean {
+    if (ts.isFunctionExpression(node) || ts.isArrowFunction(node)) {
+        return true;
+    }
+
+    if (ts.isSatisfiesExpression(node)) {
+        return isFunctionLikeInitializer(node.expression);
+    }
+
+    if (ts.isAsExpression(node)) {
+        return isFunctionLikeInitializer(node.expression);
+    }
+
+    return false;
+}

src/test/converter2/issues/gh1462.ts

@@ -5,4 +5,8 @@ const sideEffects = {
     prop: 1,
 };
 
-export const { method: METHOD, prop: PROP } = sideEffects;
+export const {
+    /** @function */
+    method: METHOD,
+    prop: PROP,
+} = sideEffects;

src/test/converter2/issues/gh1770.ts

@@ -8,6 +8,7 @@ const api = (): {
 export const {
     /**
      * Docs for Sym1
+     * @function
      */
     sym1,
 

src/test/converter2/issues/gh2008.ts

@@ -1,4 +1,4 @@
 const makeFn = () => () => {};
 
-/** Docs */
+/** Docs @function */
 export const myFn = makeFn();

src/test/converter2/issues/gh2042.ts

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

src/test/converter2/issues/gh2307.ts

@@ -1,5 +1,6 @@
 const times = (b: number) => (a: number) => a * b;
 
+/** @function */
 export const double = times(2);
 
 export const foo = () => 123;

src/test/issues.c2.test.ts

@@ -1121,9 +1121,9 @@ describe("Issue Tests", () => {
             return refl.signatures?.flatMap((sig) => sig.sources!.map((src) => src.line));
         };
 
-        equal(getLines("double"), [3]);
-        equal(getLines("foo"), [5]);
-        equal(getLines("all"), [9, 10]);
+        equal(getLines("double"), [4]);
+        equal(getLines("foo"), [6]);
+        equal(getLines("all"), [10, 11]);
     });
 
     it("#2320 Uses type parameters from parent class in arrow-methods, ", () => {