@wordpress/docgen 1.20.2 → 1.23.0

package/lib/get-type-annotation.js

@@ -110,12 +110,10 @@ function getTypeLiteralPropertyTypeAnnotations( typeAnnotation ) {
  * @param {babelTypes.TSTypeLiteral} typeAnnotation
  */
 function getTypeLiteralTypeAnnotation( typeAnnotation ) {
-	const callProperties = getTypeLiteralCallSignatureDeclarationTypeAnnotations(
-		typeAnnotation
-	);
-	const indexers = getTypeLiteralIndexSignatureTypeAnnotations(
-		typeAnnotation
-	);
+	const callProperties =
+		getTypeLiteralCallSignatureDeclarationTypeAnnotations( typeAnnotation );
+	const indexers =
+		getTypeLiteralIndexSignatureTypeAnnotations( typeAnnotation );
 	const properties = getTypeLiteralPropertyTypeAnnotations( typeAnnotation );
 
 	return `{ ${ callProperties }${ properties }${ indexers }}`;
@@ -373,6 +371,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 +440,7 @@ function getFunctionToken( token ) {
 		resolvedToken = resolvedToken.declarations[ 0 ].init;
 	}
 
-	return resolvedToken;
+	return unwrapWrappedSelectors( resolvedToken );
 }
 
 function getFunctionNameForError( declarationToken ) {

package/lib/markdown/embed.js

@@ -1,14 +1,8 @@
-/**
- * External dependencies
- */
-const { findLast } = require( 'lodash' );
-
 const getHeadingIndex = ( ast, index ) => {
 	const astBeforeIndex = ast.children.slice( 0, index );
-	const lastHeading = findLast(
-		astBeforeIndex,
-		( node ) => node.type === 'heading'
-	);
+	const lastHeading = astBeforeIndex
+		.reverse()
+		.find( ( node ) => node.type === 'heading' );
 	return lastHeading ? lastHeading.depth : 1;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/docgen",
-	"version": "1.20.2",
+	"version": "1.23.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": "a80eeb62ec7cb1418b9915c277e084a29d6665e3"
 }