Replace doctrine with comment-parser.

docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md

@@ -79,7 +79,7 @@ _Parameters_
 
 -   _state_ `Object`: Global state.
 -   _name_ `string`: Shortcut name.
--   _representation_ (unknown type): Type of representation (display, raw, ariaLabel).
+-   _representation_ `keyof FORMATTING_METHODS`: Type of representation (display, raw, ariaLabel).
 
 _Returns_
 

packages/block-editor/README.md

@@ -296,7 +296,7 @@ _Returns_
 <a name="getFontSize" href="#getFontSize">#</a> **getFontSize**
 
 Returns the font size object based on an array of named font sizes and the namedFontSize and customFontSize values.
-	If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned.
+If namedFontSize is undefined or not found in fontSizes an object with just the size value based on customFontSize is returned.
 
 _Parameters_
 

packages/docgen/package.json

@@ -23,7 +23,8 @@
 	},
 	"dependencies": {
 		"@babel/core": "^7.9.0",
-		"doctrine": "^2.1.0",
+		"comment-parser": "0.7.2",
+		"jsdoctypeparser": "6.1.0",
 		"lodash": "^4.17.15",
 		"mdast-util-inject": "1.1.0",
 		"optionator": "0.8.2",

packages/docgen/src/get-jsdoc-from-token.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies.
  */
-const doctrine = require( 'doctrine' );
+const parse = require( 'comment-parser' );
 
 /**
  * Internal dependencies.
@@ -19,19 +19,138 @@ const getTypeAsString = require( './get-type-as-string' );
  */
 module.exports = function( token ) {
 	let jsdoc;
-	const comments = getLeadingComments( token );
+	let comments = getLeadingComments( token );
 	if ( comments && /^\*\r?\n/.test( comments ) ) {
-		jsdoc = doctrine.parse( comments, {
-			unwrap: true,
-			recoverable: true,
-			sloppy: true,
-		} );
-		jsdoc.tags = jsdoc.tags.map( ( tag ) => {
-			if ( tag.type ) {
-				tag.type = getTypeAsString( tag.type );
+		comments = encodeWhitespacesInCode( comments );
+
+		// babel strips /* and */, but comment-parser requires it.
+		jsdoc = parse( `/*${ comments }\n*/` )[ 0 ];
+
+		jsdoc.description = decodeWhitespacesInCode( jsdoc.description );
+
+		delete jsdoc.line;
+		delete jsdoc.source;
+
+		jsdoc.tags = jsdoc.tags.map(
+			( { tag: title, name, type, description, optional } ) => {
+				const mergeNameAndDesc = () =>
+					`${ name } ${ description }`.trim();
+
+				if ( title === 'deprecated' ) {
+					return {
+						title,
+						description: mergeNameAndDesc(),
+					};
+				}
+
+				if ( title === 'see' ) {
+					return {
+						title,
+						description:
+							name.match( /https?:\/\// ) !== null
+								? `${ name }\n\n${ description }`.trim()
+								: mergeNameAndDesc(),
+					};
+				}
+
+				if ( title === 'since' ) {
+					return {
+						title,
+						version: name,
+						description,
+					};
+				}
+
+				if ( title === 'param' ) {
+					return {
+						title,
+						name,
+						description,
+						type: getTypeAsString( type, optional ),
+					};
+				}
+
+				if ( title === 'return' ) {
+					return {
+						title,
+						description: mergeNameAndDesc(),
+						type: getTypeAsString( type, optional ),
+					};
+				}
+
+				if ( title === 'type' ) {
+					return {
+						title,
+						description: mergeNameAndDesc(),
+						type: getTypeAsString( type, optional ),
+					};
+				}
+
+				if ( title === 'example' ) {
+					if ( name.match( /```.*/ ) !== null ) {
+						description = `${ name }\n${ description }`.trim();
+					} else if ( name.match( /<caption>.*/ ) !== null ) {
+						// do nothing
+					} else {
+						description = mergeNameAndDesc();
+					}
+
+					return {
+						title,
+						description: decodeWhitespacesInCode( description ),
+					};
+				}
+
+				if ( title === 'typedef' ) {
+					return {
+						title,
+						name,
+						type: getTypeAsString( type, optional ),
+						description,
+					};
+				}
+
+				if ( title === 'property' ) {
+					return {
+						title,
+						name,
+						type: getTypeAsString( type, optional ),
+						description,
+					};
+				}
+
+				return {
+					title,
+					description,
+				};
 			}
-			return tag;
-		} );
+		);
 	}
 	return jsdoc;
 };
+
+const codeRegex = /```.*\n[\s\S]*```/g;
+const CODE_TAB = '__CODE_TAB__';
+const CODE_SPACE = '__CODE_SPACE__';
+
+const encodeWhitespacesInCode = ( comments ) => {
+	return comments.replace( codeRegex, ( m0 ) => {
+		return m0.replace( /\n \*[ \t][ \t]+/g, ( m1 ) => {
+			return (
+				'\n * ' +
+				m1
+					.substring( 4 )
+					.replace( /\t/g, CODE_TAB )
+					.replace( / /g, CODE_SPACE )
+			);
+		} );
+	} );
+};
+
+const decodeWhitespacesInCode = ( description ) => {
+	return description.replace( codeRegex, ( m0 ) => {
+		return m0
+			.replace( new RegExp( CODE_TAB, 'g' ), '\t' )
+			.replace( new RegExp( CODE_SPACE, 'g' ), ' ' );
+	} );
+};

packages/docgen/src/get-type-as-string.js

@@ -1,47 +1,63 @@
-const maybeAddDefault = function( value, defaultValue ) {
-	if ( defaultValue ) {
-		return `value=${ defaultValue }`;
+const { parse } = require( 'jsdoctypeparser' );
+
+const getType = ( ast, typeString, noUnionParenthesis ) => {
+	if ( ast.type === 'NAME' ) {
+		return ast.name;
+	}
+
+	if ( ast.type === 'ANY' ) {
+		return '*';
+	}
+
+	if ( ast.type === 'GENERIC' ) {
+		const types = ast.objects.map( ( o ) => getType( o ) ).join( ',' );
+		return `${ getType( ast.subject ) }<${ types }>`;
 	}
-	return value;
-};
 
-const getType = function( param, defaultValue ) {
-	if ( ! defaultValue ) {
-		defaultValue = param.default;
-	}
-
-	if ( param.type.type ) {
-		return getType( param.type, defaultValue );
-	} else if ( param.expression ) {
-		if ( param.type === 'RestType' ) {
-			return `...${ getType( param.expression, defaultValue ) }`;
-		} else if ( param.type === 'NullableType' ) {
-			return `?${ getType( param.expression, defaultValue ) }`;
-		} else if ( param.type === 'TypeApplication' ) {
-			return `${ getType(
-				param.expression,
-				defaultValue
-			) }<${ param.applications
-				.map( ( application ) => getType( application ) )
-				.join( ',' ) }>`;
-		} else if ( param.type === 'OptionalType' ) {
-			return `[${ getType( param.expression, defaultValue ) }]`;
-		}
-		return getType( param.expression, defaultValue );
-	} else if ( param.elements ) {
-		const types = param.elements.map( ( element ) => getType( element ) );
-		return maybeAddDefault( `(${ types.join( '|' ) })`, defaultValue );
-	} else if ( param.type === 'AllLiteral' ) {
-		return maybeAddDefault( '*', defaultValue );
-	} else if ( param.type === 'NullLiteral' ) {
-		return maybeAddDefault( 'null', defaultValue );
-	} else if ( param.type === 'UndefinedLiteral' ) {
-		return maybeAddDefault( 'undefined', defaultValue );
-	}
-
-	return maybeAddDefault( param.name, defaultValue );
+	if ( ast.type === 'NULLABLE' ) {
+		return `?${ getType( ast.value ) }`;
+	}
+
+	if ( ast.type === 'VARIADIC' ) {
+		return `...${ getType( ast.value ) }`;
+	}
+
+	if ( ast.type === 'UNION' ) {
+		const left = getType( ast.left );
+		const right = getType( ast.right, null, true );
+		const type = `${ left }|${ right }`;
+
+		return noUnionParenthesis ? type : `(${ type })`;
+	}
+
+	if ( ast.type === 'PARENTHESIS' ) {
+		const type = getType( ast.value );
+		return type[ 0 ] === '(' && type[ type.length - 1 ] === ')'
+			? type
+			: `(${ type })`;
+	}
+
+	if ( ast.type === 'OPTIONAL' ) {
+		return `[${ getType( ast.value ) }]`;
+	}
+
+	if ( ast.type === 'MEMBER' && ast.owner.type === 'IMPORT' ) {
+		return `${ ast.name }`;
+	}
+
+	return typeString || 'unknown type';
 };
 
-module.exports = function( param ) {
-	return getType( param );
+module.exports = function( typeString, optional ) {
+	let ast;
+
+	try {
+		ast = parse( typeString );
+	} catch {
+		return 'unknown type';
+	}
+
+	const type = getType( ast, typeString );
+
+	return optional ? `[${ type }]` : type;
 };

packages/docgen/src/test/fixtures/default-parse-error/exports.json

@@ -1 +1 @@
-[{"type":"ExportDefaultDeclaration","start":173,"end":288,"loc":{"start":{"line":7,"column":0},"end":{"line":9,"column":1}},"range":[173,288],"declaration":{"type":"FunctionDeclaration","start":188,"end":288,"loc":{"start":{"line":7,"column":15},"end":{"line":9,"column":1}},"range":[188,288],"id":{"type":"Identifier","start":197,"end":221,"loc":{"start":{"line":7,"column":24},"end":{"line":7,"column":48}},"range":[197,221],"name":"invokeCallbackAfterDelay"},"generator":false,"expression":false,"async":false,"params":[{"type":"Identifier","start":223,"end":231,"loc":{"start":{"line":7,"column":50},"end":{"line":7,"column":58}},"range":[223,231],"name":"callback"}],"body":{"type":"BlockStatement","start":234,"end":288,"loc":{"start":{"line":7,"column":61},"end":{"line":9,"column":1}},"range":[234,288],"body":[{"type":"ExpressionStatement","start":237,"end":286,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":50}},"range":[237,286],"expression":{"type":"CallExpression","start":237,"end":285,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":49}},"range":[237,285],"callee":{"type":"Identifier","start":237,"end":247,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":11}},"range":[237,247],"name":"setTimeout"},"arguments":[{"type":"ArrowFunctionExpression","start":249,"end":277,"loc":{"start":{"line":8,"column":13},"end":{"line":8,"column":41}},"range":[249,277],"id":null,"generator":false,"expression":true,"async":false,"params":[],"body":{"type":"CallExpression","start":255,"end":277,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":41}},"range":[255,277],"callee":{"type":"Identifier","start":255,"end":263,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":27}},"range":[255,263],"name":"callback"},"arguments":[{"type":"CallExpression","start":265,"end":275,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":39}},"range":[265,275],"callee":{"type":"MemberExpression","start":265,"end":273,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":37}},"range":[265,273],"object":{"type":"Identifier","start":265,"end":269,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":33}},"range":[265,269],"name":"Date"},"property":{"type":"Identifier","start":270,"end":273,"loc":{"start":{"line":8,"column":34},"end":{"line":8,"column":37}},"range":[270,273],"name":"now"},"computed":false},"arguments":[]}]}},{"type":"Literal","start":279,"end":283,"loc":{"start":{"line":8,"column":43},"end":{"line":8,"column":47}},"range":[279,283],"value":1000,"raw":"1000"}]}}]}},"leadingComments":[{"type":"Block","value":"*\n * Function invoking callback after delay with current timestamp in milliseconds\n * since epoch.\n *\n * @param {(timestamp:number)=>void} callback Callback function.\n ","start":0,"end":172,"range":[0,172],"loc":{"start":{"line":1,"column":0},"end":{"line":6,"column":3}}}]}]
+[{"type":"ExportDefaultDeclaration","start":173,"end":288,"loc":{"start":{"line":7,"column":0},"end":{"line":9,"column":1}},"range":[173,288],"declaration":{"type":"FunctionDeclaration","start":188,"end":288,"loc":{"start":{"line":7,"column":15},"end":{"line":9,"column":1}},"range":[188,288],"id":{"type":"Identifier","start":197,"end":221,"loc":{"start":{"line":7,"column":24},"end":{"line":7,"column":48}},"range":[197,221],"name":"invokeCallbackAfterDelay"},"generator":false,"expression":false,"async":false,"params":[{"type":"Identifier","start":223,"end":231,"loc":{"start":{"line":7,"column":50},"end":{"line":7,"column":58}},"range":[223,231],"name":"callback"}],"body":{"type":"BlockStatement","start":234,"end":288,"loc":{"start":{"line":7,"column":61},"end":{"line":9,"column":1}},"range":[234,288],"body":[{"type":"ExpressionStatement","start":237,"end":286,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":50}},"range":[237,286],"expression":{"type":"CallExpression","start":237,"end":285,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":49}},"range":[237,285],"callee":{"type":"Identifier","start":237,"end":247,"loc":{"start":{"line":8,"column":1},"end":{"line":8,"column":11}},"range":[237,247],"name":"setTimeout"},"arguments":[{"type":"ArrowFunctionExpression","start":249,"end":277,"loc":{"start":{"line":8,"column":13},"end":{"line":8,"column":41}},"range":[249,277],"id":null,"generator":false,"expression":true,"async":false,"params":[],"body":{"type":"CallExpression","start":255,"end":277,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":41}},"range":[255,277],"callee":{"type":"Identifier","start":255,"end":263,"loc":{"start":{"line":8,"column":19},"end":{"line":8,"column":27}},"range":[255,263],"name":"callback"},"arguments":[{"type":"CallExpression","start":265,"end":275,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":39}},"range":[265,275],"callee":{"type":"MemberExpression","start":265,"end":273,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":37}},"range":[265,273],"object":{"type":"Identifier","start":265,"end":269,"loc":{"start":{"line":8,"column":29},"end":{"line":8,"column":33}},"range":[265,269],"name":"Date"},"property":{"type":"Identifier","start":270,"end":273,"loc":{"start":{"line":8,"column":34},"end":{"line":8,"column":37}},"range":[270,273],"name":"now"},"computed":false},"arguments":[]}]}},{"type":"Literal","start":279,"end":283,"loc":{"start":{"line":8,"column":43},"end":{"line":8,"column":47}},"range":[279,283],"value":1000,"raw":"1000"}]}}]}},"leadingComments":[{"type":"Block","value":"*\n * Function invoking callback after delay with current timestamp in milliseconds\n * since epoch.\n *\n * @param {A&B} callback Callback function.\n ","start":0,"end":172,"range":[0,172],"loc":{"start":{"line":1,"column":0},"end":{"line":6,"column":3}}}]}]

packages/docgen/src/test/get-intermediate-representation.js

@@ -70,10 +70,9 @@ describe( 'Intermediate Representation', function() {
 			tags: [
 				{
 					description: 'Callback function.',
-					errors: [ 'unexpected token' ],
 					name: 'callback',
 					title: 'param',
-					type: null,
+					type: 'unknown type',
 				},
 			],
 			lineStart: 7,