[labs/analyzer] Analyze overloaded functions and methods.

packages/labs/analyzer/src/lib/javascript/classes.ts

@@ -33,7 +33,10 @@ import {
   hasExportModifier,
   getPrivacy,
 } from '../utils.js';
-import {getFunctionLikeInfo} from './functions.js';
+import {
+  getDocNodeForFunctionLikeDeclaration,
+  getFunctionLikeInfo,
+} from './functions.js';
 import {getTypeForNode} from '../types.js';
 import {
   isCustomElementSubclass,
@@ -76,14 +79,15 @@ export const getClassMembers = (
   const methodMap = new Map<string, ClassMethod>();
   const staticMethodMap = new Map<string, ClassMethod>();
   declaration.members.forEach((node) => {
-    if (ts.isMethodDeclaration(node)) {
+    if (ts.isMethodDeclaration(node) && node.body) {
       const info = getMemberInfo(node);
+      const docNode = getDocNodeForFunctionLikeDeclaration(node, analyzer);
       (info.static ? staticMethodMap : methodMap).set(
         node.name.getText(),
         new ClassMethod({
           ...info,
-          ...getFunctionLikeInfo(node, analyzer),
-          ...parseNodeJSDocInfo(node),
+          ...getFunctionLikeInfo(node, docNode, analyzer),
+          ...parseNodeJSDocInfo(docNode),
         })
       );
     } else if (ts.isPropertyDeclaration(node)) {

packages/labs/analyzer/src/lib/javascript/functions.ts

@@ -23,6 +23,26 @@ import {getTypeForNode, getTypeForType} from '../types.js';
 import {parseJSDocDescription, parseNodeJSDocInfo} from './jsdoc.js';
 import {hasDefaultModifier, hasExportModifier} from '../utils.js';
 
+export const getDocNodeForFunctionLikeDeclaration = (
+  declaration: ts.FunctionLikeDeclaration,
+  analyzer: AnalyzerInterface
+) => {
+  if (ts.getJSDocTags(declaration).length !== 0) {
+    return declaration;
+  }
+
+  // Overloaded functions have mulitple declaration nodes. If there are no
+  // JSDoc tags on the provided declaration, use the first one that does have
+  // JSDoc tags for the purpose of extracting a description.
+  const type = analyzer.program.getTypeChecker().getTypeAtLocation(declaration);
+  const allDeclarations = type.getSymbol()?.getDeclarations();
+  return (
+    (allDeclarations as Array<ts.FunctionLikeDeclaration> | undefined)?.find(
+      (x) => ts.getJSDocTags(x).length !== 0
+    ) ?? declaration
+  );
+};
+
 /**
  * Returns the name of a function declaration.
  */
@@ -58,10 +78,11 @@ const getFunctionDeclaration = (
   name: string,
   analyzer: AnalyzerInterface
 ): FunctionDeclaration => {
+  const docNode = getDocNodeForFunctionLikeDeclaration(declaration, analyzer);
   return new FunctionDeclaration({
     name,
-    ...parseNodeJSDocInfo(declaration),
-    ...getFunctionLikeInfo(declaration, analyzer),
+    ...parseNodeJSDocInfo(docNode),
+    ...getFunctionLikeInfo(declaration, docNode, analyzer),
   });
 };
 
@@ -70,20 +91,24 @@ const getFunctionDeclaration = (
  */
 export const getFunctionLikeInfo = (
   node: ts.FunctionLikeDeclaration,
+  docNode: ts.FunctionLikeDeclaration,
   analyzer: AnalyzerInterface
 ) => {
   return {
-    parameters: node.parameters.map((p) => getParameter(p, analyzer)),
-    return: getReturn(node, analyzer),
+    parameters: node.parameters.map((p, i) =>
+      getParameter(p, docNode.parameters[i], analyzer)
+    ),
+    return: getReturn(node, docNode, analyzer),
   };
 };
 
 const getParameter = (
   param: ts.ParameterDeclaration,
+  docNode: ts.ParameterDeclaration,
   analyzer: AnalyzerInterface
 ): Parameter => {
   const paramTag = ts.getAllJSDocTagsOfKind(
-    param,
+    docNode,
     ts.SyntaxKind.JSDocParameterTag
   )[0];
   const p: Parameter = {
@@ -108,10 +133,11 @@ const getParameter = (
 
 const getReturn = (
   node: ts.FunctionLikeDeclaration,
+  docNode: ts.FunctionLikeDeclaration,
   analyzer: AnalyzerInterface
 ): Return => {
   const returnTag = ts.getAllJSDocTagsOfKind(
-    node,
+    docNode,
     ts.SyntaxKind.JSDocReturnTag
   )[0];
   const signature = analyzer.program

packages/labs/analyzer/src/lib/javascript/modules.ts

@@ -117,7 +117,9 @@ export const getModule = (
   for (const statement of sourceFile.statements) {
     if (ts.isClassDeclaration(statement)) {
       addDeclaration(getClassDeclarationInfo(statement, analyzer));
-    } else if (ts.isFunctionDeclaration(statement)) {
+      // Ignore non-implementation signatures of overloaded functions by
+      // checking for `statement.body`.
+    } else if (ts.isFunctionDeclaration(statement) && statement.body) {
       addDeclaration(getFunctionDeclarationInfo(statement, analyzer));
     } else if (ts.isVariableStatement(statement)) {
       getVariableDeclarationInfo(statement, analyzer).forEach(addDeclaration);

packages/labs/analyzer/src/test/javascript/functions_test.ts

@@ -82,5 +82,93 @@ for (const lang of languages) {
     assert.equal(fn.deprecated, undefined);
   });
 
+  test('Overloaded function', ({module}) => {
+    const exportedFn = module.getResolvedExport('overloaded');
+    const fn = module.getDeclaration('overloaded');
+    assert.equal(fn, exportedFn);
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloaded`);
+    assert.equal(
+      fn.description,
+      `This function has an overloaded signature in TS.`
+    );
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description,
+      'Some value, either a string or a number.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description,
+      'Returns either a string or a number.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
+  test('Overloaded function with docs only on a non-implementation signature', ({
+    module,
+  }) => {
+    const exportedFn = module.getResolvedExport(
+      'overloadedWithDocsOnOverloadOnly'
+    );
+    const fn = module.getDeclaration('overloadedWithDocsOnOverloadOnly');
+    assert.equal(fn, exportedFn);
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloadedWithDocsOnOverloadOnly`);
+    assert.equal(
+      fn.description?.replace(/\n/g, ' '),
+      `This is not the implementation signature, but there are no docs on the implementation signature.`
+    );
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description?.replace(/\n/g, ' '),
+      'This might be a string or a number, even though this signature only allows strings.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description?.replace(/\n/g, ' '),
+      'Returns either a string or a number, but this signature only mentions `string`.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
+  test('Overloaded function with docs on many signatures', ({module}) => {
+    const exportedFn = module.getResolvedExport('overloadedWithDocsOnMany');
+    const fn = module.getDeclaration('overloadedWithDocsOnMany');
+    assert.equal(fn, exportedFn);
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloadedWithDocsOnMany`);
+    assert.equal(fn.description, `This is the implementation signature.`);
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description,
+      'Maybe a string, maybe a number.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description?.replace(/\n/g, ' '),
+      'Returns either a string or a number, depending on the mood.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
   test.run();
 }

packages/labs/analyzer/src/test/lit-element/properties_test.ts

@@ -191,5 +191,96 @@ for (const lang of languages) {
     assert.equal(property.attribute, 'static-prop');
   });
 
+  test('method with an overloaded signature and docs on a implementation signature', ({
+    element,
+  }) => {
+    const fn = Array.from(element.methods).find((m) => m.name === 'overloaded');
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloaded`);
+    assert.equal(
+      fn.description,
+      `This function has an overloaded signature in TS.`
+    );
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description,
+      'Some value, either a string or a number.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description,
+      'Returns either a string or a number.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
+  test('method with an overloaded signature and docs only on an overload signature', ({
+    element,
+  }) => {
+    const fn = Array.from(element.methods).find(
+      (m) => m.name === 'overloadedWithDocsOnOverloadOnly'
+    );
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloadedWithDocsOnOverloadOnly`);
+    assert.equal(
+      fn.description?.replace(/\n/g, ' '),
+      `This is not the implementation signature, but there are no docs on the implementation signature.`
+    );
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description?.replace(/\n/g, ' '),
+      'This might be a string or a number, even though this signature only allows strings.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description?.replace(/\n/g, ' '),
+      'Returns either a string or a number, but this signature only mentions `string`.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
+  test('method with an overloaded signature and docs on many overload signatures', ({
+    element,
+  }) => {
+    const fn = Array.from(element.methods).find(
+      (m) => m.name === 'overloadedWithDocsOnMany'
+    );
+    assert.ok(fn?.isFunctionDeclaration());
+    assert.equal(fn.name, `overloadedWithDocsOnMany`);
+    assert.equal(
+      fn.description?.replace(/\n/g, ' '),
+      `This is the implementation signature.`
+    );
+    assert.equal(fn.summary, undefined);
+    assert.equal(fn.parameters?.length, 1);
+    assert.equal(fn.parameters?.[0].name, 'x');
+    assert.equal(
+      fn.parameters?.[0].description?.replace(/\n/g, ' '),
+      'Maybe a string, maybe a number.'
+    );
+    assert.equal(fn.parameters?.[0].summary, undefined);
+    assert.equal(fn.parameters?.[0].type?.text, 'string | number');
+    assert.equal(fn.parameters?.[0].default, undefined);
+    assert.equal(fn.parameters?.[0].rest, false);
+    assert.equal(fn.return?.type?.text, 'string | number');
+    assert.equal(
+      fn.return?.description?.replace(/\n/g, ' '),
+      'Returns either a string or a number, depending on the mood.'
+    );
+    assert.equal(fn.deprecated, undefined);
+  });
+
   test.run();
 }

packages/labs/analyzer/test-files/js/functions/functions.js

@@ -36,3 +36,46 @@ export function function2(a, b = false, ...c) {
 export default function () {
   return 'default';
 }
+
+/**
+ * This function has an overloaded signature in TS.
+ * @param {string | number} x Some value, either a string or a number.
+ * @returns {string | number} Returns either a string or a number.
+ */
+export function overloaded(x) {
+  if (typeof x === 'string') {
+    return x + 'abc';
+  } else {
+    return x + 123;
+  }
+}
+
+/**
+ * This is not the implementation signature, but there are no docs on the
+ * implementation signature.
+ * @param {string | number} x This might be a string or a number, even though
+ * this signature only allows strings.
+ * @returns {string | number} Returns either a string or a number, but this
+ * signature only mentions `string`.
+ */
+export function overloadedWithDocsOnOverloadOnly(x) {
+  if (typeof x === 'string') {
+    return x + 'abc';
+  } else {
+    return x + 123;
+  }
+}
+
+/**
+ * This is the implementation signature.
+ * @param {string | number} x Maybe a string, maybe a number.
+ * @returns {string | number} Returns either a string or a number, depending on
+ * the mood.
+ */
+export function overloadedWithDocsOnMany(x) {
+  if (typeof x === 'string') {
+    return x + 'abc';
+  } else {
+    return x + 123;
+  }
+}