@wordpress/docgen 2.44.1-next.v.202604201441.0 → 2.45.1-next.v.202605131006.0

package/lib/get-intermediate-representation.js

@@ -15,6 +15,15 @@ const hasClassWithName = ( node, name ) =>
 const hasFunctionWithName = ( node, name ) =>
 	node.type === 'FunctionDeclaration' && node.id.name === name;
 
+const hasTSDeclareFunction = ( node, name ) =>
+	node.type === 'TSDeclareFunction' && node.id?.name === name;
+
+const hasImplementationWithName = ( node, name ) =>
+	hasFunctionWithName( node, name ) ||
+	( node.type === 'ExportNamedDeclaration' &&
+		node.declaration &&
+		hasFunctionWithName( node.declaration, name ) );
+
 const hasVariableWithName = ( node, name ) =>
 	node.type === 'VariableDeclaration' &&
 	node.declarations.some( ( declaration ) => {
@@ -32,6 +41,8 @@ const hasNamedExportWithName = ( node, name ) =>
 	node.type === 'ExportNamedDeclaration' &&
 	( ( node.declaration && hasClassWithName( node.declaration, name ) ) ||
 		( node.declaration && hasFunctionWithName( node.declaration, name ) ) ||
+		( node.declaration &&
+			hasTSDeclareFunction( node.declaration, name ) ) ||
 		( node.declaration && hasVariableWithName( node.declaration, name ) ) );
 
 const hasImportWithName = ( node, name ) =>
@@ -91,19 +102,27 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 			return (
 				hasClassWithName( node, entry.localName ) ||
 				hasFunctionWithName( node, entry.localName ) ||
+				hasTSDeclareFunction( node, entry.localName ) ||
 				hasVariableWithName( node, entry.localName ) ||
 				hasNamedExportWithName( node, entry.localName ) ||
 				hasImportWithName( node, entry.localName )
 			);
 		} );
-		if ( candidates.length !== 1 ) {
+		if ( candidates.length === 0 ) {
 			return doc;
 		}
-		const node = candidates[ 0 ];
-		if ( isImportDeclaration( node ) ) {
-			doc = getJSDocFromDependency( node, entry, parseDependency );
-		} else {
-			doc = getJSDocFromToken( node );
+		const implementationNode = candidates.find( ( node ) =>
+			hasImplementationWithName( node, entry.localName )
+		);
+		for ( const node of candidates ) {
+			if ( isImportDeclaration( node ) ) {
+				doc = getJSDocFromDependency( node, entry, parseDependency );
+			} else {
+				doc = getJSDocFromToken( node, implementationNode ?? node );
+			}
+			if ( doc !== undefined ) {
+				return doc;
+			}
 		}
 		return doc;
 	}

package/lib/get-jsdoc-from-token.js

@@ -14,10 +14,14 @@ const getTypeAnnotation = require( './get-type-annotation' );
  * a object representing the leading JSDoc comment of the token,
  * if any.
  *
- * @param {Object} token Espree token.
+ * @param {Object} token                 Espree token to extract the leading JSDoc comment from.
+ * @param {Object} [typeAnnotationToken] Espree token to use for type inference. Defaults to `token`.
+ *                                       Pass the function implementation node when the JSDoc lives on
+ *                                       an overload signature so that inferred types reflect the
+ *                                       implementation's parameter/return types.
  * @return {Object} Object representing the JSDoc comment.
  */
-module.exports = ( token ) => {
+module.exports = ( token, typeAnnotationToken = token ) => {
 	let jsdoc;
 	const comments = getLeadingComments( token );
 	if ( comments && /^\*\r?\n/.test( comments ) ) {
@@ -44,7 +48,7 @@ module.exports = ( token ) => {
 
 				return {
 					...tag,
-					type: getTypeAnnotation( tag, token, index ),
+					type: getTypeAnnotation( tag, typeAnnotationToken, index ),
 					description:
 						tag.description === '\n'
 							? tag.description.trim()
@@ -55,7 +59,7 @@ module.exports = ( token ) => {
 			if ( jsdoc.tags.length === 0 ) {
 				const potentialTypeAnnotation = getTypeAnnotation(
 					{ tag: 'type' },
-					token,
+					typeAnnotationToken,
 					0
 				);
 				if ( potentialTypeAnnotation ) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/docgen",
-	"version": "2.44.1-next.v.202604201441.0+dab6d8c07",
+	"version": "2.45.1-next.v.202605131006.0+2a3d07cab",
 	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -48,5 +48,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "c788005ba4ee2a34851c1217c51602656aa7c3a6"
+	"gitHead": "8804fa29bc78a1d98e5a4d40c3e180ddd907016c"
 }