@wordpress/docgen 1.18.2-next.33ec3857e2.0 → 1.19.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 ## Gutenberg
 
-    Copyright 2016-2021 by the contributors
+    Copyright 2016-2022 by the contributors
 
 **License for Contributions (on and after April 15, 2021)**
 

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

@@ -48,7 +48,7 @@ module.exports = ( token ) => {
 					token,
 					0
 				);
-				if ( potentialTypeAnnotation !== '' ) {
+				if ( potentialTypeAnnotation ) {
 					jsdoc.tags.push( {
 						tag: 'type',
 						type: potentialTypeAnnotation,

package/lib/get-type-annotation.js

@@ -397,7 +397,10 @@ function getFunctionToken( token ) {
 
 function getFunctionNameForError( declarationToken ) {
 	let namedFunctionToken = declarationToken;
-	if ( babelTypes.isExportNamedDeclaration( declarationToken ) ) {
+	if (
+		babelTypes.isExportNamedDeclaration( declarationToken ) ||
+		babelTypes.isExportDefaultDeclaration( declarationToken )
+	) {
 		namedFunctionToken = declarationToken.declaration;
 	}
 
@@ -451,7 +454,7 @@ 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.
- * @return {null | string} The parameter's type annotation.
+ * @return {string?} The parameter's type annotation.
  */
 function getParamTypeAnnotation( tag, declarationToken, paramIndex ) {
 	const functionToken = getFunctionToken( declarationToken );
@@ -469,58 +472,51 @@ function getParamTypeAnnotation( tag, declarationToken, paramIndex ) {
 		);
 	}
 
-	const isQualifiedName = tag.name.includes( '.' );
+	if ( babelTypes.isAssignmentPattern( paramToken ) ) {
+		paramToken = paramToken.left;
+	}
 
-	try {
-		if ( babelTypes.isAssignmentPattern( paramToken ) ) {
-			paramToken = paramToken.left;
-		}
+	if (
+		! paramToken.typeAnnotation ||
+		! paramToken.typeAnnotation.typeAnnotation
+	) {
+		return;
+	}
 
-		const paramType = paramToken.typeAnnotation.typeAnnotation;
+	const paramType = paramToken.typeAnnotation.typeAnnotation;
+	const isQualifiedName = tag.name.includes( '.' );
 
-		if (
-			babelTypes.isIdentifier( paramToken ) ||
-			babelTypes.isRestElement( paramToken ) ||
-			( ( babelTypes.isArrayPattern( paramToken ) ||
-				babelTypes.isObjectPattern( paramToken ) ) &&
-				! isQualifiedName )
-		) {
-			return getTypeAnnotation( paramType );
-		} else if ( babelTypes.isArrayPattern( paramToken ) ) {
-			return getQualifiedArrayPatternTypeAnnotation( tag, paramType );
-		} else if ( babelTypes.isObjectPattern( paramToken ) ) {
-			return getQualifiedObjectPatternTypeAnnotation( tag, paramType );
-		}
-	} catch ( e ) {
-		throw new Error(
-			`Could not find type for parameter '${
-				tag.name
-			}' in function '${ getFunctionNameForError( declarationToken ) }'.`
-		);
+	if (
+		babelTypes.isIdentifier( paramToken ) ||
+		babelTypes.isRestElement( paramToken ) ||
+		( ( babelTypes.isArrayPattern( paramToken ) ||
+			babelTypes.isObjectPattern( paramToken ) ) &&
+			! isQualifiedName )
+	) {
+		return getTypeAnnotation( paramType );
+	} else if ( babelTypes.isArrayPattern( paramToken ) ) {
+		return getQualifiedArrayPatternTypeAnnotation( tag, paramType );
+	} else if ( babelTypes.isObjectPattern( paramToken ) ) {
+		return getQualifiedObjectPatternTypeAnnotation( tag, paramType );
 	}
 }
 
 /**
  * @param {ASTNode} declarationToken A function token.
- * @return {null | string} The function's return type annoation.
+ * @return {string?} The function's return type annotation.
  */
 function getReturnTypeAnnotation( declarationToken ) {
 	const functionToken = getFunctionToken( declarationToken );
-
-	try {
-		return getTypeAnnotation( functionToken.returnType.typeAnnotation );
-	} catch ( e ) {
-		throw new Error(
-			`Could not find return type for function '${ getFunctionNameForError(
-				declarationToken
-			) }'.`
-		);
+	if ( ! functionToken.returnType ) {
+		return;
 	}
+
+	return getTypeAnnotation( functionToken.returnType.typeAnnotation );
 }
 
 /**
  * @param {ASTNode} declarationToken
- * @return {string} The type annotation for the variable.
+ * @return {string?} The type annotation for the variable.
  */
 function getVariableTypeAnnotation( declarationToken ) {
 	let resolvedToken = declarationToken;
@@ -541,7 +537,6 @@ function getVariableTypeAnnotation( declarationToken ) {
 		return getTypeAnnotation( resolvedToken.typeAnnotation.typeAnnotation );
 	} catch ( e ) {
 		// assume it's a fully undocumented variable, there's nothing we can do about that but fail silently.
-		return '';
 	}
 }
 
@@ -550,7 +545,7 @@ module.exports =
 	 * @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.
+	 * @return {[string]} The type annotation for the given tag or null if the tag has no type annotation.
 	 */
 	function ( tag, token, index ) {
 		// If the file is using JSDoc type annotations, use the JSDoc.
@@ -568,8 +563,5 @@ module.exports =
 			case 'type': {
 				return getVariableTypeAnnotation( token );
 			}
-			default: {
-				return '';
-			}
 		}
 	};

package/lib/markdown/formatter.js

@@ -18,7 +18,7 @@ const formatTag = ( title, tags, formatter, docs ) => {
 		docs.push( '\n' );
 		docs.push( `*${ title }*` );
 		docs.push( '\n' );
-		docs.push( ...tags.map( formatter ) );
+		docs.push( ...tags.map( ( tag ) => `\n${ formatter( tag ) }` ) );
 	}
 };
 
@@ -103,54 +103,88 @@ module.exports = (
 			formatTag(
 				'Related',
 				getSymbolTagsByName( symbol, 'see', 'link' ),
-				( tag ) =>
-					`\n- ${ tag.name.trim() }${
-						tag.description ? ' ' : ''
-					}${ tag.description.trim() }`,
+				( tag ) => {
+					const name = tag.name.trim();
+					const desc = tag.description.trim();
+
+					// prettier-ignore
+					return desc
+						? `- ${ name } ${ desc }`
+						: `- ${ name }`;
+				},
 				docs
 			);
 			formatExamples( getSymbolTagsByName( symbol, 'example' ), docs );
 			formatTag(
 				'Type',
 				getSymbolTagsByName( symbol, 'type' ),
-				( tag ) =>
-					`\n- ${ getTypeOutput( tag ) }${ cleanSpaces(
-						` ${ tag.name } ${ tag.description }`
-					) }`,
+				( tag ) => {
+					const type = tag.type && getTypeOutput( tag );
+					const desc = cleanSpaces(
+						`${ tag.name } ${ tag.description }`
+					);
+
+					// prettier-ignore
+					return type
+						? `- ${ type }${ desc }`
+						: `- ${ desc }`;
+				},
 				docs
 			);
 			formatTag(
 				'Parameters',
 				getSymbolTagsByName( symbol, 'param' ),
-				( tag ) =>
-					`\n- *${ tag.name }* ${ getTypeOutput(
-						tag
-					) }: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => {
+					const name = tag.name;
+					const type = tag.type && getTypeOutput( tag );
+					const desc = cleanSpaces( tag.description );
+
+					return type
+						? `- *${ name }* ${ type }: ${ desc }`
+						: `- *${ name }* ${ desc }`;
+				},
 				docs
 			);
 			formatTag(
 				'Returns',
 				getSymbolTagsByName( symbol, 'return' ),
 				( tag ) => {
-					return `\n- ${ getTypeOutput( tag ) }: ${ cleanSpaces(
+					const type = tag.type && getTypeOutput( tag );
+					const desc = cleanSpaces(
 						`${ tag.name } ${ tag.description }`
-					) }`;
+					);
+
+					// prettier-ignore
+					return type
+						? `- ${ type }: ${ desc }`
+						: `- ${ desc }`;
 				},
 				docs
 			);
 			formatTag(
 				'Type Definition',
 				getSymbolTagsByName( symbol, 'typedef' ),
-				( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag ) }`,
+				( tag ) => {
+					const name = tag.name;
+					const type = getTypeOutput( tag );
+
+					return `- *${ name }* ${ type }`;
+				},
 				docs
 			);
 			formatTag(
 				'Properties',
 				getSymbolTagsByName( symbol, 'property' ),
-				( tag ) =>
-					`\n- *${ tag.name }* ${ getTypeOutput(
-						tag
-					) }: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => {
+					const name = tag.name;
+					const type = tag.type && getTypeOutput( tag );
+					const desc = cleanSpaces( tag.description );
+
+					// prettier-ignore
+					return type
+						? `- *${ name }* ${ type }: ${ desc }`
+						: `- *${ name }* ${ desc }`
+				},
 				docs
 			);
 			docs.push( '\n' );

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/docgen",
-	"version": "1.18.2-next.33ec3857e2.0",
+	"version": "1.19.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": "51c7917ea7fac72953702f24d6daac87d99e7617"
+	"gitHead": "d95ccb9366e249133cdb1d7b25c382446b9ee502"
 }