@wordpress/docgen 1.17.3 → 1.18.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 1.18.0 (2021-07-21)
+
+### Bug Fixes
+
+-	Fix getting param annotations for default exported functions. ([#31603](https://github.com/WordPress/gutenberg/pull/31603))
+
 ## 1.17.0 (2021-04-29)
 
 ### New Features

package/lib/engine.js

@@ -38,10 +38,10 @@ const engine = ( path, code, getIRFromPath = () => {} ) => {
 /**
  * Function that takes code and returns an intermediate representation.
  *
- * @param {string} code The code to parse.
+ * @param {string}   code                 The code to parse.
  * @param {Function} [getIRFromPath=noop] Callback to retrieve the
- * Intermediate Representation from a path relative to the file
- * being parsed.
+ *                                        Intermediate Representation from a path relative to the file
+ *                                        being parsed.
  *
  * @return {Object} Intermediate Representation in JSON.
  */

package/lib/get-intermediate-representation.js

@@ -121,11 +121,11 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
  * the identifier declaration will be looked up in the file or dependency
  * if an `ast` and `parseDependency` callback are provided.
  *
- * @param {string} path Path to file being processed.
- * @param {Object} token Espree export token.
- * @param {Object} [ast] Espree ast of the file being parsed.
+ * @param {string}   path              Path to file being processed.
+ * @param {Object}   token             Espree export token.
+ * @param {Object}   [ast]             Espree ast of the file being parsed.
  * @param {Function} [parseDependency] Function that takes a path
- * and returns the intermediate representation of the dependency file.
+ *                                     and returns the intermediate representation of the dependency file.
  *
  * @return {Object} Intermediate Representation in JSON.
  */

package/lib/get-type-annotation.js

@@ -8,12 +8,13 @@ const { types: babelTypes } = require( '@babel/core' );
 /** @typedef {ReturnType<import('comment-parser').parse>[0]} CommentBlock */
 /** @typedef {CommentBlock['tags'][0]} CommentTag */
 /** @typedef {babelTypes.TSType} TypeAnnotation */
+/** @typedef {babelTypes.TSCallSignatureDeclaration | babelTypes.TSFunctionType | babelTypes.TSConstructSignatureDeclaration} ExtendedTypeAnnotation */
 /** @typedef {import('@babel/core').Node} ASTNode */
 /* eslint-enable jsdoc/valid-types */
 
 /**
- * @param {babelTypes.TSCallSignatureDeclaration | babelTypes.TSFunctionType | babelTypes.TSConstructSignatureDeclaration} typeAnnotation
- * @param {' => ' | ': '} returnIndicator The return indicator to use. Allows using the same function for function annotations and object call properties.
+ * @param {ExtendedTypeAnnotation} typeAnnotation
+ * @param {' => ' | ': '}          returnIndicator The return indicator to use. Allows using the same function for function annotations and object call properties.
  */
 function getFunctionTypeAnnotation( typeAnnotation, returnIndicator ) {
 	const nonRestParams = typeAnnotation.parameters
@@ -43,7 +44,9 @@ function getFunctionTypeAnnotation( typeAnnotation, returnIndicator ) {
 			typeAnnotation.typeAnnotation.typeAnnotation
 	);
 
-	return `( ${ params } )${ returnIndicator }${ returnType }`;
+	const paramsWithParens = params.length ? `( ${ params } )` : `()`;
+
+	return `${ paramsWithParens }${ returnIndicator }${ returnType }`;
 }
 
 /**
@@ -376,6 +379,10 @@ function getTypeAnnotation( typeAnnotation ) {
  */
 function getFunctionToken( token ) {
 	let resolvedToken = token;
+	if ( babelTypes.isExportDefaultDeclaration( resolvedToken ) ) {
+		resolvedToken = resolvedToken.declaration;
+	}
+
 	if ( babelTypes.isExportNamedDeclaration( resolvedToken ) ) {
 		resolvedToken = resolvedToken.declaration;
 	}
@@ -441,9 +448,9 @@ function getQualifiedObjectPatternTypeAnnotation( tag, paramType ) {
 }
 
 /**
- * @param {CommentTag} tag The documented parameter.
- * @param {ASTNode} declarationToken The function the parameter is documented on.
- * @param {number} paramIndex The parameter index.
+ * @param {CommentTag} tag              The documented parameter.
+ * @param {ASTNode}    declarationToken The function the parameter is documented on.
+ * @param {number}     paramIndex       The parameter index.
  * @return {null | string} The parameter's type annotation.
  */
 function getParamTypeAnnotation( tag, declarationToken, paramIndex ) {
@@ -540,8 +547,8 @@ function getVariableTypeAnnotation( declarationToken ) {
 
 module.exports =
 	/**
-	 * @param {CommentTag} tag A comment tag.
-	 * @param {ASTNode} token A function token.
+	 * @param {CommentTag}    tag   A comment tag.
+	 * @param {ASTNode}       token A function token.
 	 * @param {number | null} index The index of the parameter or `null` if not a param tag.
 	 * @return {null | string} The type annotation for the given tag or null if the tag has no type annotation.
 	 */

package/lib/markdown/embed.js

@@ -15,8 +15,8 @@ const getHeadingIndex = ( ast, index ) => {
 /**
  * Inserts new contents within the token boundaries.
  *
- * @param {string} token String to embed in the start/end tokens.
- * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded.
+ * @param {string} token         String to embed in the start/end tokens.
+ * @param {Object} targetAst     The remark AST of the file where the new contents are to be embedded.
  * @param {Object} newContentAst The new contents to be embedded in remark AST format.
  * @return {boolean} Whether the contents were embedded or not.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/docgen",
-	"version": "1.17.3",
+	"version": "1.18.1",
 	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -27,7 +27,7 @@
 		"docgen": "./bin/cli.js"
 	},
 	"dependencies": {
-		"@babel/core": "^7.13.10",
+		"@babel/core": "^7.16.0",
 		"comment-parser": "^1.1.1",
 		"lodash": "^4.17.21",
 		"mdast-util-inject": "1.1.0",
@@ -39,5 +39,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "c6e7eca347923b56c0117f8129f80eba6ac59f52"
+	"gitHead": "9a1dd3474d937468e4cf9caf9886ad61ef0a8f50"
 }