docgen: Omit unknown type tag from Markdown format output (#19571)

* docgen: Omit unknown type tag from Markdown format output * Docs: Regenerate keyboard shortcuts documentation * docgen: Output "unknown type" for unknown type * Docs: Regenerate keyboard shortcuts documentation * docgen: Add space before "unknown type" * Docs: Regenerate keyboard shortcuts documentation * docgen: Update Markdown formatter tests for unknown type output * docgen: Render unknown types consistently in all output * Docs: Regenerate documentation for unknown types * docgen: Update CHANGELOG to reflect latest implementation
WordPress · Jan 16, 2020 · 669549a · 669549a
1 parent 9c5c691
commit 669549a
Show file tree

Hide file tree

Showing 10 changed files with 100 additions and 8 deletions.
diff --git a/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md b/docs/designers-developers/developers/data/data-core-keyboard-shortcuts.md
@@ -66,7 +66,7 @@ _Parameters_
 
 -   _state_ `Object`: Global state.
 -   _name_ `string`: Shortcut name.
--   _representation_ `null`: Type of representation (display, raw, ariaLabel).
+-   _representation_ (unknown type): Type of representation (display, raw, ariaLabel).
 
 _Returns_
 

diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md
@@ -166,7 +166,7 @@ _Parameters_
 
 _Returns_
 
--   `null`: The map of edited records with their edits.
+-   (unknown type): The map of edited records with their edits.
 
 <a name="getEntityRecordEdits" href="#getEntityRecordEdits">#</a> **getEntityRecordEdits**
 

diff --git a/packages/core-data/README.md b/packages/core-data/README.md
@@ -379,7 +379,7 @@ _Parameters_
 
 _Returns_
 
--   `null`: The map of edited records with their edits.
+-   (unknown type): The map of edited records with their edits.
 
 <a name="getEntityRecordEdits" href="#getEntityRecordEdits">#</a> **getEntityRecordEdits**
 

diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md
@@ -1,3 +1,9 @@
+## Master
+
+### Bug Fixes
+
+- The built-in Markdown formatter will output text indicating that the type is unknown if a type cannot be parsed. Previously, these would be output wrongly as the `null` type.
+
 ## 1.3.0 (2019-08-05)
 
 ### Bug Fixes

diff --git a/packages/docgen/src/markdown/formatter.js b/packages/docgen/src/markdown/formatter.js
@@ -59,6 +59,10 @@ const getSymbolHeading = ( text ) => {
 	return `<a name="${ text }" href="#${ text }">#</a> **${ text }**`;
 };
 
+const getTypeOutput = ( type ) => {
+	return type ? `\`${ type }\`` : '(unknown type)';
+};
+
 module.exports = function( rootDir, docPath, symbols, headingTitle, headingStartIndex ) {
 	const docs = [];
 	let headingIndex = headingStartIndex || 1;
@@ -94,31 +98,31 @@ module.exports = function( rootDir, docPath, symbols, headingTitle, headingStart
 			formatTag(
 				'Type',
 				getSymbolTagsByName( symbol, 'type' ),
-				( tag ) => `\n- \`${ tag.type }\` ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n- ${ getTypeOutput( tag.type ) } ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			formatTag(
 				'Parameters',
 				getSymbolTagsByName( symbol, 'param' ),
-				( tag ) => `\n- *${ tag.name }* \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag.type ) }: ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			formatTag(
 				'Returns',
 				getSymbolTagsByName( symbol, 'return' ),
-				( tag ) => `\n- \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n- ${ getTypeOutput( tag.type ) }: ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			formatTag(
 				'Type Definition',
 				getSymbolTagsByName( symbol, 'typedef' ),
-				( tag ) => `\n- *${ tag.name }* \`${ tag.type }\``,
+				( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag.type ) }`,
 				docs
 			);
 			formatTag(
 				'Properties',
 				getSymbolTagsByName( symbol, 'property' ),
-				( tag ) => `\n- *${ tag.name }* \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n- *${ tag.name }* ${ getTypeOutput( tag.type ) }: ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			docs.push( '\n' );

diff --git a/packages/docgen/src/test/fixtures/default-parse-error/code.js b/packages/docgen/src/test/fixtures/default-parse-error/code.js
@@ -0,0 +1,9 @@
+/**
+ * Function invoking callback after delay with current timestamp in milliseconds
+ * since epoch.
+ *
+ * @param {(timestamp:number)=>void} callback Callback function.
+ */
+export default function invokeCallbackAfterDelay( callback ) {
+	setTimeout( () => callback( Date.now() ), 1000 );
+}
diff --git a/packages/docgen/src/test/fixtures/default-parse-error/exports.json b/packages/docgen/src/test/fixtures/default-parse-error/exports.json
@@ -0,0 +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}}}]}]
diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js
@@ -31,4 +31,28 @@ describe( 'Formatter', () => {
 			'# API docs\n\n<a name="myDeclaration" href="#myDeclaration">#</a> **myDeclaration**\n\nMy declaration example.\n\n*Parameters*\n\n- *firstParam* `number`: First declaration parameter.\n\n*Returns*\n\n- `number`: The result of the declaration.\n'
 		);
 	} );
+
+	it( 'handles unknown types from parse error', () => {
+		const rootDir = '/home/my-path';
+		const docPath = '/home/my-path/docs';
+		const docs = formatter( rootDir, docPath + '-api.md', [ {
+			path: null,
+			name: 'default',
+			description: 'Function invoking callback after delay with current timestamp in milliseconds\nsince epoch.',
+			tags: [
+				{
+					description: 'Callback function.',
+					errors: [ 'unexpected token' ],
+					name: 'callback',
+					title: 'param',
+					type: null,
+				},
+			],
+			lineStart: 7,
+			lineEnd: 9,
+		} ], 'API docs' );
+		expect( docs ).toBe(
+			'# API docs\n\n<a name="default" href="#default">#</a> **default**\n\nFunction invoking callback after delay with current timestamp in milliseconds\nsince epoch.\n\n*Parameters*\n\n- *callback* (unknown type): Callback function.\n'
+		);
+	} );
 } );
diff --git a/packages/docgen/src/test/get-intermediate-representation.js b/packages/docgen/src/test/get-intermediate-representation.js
@@ -41,6 +41,31 @@ describe( 'Intermediate Representation', function() {
 		} );
 	} );
 
+	it( 'type parse error handling', () => {
+		const token = JSON.parse( fs.readFileSync(
+			path.join( __dirname, './fixtures/default-parse-error/exports.json' ),
+			'utf-8'
+		) )[ 0 ];
+		const ir = getIntermediateRepresentation( null, token );
+		expect( ir ).toHaveLength( 1 );
+		expect( ir[ 0 ] ).toEqual( {
+			path: null,
+			name: 'default',
+			description: 'Function invoking callback after delay with current timestamp in milliseconds\nsince epoch.',
+			tags: [
+				{
+					description: 'Callback function.',
+					errors: [ 'unexpected token' ],
+					name: 'callback',
+					title: 'param',
+					type: null,
+				},
+			],
+			lineStart: 7,
+			lineEnd: 9,
+		} );
+	} );
+
 	describe( 'JSDoc in export statement', function() {
 		it( 'default export', function() {
 			const tokenClassAnonymous = fs.readFileSync(

diff --git a/packages/docgen/src/test/get-jsdoc-from-token.js b/packages/docgen/src/test/get-jsdoc-from-token.js
@@ -74,5 +74,28 @@ describe( 'JSDoc', () => {
 				],
 			}
 		);
+
+		expect(
+			getJSDocFromToken( {
+				leadingComments: [ {
+					value: '*\n * Function invoking callback after delay with current timestamp in milliseconds since epoch.\n * @param {(timestamp:number)=>void} callback Callback function.\n ',
+				} ],
+			} )
+		).toEqual(
+			{
+				description: 'Function invoking callback after delay with current timestamp in milliseconds since epoch.',
+				tags: [
+					{
+						title: 'param',
+						errors: [
+							'unexpected token',
+						],
+						description: 'Callback function.',
+						name: 'callback',
+						type: null,
+					},
+				],
+			}
+		);
 	} );
 } );