@wordpress/docgen 1.20.2 → 1.21.0

package/lib/get-type-annotation.js

@@ -373,6 +373,56 @@ function getTypeAnnotation( typeAnnotation ) {
 	}
 }
 
+/**
+ * Extract wrapped selector functions to reach inside for parameter types.
+ *
+ * This function wasn't necessary until we started introducing more TypeScript code into
+ * the project. With parameter types fully in the JSDoc comments we always have a direct
+ * match between parameter name and the type. However, when working in TypeScript where
+ * we rely on the type annotations for the types we introduce a mismatch when wrapping
+ * functions.
+ *
+ * Example:
+ *     export const getThings = createSelector( ( state ) => state.things, ( state ) => state.version );
+ *
+ * In this example we would document `state` but its type is buried inside of `createSelector`.
+ * Because this kind of scenario is tricky to properly parse without asking TypeScript directly
+ * to give us the actual type of `getThings` we're going to special-case the known instances
+ * of selector-wrapping to extract the inner function and re-connect the parameter types
+ * with their descriptions in the JSDoc comments.
+ *
+ * If we find more wrapper functions on selectors we should add them below following the
+ * example of `createSelector` and `createRegsitrySelector`.
+ *
+ * @param {ASTNode} token Contains either a function or a call to a function-wrapper.
+ *
+ * TODO: Remove the special-casing here once we're able to infer the types from TypeScript itself.
+ */
+function unwrapWrappedSelectors( token ) {
+	if ( babelTypes.isFunctionDeclaration( token ) ) {
+		return token;
+	}
+
+	if ( babelTypes.isArrowFunctionExpression( token ) ) {
+		return token;
+	}
+
+	if ( babelTypes.isCallExpression( token ) ) {
+		// createSelector( ( state, queryId ) => state.queries[ queryId ] );
+		//                 \--------------------------------------------/ CallExpression.arguments[0]
+		if ( token.callee.name === 'createSelector' ) {
+			return token.arguments[ 0 ];
+		}
+
+		// createRegistrySelector( ( selector ) => ( state, queryId ) => select( 'core/queries' ).get( queryId ) );
+		//                                         \-----------------------------------------------------------/ CallExpression.arguments[0].body
+		//                         \---------------------------------------------------------------------------/ CallExpression.arguments[0]
+		if ( token.callee.name === 'createRegistrySelector' ) {
+			return token.arguments[ 0 ].body;
+		}
+	}
+}
+
 /**
  * @param {ASTNode} token
  * @return {babelTypes.ArrowFunctionExpression | babelTypes.FunctionDeclaration} The function token.
@@ -392,7 +442,7 @@ function getFunctionToken( token ) {
 		resolvedToken = resolvedToken.declarations[ 0 ].init;
 	}
 
-	return resolvedToken;
+	return unwrapWrappedSelectors( resolvedToken );
 }
 
 function getFunctionNameForError( declarationToken ) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/docgen",
-	"version": "1.20.2",
+	"version": "1.21.0",
 	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -39,5 +39,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "446565ecaa40370173c18926535e975ec5652b71"
+	"gitHead": "1ba52312b56db563df2d8d4fba5b00613fb46d8c"
 }