From 0a6b23ccb3cddd4de054ea1117ea8ad9dc2c24dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 15 Jan 2019 12:31:20 +0100
Subject: [PATCH 001/213] First, find export declarations

---
 docs/tool/api.js                  | 43 +++++++++++++++++++++++++++++++
 docs/tool/get-name-declaration.js | 28 ++++++++++++++++++++
 docs/tool/goal.md                 | 19 ++++++++++++++
 3 files changed, 90 insertions(+)
 create mode 100644 docs/tool/api.js
 create mode 100644 docs/tool/get-name-declaration.js
 create mode 100644 docs/tool/goal.md

diff --git a/docs/tool/api.js b/docs/tool/api.js
new file mode 100644
index 00000000000000..b14b888b4c78ee
--- /dev/null
+++ b/docs/tool/api.js
@@ -0,0 +1,43 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * External dependencies.
+ */
+const { last } = require( 'lodash' );
+const espree = require( 'espree' );
+// const doctrine = require( 'doctrine' );
+
+/**
+ * Internal dependencies.
+ */
+const getNameDeclaration = require( './get-name-declaration' );
+
+const root = path.resolve( __dirname, '../../' );
+const input = path.resolve( root, 'packages/i18n/src/index.js' );
+const outputTmp = path.resolve( root, 'packages/i18n/src/ast.json' );
+const output = path.resolve( root, 'packages/i18n/src/api.json' );
+
+const code = fs.readFileSync( input, 'utf8' );
+const ast = espree.parse( code, {
+	attachComment: true,
+	ecmaVersion: 2018,
+	sourceType: 'module',
+} );
+
+const exportDeclarations = ast.body.filter(
+	( node ) => [ 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration' ].some( ( declaration ) => declaration === node.type )
+);
+
+const apiArtifacts = exportDeclarations.map(
+	( exportDeclaration ) => ( {
+		name: getNameDeclaration( exportDeclaration.declaration ),
+		jsdoc: last( exportDeclaration.leadingComments ).value,
+	} )
+);
+
+fs.writeFileSync( outputTmp, JSON.stringify( exportDeclarations ) );
+fs.writeFileSync( output, JSON.stringify( apiArtifacts ) );
diff --git a/docs/tool/get-name-declaration.js b/docs/tool/get-name-declaration.js
new file mode 100644
index 00000000000000..8fae5e8b899869
--- /dev/null
+++ b/docs/tool/get-name-declaration.js
@@ -0,0 +1,28 @@
+/**
+ * External dependencies
+ */
+const { first } = require( 'lodash' );
+
+/**
+ * Returns the assigned name for a given declaration node type, or undefined if
+ * it cannot be determined.
+ *
+ * @param {Object} declaration Declaration node.
+ *
+ * @return {?string} Exported declaration name.
+ */
+module.exports = function( declaration ) {
+	let declarator;
+	switch ( declaration.type ) {
+		case 'FunctionDeclaration':
+			declarator = declaration;
+			break;
+
+		case 'VariableDeclaration':
+			declarator = first( declaration.declarations );
+	}
+
+	if ( declarator ) {
+		return declarator.id.name;
+	}
+};
diff --git a/docs/tool/goal.md b/docs/tool/goal.md
new file mode 100644
index 00000000000000..885e3a51bf13d4
--- /dev/null
+++ b/docs/tool/goal.md
@@ -0,0 +1,19 @@
+# «X» API
+
+## «API_ARTIFACT»
+
+_Introduced in «SINCE_DESCRIPTION»._
+
+«JSDOC_DESCRIPTION»
+
+**Parameters**
+
+- «PARAMETER_DESCRIPTION»
+
+**Returns**
+
+«RETURN_DESCRIPTION»
+
+**Examples**
+
+«EXAMPLES_DESCRIPTION»

From 81d4b78fe88e0fb5ab95c03e5a2f19121cc3e461 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 15 Jan 2019 12:35:33 +0100
Subject: [PATCH 002/213] Second, parse JSDoc

---
 docs/tool/api.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/tool/api.js b/docs/tool/api.js
index b14b888b4c78ee..8832df962571e5 100644
--- a/docs/tool/api.js
+++ b/docs/tool/api.js
@@ -9,7 +9,7 @@ const path = require( 'path' );
  */
 const { last } = require( 'lodash' );
 const espree = require( 'espree' );
-// const doctrine = require( 'doctrine' );
+const doctrine = require( 'doctrine' );
 
 /**
  * Internal dependencies.
@@ -35,7 +35,10 @@ const exportDeclarations = ast.body.filter(
 const apiArtifacts = exportDeclarations.map(
 	( exportDeclaration ) => ( {
 		name: getNameDeclaration( exportDeclaration.declaration ),
-		jsdoc: last( exportDeclaration.leadingComments ).value,
+		jsdoc: doctrine.parse(
+			last( exportDeclaration.leadingComments ).value,
+			{ unwrap: true, recoverable: true }
+		),
 	} )
 );
 

From c5ad30714898ce8510c826096c93df11e4319846 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 15 Jan 2019 12:55:41 +0100
Subject: [PATCH 003/213] Third, create markdown files with exports and JDoc
 descriptions.

---
 docs/tool/api.js | 26 ++++++++++++++++++++++----
 1 file changed, 22 insertions(+), 4 deletions(-)

diff --git a/docs/tool/api.js b/docs/tool/api.js
index 8832df962571e5..ab5d14af48c1ba 100644
--- a/docs/tool/api.js
+++ b/docs/tool/api.js
@@ -18,8 +18,9 @@ const getNameDeclaration = require( './get-name-declaration' );
 
 const root = path.resolve( __dirname, '../../' );
 const input = path.resolve( root, 'packages/i18n/src/index.js' );
-const outputTmp = path.resolve( root, 'packages/i18n/src/ast.json' );
-const output = path.resolve( root, 'packages/i18n/src/api.json' );
+const outputExportDeclarations = path.resolve( root, 'packages/i18n/src/ast.json' );
+const outputApiArtifacts = path.resolve( root, 'packages/i18n/src/api.json' );
+const output = path.resolve( root, 'packages/i18n/src/api.md' );
 
 const code = fs.readFileSync( input, 'utf8' );
 const ast = espree.parse( code, {
@@ -42,5 +43,22 @@ const apiArtifacts = exportDeclarations.map(
 	} )
 );
 
-fs.writeFileSync( outputTmp, JSON.stringify( exportDeclarations ) );
-fs.writeFileSync( output, JSON.stringify( apiArtifacts ) );
+const generateDocs = function( artifacts ) {
+	const docs = [ '# API' ];
+	docs.push( '\n' );
+	docs.push( '\n' );
+	artifacts.forEach( ( artifact ) => {
+		docs.push( `## ${ artifact.name }` );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( artifact.jsdoc.description.replace( '\n', ' ' ) );
+		docs.push( '\n' );
+		docs.push( '\n' );
+	} );
+	docs.pop(); // remove last \n, we want one blank line at the end of the file.
+	return docs.join( '' );
+};
+
+fs.writeFileSync( outputExportDeclarations, JSON.stringify( exportDeclarations ) );
+fs.writeFileSync( outputApiArtifacts, JSON.stringify( apiArtifacts ) );
+fs.writeFileSync( output, generateDocs( apiArtifacts ) );

From 16c178c0d392bc32c11be2965f738e42b7e9b5bd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 11:03:52 +0100
Subject: [PATCH 004/213] Refactor and prevent against no JSDoc

---
 docs/tool/api.js                  | 13 +++++++------
 docs/tool/get-leading-comments.js | 11 +++++++++++
 2 files changed, 18 insertions(+), 6 deletions(-)
 create mode 100644 docs/tool/get-leading-comments.js

diff --git a/docs/tool/api.js b/docs/tool/api.js
index ab5d14af48c1ba..59f77db64d6bf4 100644
--- a/docs/tool/api.js
+++ b/docs/tool/api.js
@@ -7,7 +7,6 @@ const path = require( 'path' );
 /**
  * External dependencies.
  */
-const { last } = require( 'lodash' );
 const espree = require( 'espree' );
 const doctrine = require( 'doctrine' );
 
@@ -15,12 +14,14 @@ const doctrine = require( 'doctrine' );
  * Internal dependencies.
  */
 const getNameDeclaration = require( './get-name-declaration' );
+const getLeadingComments = require( './get-leading-comments' );
 
+const packageName = 'dom-ready';
 const root = path.resolve( __dirname, '../../' );
-const input = path.resolve( root, 'packages/i18n/src/index.js' );
-const outputExportDeclarations = path.resolve( root, 'packages/i18n/src/ast.json' );
-const outputApiArtifacts = path.resolve( root, 'packages/i18n/src/api.json' );
-const output = path.resolve( root, 'packages/i18n/src/api.md' );
+const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
+const outputExportDeclarations = path.resolve( root, `packages/${ packageName }/src/doc-ast.json` );
+const outputApiArtifacts = path.resolve( root, `packages/${ packageName }/src/doc-api.json` );
+const output = path.resolve( root, `packages/${ packageName }/src/doc-api.md` );
 
 const code = fs.readFileSync( input, 'utf8' );
 const ast = espree.parse( code, {
@@ -37,7 +38,7 @@ const apiArtifacts = exportDeclarations.map(
 	( exportDeclaration ) => ( {
 		name: getNameDeclaration( exportDeclaration.declaration ),
 		jsdoc: doctrine.parse(
-			last( exportDeclaration.leadingComments ).value,
+			getLeadingComments( exportDeclaration ),
 			{ unwrap: true, recoverable: true }
 		),
 	} )
diff --git a/docs/tool/get-leading-comments.js b/docs/tool/get-leading-comments.js
new file mode 100644
index 00000000000000..e1e0b1e3dea831
--- /dev/null
+++ b/docs/tool/get-leading-comments.js
@@ -0,0 +1,11 @@
+/**
+ * External dependencies.
+ */
+const { last } = require( 'lodash' );
+
+module.exports = function( declaration ) {
+	if ( declaration.leadingComments ) {
+		return last( declaration.leadingComments ).value;
+	}
+	return '*\n * Undocumented declaration\n ';
+};

From 9ee1aea6e540e60142313676bf087abc3f809332 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 11:41:36 +0100
Subject: [PATCH 005/213] Move script to own package

---
 packages/docgen/.npmrc                        |  1 +
 packages/docgen/CHANGELOG.md                  |  3 +++
 packages/docgen/README.md                     | 11 ++++++++
 packages/docgen/package.json                  | 26 +++++++++++++++++++
 {docs/tool => packages/docgen/src}/api.js     |  4 +--
 .../docgen/src}/get-leading-comments.js       |  0
 .../docgen/src}/get-name-declaration.js       |  0
 7 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 packages/docgen/.npmrc
 create mode 100644 packages/docgen/CHANGELOG.md
 create mode 100644 packages/docgen/README.md
 create mode 100644 packages/docgen/package.json
 rename {docs/tool => packages/docgen/src}/api.js (96%)
 rename {docs/tool => packages/docgen/src}/get-leading-comments.js (100%)
 rename {docs/tool => packages/docgen/src}/get-name-declaration.js (100%)

diff --git a/packages/docgen/.npmrc b/packages/docgen/.npmrc
new file mode 100644
index 00000000000000..43c97e719a5a82
--- /dev/null
+++ b/packages/docgen/.npmrc
@@ -0,0 +1 @@
+package-lock=false
diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md
new file mode 100644
index 00000000000000..c90df3c7488eca
--- /dev/null
+++ b/packages/docgen/CHANGELOG.md
@@ -0,0 +1,3 @@
+## 1.0.0 (next)
+
+TBD
diff --git a/packages/docgen/README.md b/packages/docgen/README.md
new file mode 100644
index 00000000000000..ac08fc04e67a17
--- /dev/null
+++ b/packages/docgen/README.md
@@ -0,0 +1,11 @@
+# `docgen`
+
+> TODO: description
+
+## Usage
+
+```
+const docgen = require('docgen');
+
+// TODO: DEMONSTRATE API
+```
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
new file mode 100644
index 00000000000000..745c023e5e8f41
--- /dev/null
+++ b/packages/docgen/package.json
@@ -0,0 +1,26 @@
+{
+	"name": "docgen",
+	"version": "1.0.0",
+	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"jsdoc",
+		"documentation"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/WordPress/gutenberg.git"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"main": "src/index.js",
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "echo \"Error: run tests from root\" && exit 1"
+	}
+}
diff --git a/docs/tool/api.js b/packages/docgen/src/api.js
similarity index 96%
rename from docs/tool/api.js
rename to packages/docgen/src/api.js
index 59f77db64d6bf4..92b7dadaeb5d10 100644
--- a/docs/tool/api.js
+++ b/packages/docgen/src/api.js
@@ -16,8 +16,8 @@ const doctrine = require( 'doctrine' );
 const getNameDeclaration = require( './get-name-declaration' );
 const getLeadingComments = require( './get-leading-comments' );
 
-const packageName = 'dom-ready';
-const root = path.resolve( __dirname, '../../' );
+const packageName = 'i18n';
+const root = path.resolve( __dirname, '../../../' );
 const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
 const outputExportDeclarations = path.resolve( root, `packages/${ packageName }/src/doc-ast.json` );
 const outputApiArtifacts = path.resolve( root, `packages/${ packageName }/src/doc-api.json` );
diff --git a/docs/tool/get-leading-comments.js b/packages/docgen/src/get-leading-comments.js
similarity index 100%
rename from docs/tool/get-leading-comments.js
rename to packages/docgen/src/get-leading-comments.js
diff --git a/docs/tool/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
similarity index 100%
rename from docs/tool/get-name-declaration.js
rename to packages/docgen/src/get-name-declaration.js

From 4e6b22b7912a8d98aee9ec81d5d9f2c0285127f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 12:55:41 +0100
Subject: [PATCH 006/213] Split api into cli, engine, and formatter

---
 packages/docgen/src/api.js       | 65 --------------------------------
 packages/docgen/src/cli.js       | 22 +++++++++++
 packages/docgen/src/engine.js    | 35 +++++++++++++++++
 packages/docgen/src/formatter.js | 15 ++++++++
 4 files changed, 72 insertions(+), 65 deletions(-)
 delete mode 100644 packages/docgen/src/api.js
 create mode 100644 packages/docgen/src/cli.js
 create mode 100644 packages/docgen/src/engine.js
 create mode 100644 packages/docgen/src/formatter.js

diff --git a/packages/docgen/src/api.js b/packages/docgen/src/api.js
deleted file mode 100644
index 92b7dadaeb5d10..00000000000000
--- a/packages/docgen/src/api.js
+++ /dev/null
@@ -1,65 +0,0 @@
-/**
- * Node dependencies.
- */
-const fs = require( 'fs' );
-const path = require( 'path' );
-
-/**
- * External dependencies.
- */
-const espree = require( 'espree' );
-const doctrine = require( 'doctrine' );
-
-/**
- * Internal dependencies.
- */
-const getNameDeclaration = require( './get-name-declaration' );
-const getLeadingComments = require( './get-leading-comments' );
-
-const packageName = 'i18n';
-const root = path.resolve( __dirname, '../../../' );
-const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
-const outputExportDeclarations = path.resolve( root, `packages/${ packageName }/src/doc-ast.json` );
-const outputApiArtifacts = path.resolve( root, `packages/${ packageName }/src/doc-api.json` );
-const output = path.resolve( root, `packages/${ packageName }/src/doc-api.md` );
-
-const code = fs.readFileSync( input, 'utf8' );
-const ast = espree.parse( code, {
-	attachComment: true,
-	ecmaVersion: 2018,
-	sourceType: 'module',
-} );
-
-const exportDeclarations = ast.body.filter(
-	( node ) => [ 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration' ].some( ( declaration ) => declaration === node.type )
-);
-
-const apiArtifacts = exportDeclarations.map(
-	( exportDeclaration ) => ( {
-		name: getNameDeclaration( exportDeclaration.declaration ),
-		jsdoc: doctrine.parse(
-			getLeadingComments( exportDeclaration ),
-			{ unwrap: true, recoverable: true }
-		),
-	} )
-);
-
-const generateDocs = function( artifacts ) {
-	const docs = [ '# API' ];
-	docs.push( '\n' );
-	docs.push( '\n' );
-	artifacts.forEach( ( artifact ) => {
-		docs.push( `## ${ artifact.name }` );
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( artifact.jsdoc.description.replace( '\n', ' ' ) );
-		docs.push( '\n' );
-		docs.push( '\n' );
-	} );
-	docs.pop(); // remove last \n, we want one blank line at the end of the file.
-	return docs.join( '' );
-};
-
-fs.writeFileSync( outputExportDeclarations, JSON.stringify( exportDeclarations ) );
-fs.writeFileSync( outputApiArtifacts, JSON.stringify( apiArtifacts ) );
-fs.writeFileSync( output, generateDocs( apiArtifacts ) );
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
new file mode 100644
index 00000000000000..50311300aff9fa
--- /dev/null
+++ b/packages/docgen/src/cli.js
@@ -0,0 +1,22 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies.
+ */
+const engine = require( './engine' );
+const formatter = require( './formatter' );
+
+const packageName = 'i18n';
+const root = path.resolve( __dirname, '../../../' );
+const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
+const output = path.resolve( root, `packages/${ packageName }/src/doc-api.md` );
+
+const code = fs.readFileSync( input, 'utf8' );
+const json = engine( code );
+const docs = formatter( json );
+
+fs.writeFileSync( output, docs );
diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
new file mode 100644
index 00000000000000..86e4347d268a01
--- /dev/null
+++ b/packages/docgen/src/engine.js
@@ -0,0 +1,35 @@
+/**
+* External dependencies.
+*/
+const espree = require( 'espree' );
+const doctrine = require( 'doctrine' );
+
+/**
+* Internal dependencies.
+*/
+const getNameDeclaration = require( './get-name-declaration' );
+const getLeadingComments = require( './get-leading-comments' );
+
+module.exports = function( code ) {
+	const ast = espree.parse( code, {
+		attachComment: true,
+		ecmaVersion: 2018,
+		sourceType: 'module',
+	} );
+
+	const exportDeclarations = ast.body.filter(
+		( node ) => [ 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration' ].some( ( declaration ) => declaration === node.type )
+	);
+
+	const intermediateRepresentation = exportDeclarations.map(
+		( exportDeclaration ) => ( {
+			name: getNameDeclaration( exportDeclaration.declaration ),
+			jsdoc: doctrine.parse(
+				getLeadingComments( exportDeclaration ),
+				{ unwrap: true, recoverable: true }
+			),
+		} )
+	);
+
+	return intermediateRepresentation;
+};
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
new file mode 100644
index 00000000000000..44100b462edd8d
--- /dev/null
+++ b/packages/docgen/src/formatter.js
@@ -0,0 +1,15 @@
+module.exports = function( artifacts ) {
+	const docs = [ '# API' ];
+	docs.push( '\n' );
+	docs.push( '\n' );
+	artifacts.forEach( ( artifact ) => {
+		docs.push( `## ${ artifact.name }` );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( artifact.jsdoc.description.replace( '\n', ' ' ) );
+		docs.push( '\n' );
+		docs.push( '\n' );
+	} );
+	docs.pop(); // remove last \n, we want one blank line at the end of the file.
+	return docs.join( '' );
+};

From 7225849a5a4b194732f86aee56cc7b224709dcf6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 13:06:40 +0100
Subject: [PATCH 007/213] Add initial tests

---
 packages/docgen/package.json                  |  6 ++++-
 packages/docgen/tests/test-engine.js          | 25 +++++++++++++++++++
 .../docgen/tests/test-formatter-markdown.js   | 18 +++++++++++++
 3 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 packages/docgen/tests/test-engine.js
 create mode 100644 packages/docgen/tests/test-formatter-markdown.js

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 745c023e5e8f41..a1dfde25d607bf 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -17,10 +17,14 @@
 		"url": "https://github.com/WordPress/gutenberg/issues"
 	},
 	"main": "src/index.js",
+	"devDependencies": {
+		"faucet": "0.0.1",
+		"tape": "4.9.2"
+	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
-		"test": "echo \"Error: run tests from root\" && exit 1"
+		"test": "tape tests/*.js | faucet"
 	}
 }
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
new file mode 100644
index 00000000000000..a2bb4249e1a649
--- /dev/null
+++ b/packages/docgen/tests/test-engine.js
@@ -0,0 +1,25 @@
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+/**
+ * Internal dependencies.
+ */
+const engine = require( '../src/engine' );
+
+test( 'engine returns intermediate representation', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * My declaration example.
+ 		 */
+		export function myDeclaration() {
+			// do nothing
+		}
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
new file mode 100644
index 00000000000000..e378b37dcc162d
--- /dev/null
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -0,0 +1,18 @@
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+/**
+ * Internal dependencies.
+ */
+const formatter = require( '../src/formatter' );
+
+test( 'formatter returns markdown', ( t ) => {
+	const docs = formatter( [ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ] );
+	t.equal(
+		docs,
+		'# API\n\n## myDeclaration\n\nMy declaration example.\n'
+	);
+	t.end();
+} );

From de314f56b3ea1713f3c2cdc98e77d0fcd85ea323 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 13:09:22 +0100
Subject: [PATCH 008/213] Test named export (const)

---
 packages/docgen/package.json         |  3 ++-
 packages/docgen/tests/test-engine.js | 18 +++++++++++++++++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index a1dfde25d607bf..c7b0e25b608a81 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -25,6 +25,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"test": "tape tests/*.js | faucet"
+		"test": "tape tests/*.js | faucet",
+		"test:engine": "tape tests/test-engine.js | faucet"
 	}
 }
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index a2bb4249e1a649..1abd4f365a5d46 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -8,7 +8,7 @@ const test = require( 'tape' );
  */
 const engine = require( '../src/engine' );
 
-test( 'engine returns intermediate representation', ( t ) => {
+test( 'engine returns IR for named export (function)', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.
@@ -23,3 +23,19 @@ test( 'engine returns intermediate representation', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for named export (const)', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * My declaration example.
+ 		 */
+		export const myDeclaration = function() {
+			// do nothing
+		}
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );

From f27fb08045764179429390a009ca0e39d655332d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 13:13:19 +0100
Subject: [PATCH 009/213] Add test for default named functions

---
 packages/docgen/tests/test-engine.js | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 1abd4f365a5d46..662a8ec2abf259 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -39,3 +39,19 @@ test( 'engine returns IR for named export (const)', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for default export (named function)', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * My declaration example.
+ 		 */
+		export default function myDeclaration() {
+			// do nothing
+		}
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );

From 07e21fa18bff94e1526097b4ef03f65a62ca01ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 13:29:36 +0100
Subject: [PATCH 010/213] Add support for default export of anonymous functions

---
 packages/docgen/src/get-name-declaration.js |  4 ++--
 packages/docgen/tests/test-engine.js        | 16 ++++++++++++++++
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 8fae5e8b899869..ed4f883ee087e8 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-const { first } = require( 'lodash' );
+const { first, get } = require( 'lodash' );
 
 /**
  * Returns the assigned name for a given declaration node type, or undefined if
@@ -23,6 +23,6 @@ module.exports = function( declaration ) {
 	}
 
 	if ( declarator ) {
-		return declarator.id.name;
+		return get( declarator, [ 'id', 'name' ], 'default export' );
 	}
 };
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 662a8ec2abf259..4e615745f230f9 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -55,3 +55,19 @@ test( 'engine returns IR for default export (named function)', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for default export (anonymous function)', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * My declaration example.
+ 		 */
+		export default function() {
+			// do nothing
+		}
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'default export', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );

From 7b3dafc109803a126608753c008224245e6e30d2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 13:31:04 +0100
Subject: [PATCH 011/213] Better phrasing for test

---
 packages/docgen/tests/test-engine.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 4e615745f230f9..18df032a726961 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -24,7 +24,7 @@ test( 'engine returns IR for named export (function)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (const)', ( t ) => {
+test( 'engine returns IR for named export (variable)', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.

From 441ba4b2e9e1ce88b61b6355faa656a175a87cde Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 14:18:27 +0100
Subject: [PATCH 012/213] Add support for default exports (identifiers)

---
 packages/docgen/src/get-name-declaration.js | 19 +++++++++++--------
 packages/docgen/tests/test-engine.js        | 18 ++++++++++++++++++
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index ed4f883ee087e8..86c3b4be7887bb 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -4,25 +4,28 @@
 const { first, get } = require( 'lodash' );
 
 /**
- * Returns the assigned name for a given declaration node type, or undefined if
- * it cannot be determined.
+ * Returns the assigned name for a given declaration node type,
+ * or undefined if it cannot be determined.
  *
  * @param {Object} declaration Declaration node.
  *
  * @return {?string} Exported declaration name.
  */
 module.exports = function( declaration ) {
-	let declarator;
+	let name;
 	switch ( declaration.type ) {
 		case 'FunctionDeclaration':
-			declarator = declaration;
+			name = get( declaration, [ 'id', 'name' ], 'default export' );
 			break;
 
 		case 'VariableDeclaration':
-			declarator = first( declaration.declarations );
-	}
+			name = get( first( declaration.declarations ), [ 'id', 'name' ], 'default export' );
+			break;
 
-	if ( declarator ) {
-		return get( declarator, [ 'id', 'name' ], 'default export' );
+		case 'Identifier':
+			name = declaration.name;
+			break;
 	}
+
+	return name;
 };
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 18df032a726961..8bb9e7f6a2f4b5 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -71,3 +71,21 @@ test( 'engine returns IR for default export (anonymous function)', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for default export (identifier)', ( t ) => {
+	const ir = engine( `
+		function myDeclaration() {
+			// do nothing
+		}
+
+		/**
+ 		 * My declaration example.
+ 		 */
+		export default myDeclaration;
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );

From d305f7cc60fb7d4b7389ca7b27195fc5dae83b19 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 14:33:19 +0100
Subject: [PATCH 013/213] Add support for named exports of a single identifier

---
 packages/docgen/src/engine.js               | 10 +++++-----
 packages/docgen/src/get-name-declaration.js | 18 +++++++++++-------
 packages/docgen/tests/test-engine.js        | 18 ++++++++++++++++++
 3 files changed, 34 insertions(+), 12 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 86e4347d268a01..6bb109ff59e121 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -17,15 +17,15 @@ module.exports = function( code ) {
 		sourceType: 'module',
 	} );
 
-	const exportDeclarations = ast.body.filter(
+	const tokens = ast.body.filter(
 		( node ) => [ 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration' ].some( ( declaration ) => declaration === node.type )
 	);
 
-	const intermediateRepresentation = exportDeclarations.map(
-		( exportDeclaration ) => ( {
-			name: getNameDeclaration( exportDeclaration.declaration ),
+	const intermediateRepresentation = tokens.map(
+		( token ) => ( {
+			name: getNameDeclaration( token ),
 			jsdoc: doctrine.parse(
-				getLeadingComments( exportDeclaration ),
+				getLeadingComments( token ),
 				{ unwrap: true, recoverable: true }
 			),
 		} )
diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 86c3b4be7887bb..9991d699d8b215 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -4,26 +4,30 @@
 const { first, get } = require( 'lodash' );
 
 /**
- * Returns the assigned name for a given declaration node type,
+ * Returns the assigned name for a given export node type,
  * or undefined if it cannot be determined.
  *
- * @param {Object} declaration Declaration node.
+ * @param {Object} token Espree node.
  *
  * @return {?string} Exported declaration name.
  */
-module.exports = function( declaration ) {
+module.exports = function( token ) {
+	if ( token.declaration === null ) {
+		return first( token.specifiers ).local.name;
+	}
+
 	let name;
-	switch ( declaration.type ) {
+	switch ( token.declaration.type ) {
 		case 'FunctionDeclaration':
-			name = get( declaration, [ 'id', 'name' ], 'default export' );
+			name = get( token.declaration, [ 'id', 'name' ], 'default export' );
 			break;
 
 		case 'VariableDeclaration':
-			name = get( first( declaration.declarations ), [ 'id', 'name' ], 'default export' );
+			name = get( first( token.declaration.declarations ), [ 'id', 'name' ] );
 			break;
 
 		case 'Identifier':
-			name = declaration.name;
+			name = token.declaration.name;
 			break;
 	}
 
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 8bb9e7f6a2f4b5..9efe67ac50d2a8 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -40,6 +40,24 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
+test( 'engine returns IR for named export (identifier)', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * My declaration example.
+ 		 */
+		const myDeclaration = function() {
+			// do nothing
+		}
+
+		export { myDeclaration };
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'Undocumented declaration', tags: [] } } ]
+	);
+	t.end();
+} );
+
 test( 'engine returns IR for default export (named function)', ( t ) => {
 	const ir = engine( `
 		/**

From e1b83c0a3a6d63c431d4b5daecbb849f72a00e71 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 14:39:13 +0100
Subject: [PATCH 014/213] Add test for many exports at once

---
 packages/docgen/tests/test-engine.js | 34 ++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 9efe67ac50d2a8..543a1a11152413 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -40,6 +40,40 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
+test( 'engine returns IR for many exports at once', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * First declaration example.
+ 		 */
+		export const firstDeclaration = function() {
+			// do nothing
+		}
+
+		/**
+		 * Second declaration example.
+		 */
+		export function secondDeclaration(){
+			// do nothing
+		}
+
+		/**
+		 * Default declaration example.
+		 */
+		export default function() {
+			// do nothing
+		}
+` );
+	t.deepEqual(
+		ir,
+		[
+			{ name: 'firstDeclaration', jsdoc: { description: 'First declaration example.', tags: [] } },
+			{ name: 'secondDeclaration', jsdoc: { description: 'Second declaration example.', tags: [] } },
+			{ name: 'default export', jsdoc: { description: 'Default declaration example.', tags: [] } },
+		]
+	);
+	t.end();
+} );
+
 test( 'engine returns IR for named export (identifier)', ( t ) => {
 	const ir = engine( `
 		/**

From 04b6c8eff6ff116cf53462d487f8838f477088de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 16:53:55 +0100
Subject: [PATCH 015/213] Tweak text and reorder tests

---
 packages/docgen/tests/test-engine.js | 58 ++++++++++++++--------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 543a1a11152413..f5b324ef490cfa 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -8,28 +8,46 @@ const test = require( 'tape' );
  */
 const engine = require( '../src/engine' );
 
-test( 'engine returns IR for named export (function)', ( t ) => {
+test( 'engine returns IR for many exports at once', ( t ) => {
 	const ir = engine( `
 		/**
- 		 * My declaration example.
+ 		 * First declaration example.
  		 */
-		export function myDeclaration() {
+		export const firstDeclaration = function() {
+			// do nothing
+		}
+
+		/**
+		 * Second declaration example.
+		 */
+		export function secondDeclaration(){
+			// do nothing
+		}
+
+		/**
+		 * Default declaration example.
+		 */
+		export default function() {
 			// do nothing
 		}
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[
+			{ name: 'firstDeclaration', jsdoc: { description: 'First declaration example.', tags: [] } },
+			{ name: 'secondDeclaration', jsdoc: { description: 'Second declaration example.', tags: [] } },
+			{ name: 'default export', jsdoc: { description: 'Default declaration example.', tags: [] } },
+		]
 	);
 	t.end();
 } );
 
-test( 'engine returns IR for named export (variable)', ( t ) => {
+test( 'engine returns IR for named export (function)', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.
  		 */
-		export const myDeclaration = function() {
+		export function myDeclaration() {
 			// do nothing
 		}
 ` );
@@ -40,41 +58,23 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for many exports at once', ( t ) => {
+test( 'engine returns IR for named export (variable)', ( t ) => {
 	const ir = engine( `
 		/**
- 		 * First declaration example.
+ 		 * My declaration example.
  		 */
-		export const firstDeclaration = function() {
-			// do nothing
-		}
-
-		/**
-		 * Second declaration example.
-		 */
-		export function secondDeclaration(){
-			// do nothing
-		}
-
-		/**
-		 * Default declaration example.
-		 */
-		export default function() {
+		export const myDeclaration = function() {
 			// do nothing
 		}
 ` );
 	t.deepEqual(
 		ir,
-		[
-			{ name: 'firstDeclaration', jsdoc: { description: 'First declaration example.', tags: [] } },
-			{ name: 'secondDeclaration', jsdoc: { description: 'Second declaration example.', tags: [] } },
-			{ name: 'default export', jsdoc: { description: 'Default declaration example.', tags: [] } },
-		]
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
 	);
 	t.end();
 } );
 
-test( 'engine returns IR for named export (identifier)', ( t ) => {
+test( 'engine returns IR for named export (single identifier)', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.

From acef18c5fe2ba75b6a47a351e13866badf0b2d95 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 17:58:16 +0100
Subject: [PATCH 016/213] Teach engine to take JSDoc from identifier
 declaration

---
 packages/docgen/src/engine.js               |  8 +---
 packages/docgen/src/get-jsdoc.js            | 41 +++++++++++++++++++++
 packages/docgen/src/get-leading-comments.js | 13 ++++++-
 packages/docgen/tests/test-engine.js        | 40 +++++++++++++++++++-
 4 files changed, 92 insertions(+), 10 deletions(-)
 create mode 100644 packages/docgen/src/get-jsdoc.js

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 6bb109ff59e121..89da74798042c8 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -2,13 +2,12 @@
 * External dependencies.
 */
 const espree = require( 'espree' );
-const doctrine = require( 'doctrine' );
 
 /**
 * Internal dependencies.
 */
 const getNameDeclaration = require( './get-name-declaration' );
-const getLeadingComments = require( './get-leading-comments' );
+const getJSDoc = require( './get-jsdoc' );
 
 module.exports = function( code ) {
 	const ast = espree.parse( code, {
@@ -24,10 +23,7 @@ module.exports = function( code ) {
 	const intermediateRepresentation = tokens.map(
 		( token ) => ( {
 			name: getNameDeclaration( token ),
-			jsdoc: doctrine.parse(
-				getLeadingComments( token ),
-				{ unwrap: true, recoverable: true }
-			),
+			jsdoc: getJSDoc( ast, token ),
 		} )
 	);
 
diff --git a/packages/docgen/src/get-jsdoc.js b/packages/docgen/src/get-jsdoc.js
new file mode 100644
index 00000000000000..32dff78687335a
--- /dev/null
+++ b/packages/docgen/src/get-jsdoc.js
@@ -0,0 +1,41 @@
+/**
+ * External dependencies.
+ */
+const doctrine = require( 'doctrine' );
+const { first } = require( 'lodash' );
+
+/**
+ * Internal dependencies.
+ */
+const getLeadingComments = require( './get-leading-comments' );
+const getNameDeclaration = require( './get-name-declaration' );
+
+const getJSDoc = ( token ) => {
+	let jsdoc;
+	const comments = getLeadingComments( token );
+	if ( comments ) {
+		jsdoc = doctrine.parse( comments, { unwrap: true, recoverable: true } );
+	}
+	return jsdoc;
+};
+
+module.exports = function( ast, token ) {
+	let jsdoc = getJSDoc( token );
+	const name = getNameDeclaration( token );
+	// TODO: 'default export' is tangling getNameDeclaration and this module
+	if ( jsdoc === undefined && name !== 'default export' ) {
+		const candidates = ast.body.filter( ( node ) => {
+			return ( node.type === 'FunctionDeclaration' && node.id.name === name ) ||
+				( node.type === 'VariableDeclaration' && first( node.declarations ).id.name === name );
+		} );
+		if ( candidates.length === 1 ) {
+			jsdoc = getJSDoc( candidates[ 0 ] );
+		}
+	}
+
+	if ( jsdoc === undefined ) {
+		jsdoc = '*\n * Undocumented declaration\n ';
+	}
+
+	return jsdoc;
+};
diff --git a/packages/docgen/src/get-leading-comments.js b/packages/docgen/src/get-leading-comments.js
index e1e0b1e3dea831..3f025278b10337 100644
--- a/packages/docgen/src/get-leading-comments.js
+++ b/packages/docgen/src/get-leading-comments.js
@@ -3,9 +3,18 @@
  */
 const { last } = require( 'lodash' );
 
+/**
+ * Function that returns the leading comment
+ * of a Espree node.
+ *
+ * @param {Object} declaration Espree node to inspect
+ *
+ * @return {?string} Leading comment or undefined if there is none.
+ */
 module.exports = function( declaration ) {
+	let comments;
 	if ( declaration.leadingComments ) {
-		return last( declaration.leadingComments ).value;
+		comments = last( declaration.leadingComments ).value;
 	}
-	return '*\n * Undocumented declaration\n ';
+	return comments;
 };
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index f5b324ef490cfa..3da7dace6d4380 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -74,7 +74,7 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (single identifier)', ( t ) => {
+test( 'engine returns IR for named export (single identifier) using JSDoc from identifier', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.
@@ -87,7 +87,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'Undocumented declaration', tags: [] } } ]
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
 	);
 	t.end();
 } );
@@ -141,3 +141,39 @@ test( 'engine returns IR for default export (identifier)', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for default export (identifier) using JSDoc from function', ( t ) => {
+	const ir = engine( `
+		/**
+		 * My declaration example.
+		 */
+		function myDeclaration() {
+			// do nothing
+		}
+
+		export default myDeclaration;
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );
+
+test( 'engine returns IR for default export (identifier) using JSDoc from variable', ( t ) => {
+	const ir = engine( `
+		/**
+		 * My declaration example.
+		 */
+		const myDeclaration = function() {
+			// do nothing
+		}
+
+		export default myDeclaration;
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );

From e042c8c6f50c7230926192aa922e3738e33a48fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 18:00:48 +0100
Subject: [PATCH 017/213] Cover undocumented exports

---
 packages/docgen/src/get-jsdoc.js     |  2 +-
 packages/docgen/tests/test-engine.js | 15 +++++++++++++++
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/src/get-jsdoc.js b/packages/docgen/src/get-jsdoc.js
index 32dff78687335a..c04a284ccf3566 100644
--- a/packages/docgen/src/get-jsdoc.js
+++ b/packages/docgen/src/get-jsdoc.js
@@ -34,7 +34,7 @@ module.exports = function( ast, token ) {
 	}
 
 	if ( jsdoc === undefined ) {
-		jsdoc = '*\n * Undocumented declaration\n ';
+		jsdoc = { description: 'Undocumented declaration.', tags: [] };
 	}
 
 	return jsdoc;
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 3da7dace6d4380..e350213037f24c 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -177,3 +177,18 @@ test( 'engine returns IR for default export (identifier) using JSDoc from variab
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for undocumented export', ( t ) => {
+	const ir = engine( `
+		const myDeclaration = function() {
+			// do nothing
+		}
+
+		export default myDeclaration;
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'Undocumented declaration.', tags: [] } } ]
+	);
+	t.end();
+} );

From 4e74cb15bdcc4fab15525ef01f677a8e6ec2e8de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 18:01:04 +0100
Subject: [PATCH 018/213] Be more explicit about what is a test file

---
 packages/docgen/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index c7b0e25b608a81..04a8a998626014 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -25,7 +25,7 @@
 		"access": "public"
 	},
 	"scripts": {
-		"test": "tape tests/*.js | faucet",
+		"test": "tape tests/test-*.js | faucet",
 		"test:engine": "tape tests/test-engine.js | faucet"
 	}
 }

From fd6089114a79e9853cf1225cb94f3afa6bc843de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 18:03:14 +0100
Subject: [PATCH 019/213] Add more test to cover potential regressions

---
 packages/docgen/tests/test-engine.js | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index e350213037f24c..b76d482c0b46ea 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -74,6 +74,24 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
+test( 'engine returns IR for named export (single identifier)', ( t ) => {
+	const ir = engine( `
+	const myDeclaration = function() {
+		// do nothing
+	}
+	
+	/**
+	 * My declaration example.
+	 */
+	export { myDeclaration };
+` );
+	t.deepEqual(
+		ir,
+		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+	);
+	t.end();
+} );
+
 test( 'engine returns IR for named export (single identifier) using JSDoc from identifier', ( t ) => {
 	const ir = engine( `
 		/**

From 5fa808c7494edd0307d8a7c32ec299dc8bab68c6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 19:09:23 +0100
Subject: [PATCH 020/213] Expose script as npm script

---
 package.json               | 1 +
 packages/docgen/src/cli.js | 7 ++++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index eb1b308d87f2a1..97fb5c5126d485 100644
--- a/package.json
+++ b/package.json
@@ -161,6 +161,7 @@
 		"dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"",
 		"dev:packages": "node ./bin/packages/watch.js",
 		"docs:build": "node docs/tool",
+		"docs:api": "node packages/docgen/src/cli.js",
 		"fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"",
 		"fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json",
 		"fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit",
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 50311300aff9fa..98fe945d3a1f0f 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -10,7 +10,12 @@ const path = require( 'path' );
 const engine = require( './engine' );
 const formatter = require( './formatter' );
 
-const packageName = 'i18n';
+const packageName = process.argv[ 2 ];
+if ( packageName === undefined ) {
+	process.stdout.write( '\nUsage: <path-to-docgen> <gutenberg-package-name>\n' );
+	process.exit( 1 );
+}
+
 const root = path.resolve( __dirname, '../../../' );
 const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
 const output = path.resolve( root, `packages/${ packageName }/src/doc-api.md` );

From f2b7c98e654ea1cbbba432d50a4202ba62a13f9b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 16 Jan 2019 19:30:43 +0100
Subject: [PATCH 021/213] CLI: manage errors

---
 packages/docgen/src/cli.js | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 98fe945d3a1f0f..1ece71e63bfe43 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -12,16 +12,24 @@ const formatter = require( './formatter' );
 
 const packageName = process.argv[ 2 ];
 if ( packageName === undefined ) {
-	process.stdout.write( '\nUsage: <path-to-docgen> <gutenberg-package-name>\n' );
+	process.stdout.write( '\nUsage: <path-to-docgen> <gutenberg-package-name>\n\n\n' );
 	process.exit( 1 );
 }
 
-const root = path.resolve( __dirname, '../../../' );
-const input = path.resolve( root, `packages/${ packageName }/src/index.js` );
-const output = path.resolve( root, `packages/${ packageName }/src/doc-api.md` );
+const root = path.join( __dirname, '../../../' );
+// TODO:
+// - take input file from package.json?
+// - make CLI take input file instead of package?
+const input = path.join( root, `packages/${ packageName }/src/index.js` );
+const output = path.join( root, `packages/${ packageName }/api.md` );
 
-const code = fs.readFileSync( input, 'utf8' );
-const json = engine( code );
-const docs = formatter( json );
+fs.readFile( input, 'utf8', ( err, data ) => {
+	if ( err ) {
+		process.stdout.write( `\n${ input } does not exists.\n\n\n` );
+		process.exit( 1 );
+	}
 
-fs.writeFileSync( output, docs );
+	const json = engine( data );
+	const docs = formatter( json );
+	fs.writeFileSync( output, docs );
+} );

From 97ae4828e809ae8fc464b4f1bf43afcc13481686 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 11:39:42 +0100
Subject: [PATCH 022/213] Refactor to pave the way to next step

---
 packages/docgen/src/engine.js                 | 14 +++++-----
 ....js => get-intermediate-representation.js} |  1 +
 packages/docgen/tests/test-engine.js          | 26 +++++++++----------
 3 files changed, 21 insertions(+), 20 deletions(-)
 rename packages/docgen/src/{get-jsdoc.js => get-intermediate-representation.js} (98%)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 89da74798042c8..a53cff012f4e16 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -6,8 +6,7 @@ const espree = require( 'espree' );
 /**
 * Internal dependencies.
 */
-const getNameDeclaration = require( './get-name-declaration' );
-const getJSDoc = require( './get-jsdoc' );
+const getIntermediateRepresentation = require( './get-intermediate-representation' );
 
 module.exports = function( code ) {
 	const ast = espree.parse( code, {
@@ -17,14 +16,15 @@ module.exports = function( code ) {
 	} );
 
 	const tokens = ast.body.filter(
-		( node ) => [ 'ExportNamedDeclaration', 'ExportDefaultDeclaration', 'ExportAllDeclaration' ].some( ( declaration ) => declaration === node.type )
+		( node ) => [
+			'ExportNamedDeclaration',
+			'ExportDefaultDeclaration',
+			'ExportAllDeclaration',
+		].some( ( declaration ) => declaration === node.type )
 	);
 
 	const intermediateRepresentation = tokens.map(
-		( token ) => ( {
-			name: getNameDeclaration( token ),
-			jsdoc: getJSDoc( ast, token ),
-		} )
+		( token ) => getIntermediateRepresentation( ast, token )
 	);
 
 	return intermediateRepresentation;
diff --git a/packages/docgen/src/get-jsdoc.js b/packages/docgen/src/get-intermediate-representation.js
similarity index 98%
rename from packages/docgen/src/get-jsdoc.js
rename to packages/docgen/src/get-intermediate-representation.js
index c04a284ccf3566..5d8d33c47ef3c6 100644
--- a/packages/docgen/src/get-jsdoc.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -37,5 +37,6 @@ module.exports = function( ast, token ) {
 		jsdoc = { description: 'Undocumented declaration.', tags: [] };
 	}
 
+	jsdoc.name = name;
 	return jsdoc;
 };
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index b76d482c0b46ea..d5ba6349af6be2 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -34,9 +34,9 @@ test( 'engine returns IR for many exports at once', ( t ) => {
 	t.deepEqual(
 		ir,
 		[
-			{ name: 'firstDeclaration', jsdoc: { description: 'First declaration example.', tags: [] } },
-			{ name: 'secondDeclaration', jsdoc: { description: 'Second declaration example.', tags: [] } },
-			{ name: 'default export', jsdoc: { description: 'Default declaration example.', tags: [] } },
+			{ description: 'First declaration example.', tags: [], name: 'firstDeclaration' },
+			{ description: 'Second declaration example.', tags: [], name: 'secondDeclaration' },
+			{ description: 'Default declaration example.', tags: [], name: 'default export' },
 		]
 	);
 	t.end();
@@ -53,7 +53,7 @@ test( 'engine returns IR for named export (function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -69,7 +69,7 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -87,7 +87,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -105,7 +105,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from i
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -121,7 +121,7 @@ test( 'engine returns IR for default export (named function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -137,7 +137,7 @@ test( 'engine returns IR for default export (anonymous function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default export', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
 	);
 	t.end();
 } );
@@ -155,7 +155,7 @@ test( 'engine returns IR for default export (identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -173,7 +173,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from functi
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -191,7 +191,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from variab
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ]
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );
@@ -206,7 +206,7 @@ test( 'engine returns IR for undocumented export', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', jsdoc: { description: 'Undocumented declaration.', tags: [] } } ]
+		[ { description: 'Undocumented declaration.', tags: [], name: 'myDeclaration' } ]
 	);
 	t.end();
 } );

From 5f45ad7891785065b7beeca62190ea20a507a0cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 12:27:57 +0100
Subject: [PATCH 023/213] Refactor to prepare next step

---
 packages/docgen/src/engine.js                     |  7 +++++++
 .../docgen/src/get-intermediate-representation.js | 15 +++++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index a53cff012f4e16..f6654371fea681 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -8,6 +8,13 @@ const espree = require( 'espree' );
 */
 const getIntermediateRepresentation = require( './get-intermediate-representation' );
 
+/**
+ * Function that takes code and returns an intermediate representation.
+ *
+ * @param {string} code The code to parse.
+ *
+ * @return {Object} Intermediate Representation in JSON.
+ */
 module.exports = function( code ) {
 	const ast = espree.parse( code, {
 		attachComment: true,
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 5d8d33c47ef3c6..7ea8be8fa6fb6d 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -19,11 +19,22 @@ const getJSDoc = ( token ) => {
 	return jsdoc;
 };
 
+const isIdentifier = ( token ) => {
+	if ( token.declaration !== null &&
+		token.declaration.type === 'Identifier' ) {
+		return true;
+	}
+	if ( token.declaration === null &&
+		token.specifiers !== null &&
+		token.specifiers.length > 0 ) {
+		return true;
+	}
+};
+
 module.exports = function( ast, token ) {
 	let jsdoc = getJSDoc( token );
 	const name = getNameDeclaration( token );
-	// TODO: 'default export' is tangling getNameDeclaration and this module
-	if ( jsdoc === undefined && name !== 'default export' ) {
+	if ( jsdoc === undefined && isIdentifier( token ) ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return ( node.type === 'FunctionDeclaration' && node.id.name === name ) ||
 				( node.type === 'VariableDeclaration' && first( node.declarations ).id.name === name );

From c92e15b5e9a8cd8fe172c5f0bc09803d7f2ab098 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 12:31:18 +0100
Subject: [PATCH 024/213] Refactor to prepare next step

---
 packages/docgen/src/engine.js                         |  2 +-
 .../docgen/src/get-intermediate-representation.js     | 11 ++++++++++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index f6654371fea681..d80d95bdde35b6 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -31,7 +31,7 @@ module.exports = function( code ) {
 	);
 
 	const intermediateRepresentation = tokens.map(
-		( token ) => getIntermediateRepresentation( ast, token )
+		( token ) => getIntermediateRepresentation( token, ast )
 	);
 
 	return intermediateRepresentation;
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 7ea8be8fa6fb6d..8e7d85ea5e2e79 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -31,7 +31,16 @@ const isIdentifier = ( token ) => {
 	}
 };
 
-module.exports = function( ast, token ) {
+/**
+ * Takes a export token and the file AST
+ * and returns an intermediate representation in JSON.
+ *
+ * @param {Object} token Espree export token.
+ * @param {Object} ast Espree ast of a single file.
+ *
+ * @return {Object} Intermediate Representation in JSON.
+ */
+module.exports = function( token, ast ) {
 	let jsdoc = getJSDoc( token );
 	const name = getNameDeclaration( token );
 	if ( jsdoc === undefined && isIdentifier( token ) ) {

From ef0d41eb8e5a8bd6f0e9434b9095fe64acd915cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 13:25:06 +0100
Subject: [PATCH 025/213] Add helper functions

---
 packages/docgen/src/get-dependency-path.js     |  3 +++
 packages/docgen/src/get-jsdoc.js               | 18 ++++++++++++++++++
 .../docgen/src/is-identifier-in-dependency.js  |  8 ++++++++
 .../docgen/src/is-identifier-in-same-file.js   | 13 +++++++++++++
 4 files changed, 42 insertions(+)
 create mode 100644 packages/docgen/src/get-dependency-path.js
 create mode 100644 packages/docgen/src/get-jsdoc.js
 create mode 100644 packages/docgen/src/is-identifier-in-dependency.js
 create mode 100644 packages/docgen/src/is-identifier-in-same-file.js

diff --git a/packages/docgen/src/get-dependency-path.js b/packages/docgen/src/get-dependency-path.js
new file mode 100644
index 00000000000000..83c043023ed441
--- /dev/null
+++ b/packages/docgen/src/get-dependency-path.js
@@ -0,0 +1,3 @@
+module.exports = function( token ) {
+	return token.source.value;
+};
diff --git a/packages/docgen/src/get-jsdoc.js b/packages/docgen/src/get-jsdoc.js
new file mode 100644
index 00000000000000..477fd176d54ea1
--- /dev/null
+++ b/packages/docgen/src/get-jsdoc.js
@@ -0,0 +1,18 @@
+/**
+ * External dependencies.
+ */
+const doctrine = require( 'doctrine' );
+
+/**
+ * Internal dependencies.
+ */
+const getLeadingComments = require( './get-leading-comments' );
+
+module.exports = function( token ) {
+	let jsdoc;
+	const comments = getLeadingComments( token );
+	if ( comments ) {
+		jsdoc = doctrine.parse( comments, { unwrap: true, recoverable: true } );
+	}
+	return jsdoc;
+};
diff --git a/packages/docgen/src/is-identifier-in-dependency.js b/packages/docgen/src/is-identifier-in-dependency.js
new file mode 100644
index 00000000000000..261b7bd888828e
--- /dev/null
+++ b/packages/docgen/src/is-identifier-in-dependency.js
@@ -0,0 +1,8 @@
+module.exports = function( token ) {
+	if ( token.declaration === null &&
+		token.specifiers !== null &&
+		token.specifiers.length > 0 &&
+		token.source !== null ) {
+		return true;
+	}
+};
diff --git a/packages/docgen/src/is-identifier-in-same-file.js b/packages/docgen/src/is-identifier-in-same-file.js
new file mode 100644
index 00000000000000..a0389f48917cab
--- /dev/null
+++ b/packages/docgen/src/is-identifier-in-same-file.js
@@ -0,0 +1,13 @@
+module.exports = function( token ) {
+	if ( token.declaration !== null &&
+		token.declaration.type === 'Identifier' ) {
+		return true;
+	}
+	if ( token.declaration === null &&
+		token.specifiers !== null &&
+		token.specifiers.length > 0 &&
+		token.source === null ) {
+		return true;
+	}
+	return false;
+};

From 48281e5f660215bc165b80ad20fb967139b7c3b2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 13:26:39 +0100
Subject: [PATCH 026/213] Add mechanism to query upper layers for dependency
 code

---
 .../src/get-intermediate-representation.js    | 53 ++++++++-----------
 1 file changed, 21 insertions(+), 32 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 8e7d85ea5e2e79..9aa1cee6d12d10 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -1,35 +1,16 @@
 /**
  * External dependencies.
  */
-const doctrine = require( 'doctrine' );
 const { first } = require( 'lodash' );
 
 /**
  * Internal dependencies.
  */
-const getLeadingComments = require( './get-leading-comments' );
 const getNameDeclaration = require( './get-name-declaration' );
-
-const getJSDoc = ( token ) => {
-	let jsdoc;
-	const comments = getLeadingComments( token );
-	if ( comments ) {
-		jsdoc = doctrine.parse( comments, { unwrap: true, recoverable: true } );
-	}
-	return jsdoc;
-};
-
-const isIdentifier = ( token ) => {
-	if ( token.declaration !== null &&
-		token.declaration.type === 'Identifier' ) {
-		return true;
-	}
-	if ( token.declaration === null &&
-		token.specifiers !== null &&
-		token.specifiers.length > 0 ) {
-		return true;
-	}
-};
+const getJSDoc = require( './get-jsdoc' );
+const isIdentifierInSameFile = require( './is-identifier-in-same-file' );
+const isIdentifierInDependency = require( './is-identifier-in-dependency' );
+const getDependencyPath = require( './get-dependency-path' );
 
 /**
  * Takes a export token and the file AST
@@ -37,26 +18,34 @@ const isIdentifier = ( token ) => {
  *
  * @param {Object} token Espree export token.
  * @param {Object} ast Espree ast of a single file.
+ * @param {Function} parseDependency Function that takes a path
+ * and returns the AST of the dependency file.
  *
  * @return {Object} Intermediate Representation in JSON.
  */
-module.exports = function( token, ast ) {
-	let jsdoc = getJSDoc( token );
+module.exports = function( token, ast, parseDependency = () => {} ) {
+	let ir = getJSDoc( token );
 	const name = getNameDeclaration( token );
-	if ( jsdoc === undefined && isIdentifier( token ) ) {
+	// If at this point, the ir is undefined, we'll lookup JSDoc comments either:
+	// 1) in the same file declaration
+	// 2) in the dependency file declaration
+	if ( ir === undefined && isIdentifierInSameFile( token ) ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return ( node.type === 'FunctionDeclaration' && node.id.name === name ) ||
-				( node.type === 'VariableDeclaration' && first( node.declarations ).id.name === name );
+			( node.type === 'VariableDeclaration' && first( node.declarations ).id.name === name );
 		} );
 		if ( candidates.length === 1 ) {
-			jsdoc = getJSDoc( candidates[ 0 ] );
+			ir = getJSDoc( candidates[ 0 ] );
 		}
+	} else if ( ir === undefined && isIdentifierInDependency( token ) ) {
+		ir = parseDependency( getDependencyPath( token ) );
 	}
 
-	if ( jsdoc === undefined ) {
-		jsdoc = { description: 'Undocumented declaration.', tags: [] };
+	// Sometimes, humans do not add JSDoc, though.
+	if ( ir === undefined ) {
+		ir = { description: 'Undocumented declaration.', tags: [] };
 	}
 
-	jsdoc.name = name;
-	return jsdoc;
+	ir.name = name;
+	return ir;
 };

From 84f5e1c5663fb3bfa5a1b6ea7d7ff5fca00e0c8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 14:01:33 +0100
Subject: [PATCH 027/213] Engine can lookup JSDoc in dependency file

---
 packages/docgen/src/engine.js                 | 52 +++++++++++--------
 .../src/get-intermediate-representation.js    |  3 +-
 2 files changed, 33 insertions(+), 22 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index d80d95bdde35b6..a1a7e5bd326500 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -8,31 +8,41 @@ const espree = require( 'espree' );
 */
 const getIntermediateRepresentation = require( './get-intermediate-representation' );
 
+const getAST = ( source ) => espree.parse( source, {
+	attachComment: true,
+	ecmaVersion: 2018,
+	sourceType: 'module',
+} );
+
+const getExportTokens = ( ast ) => ast.body.filter(
+	( node ) => [
+		'ExportNamedDeclaration',
+		'ExportDefaultDeclaration',
+		'ExportAllDeclaration',
+	].some( ( declaration ) => declaration === node.type )
+);
+
+const getIRFromDependency = ( getCodeFromPath ) => ( path ) => engine( getCodeFromPath( path ) );
+
+const engine = ( code, getCodeFromPath = () => {} ) => {
+	const ast = getAST( code );
+	const tokens = getExportTokens( ast );
+	return tokens.map(
+		( token ) => getIntermediateRepresentation(
+			token,
+			ast,
+			getIRFromDependency( getCodeFromPath )
+		)
+	);
+};
+
 /**
  * Function that takes code and returns an intermediate representation.
  *
  * @param {string} code The code to parse.
+ * @param {Function} getCodeFromDependency Callback to retrieve code
+ * from a relative path.
  *
  * @return {Object} Intermediate Representation in JSON.
  */
-module.exports = function( code ) {
-	const ast = espree.parse( code, {
-		attachComment: true,
-		ecmaVersion: 2018,
-		sourceType: 'module',
-	} );
-
-	const tokens = ast.body.filter(
-		( node ) => [
-			'ExportNamedDeclaration',
-			'ExportDefaultDeclaration',
-			'ExportAllDeclaration',
-		].some( ( declaration ) => declaration === node.type )
-	);
-
-	const intermediateRepresentation = tokens.map(
-		( token ) => getIntermediateRepresentation( token, ast )
-	);
-
-	return intermediateRepresentation;
-};
+module.exports = engine;
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 9aa1cee6d12d10..8f6fd6153d1810 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -38,7 +38,8 @@ module.exports = function( token, ast, parseDependency = () => {} ) {
 			ir = getJSDoc( candidates[ 0 ] );
 		}
 	} else if ( ir === undefined && isIdentifierInDependency( token ) ) {
-		ir = parseDependency( getDependencyPath( token ) );
+		const irFromDependency = parseDependency( getDependencyPath( token ) );
+		ir = irFromDependency.find( ( exportDeclaration ) => exportDeclaration.name === name );
 	}
 
 	// Sometimes, humans do not add JSDoc, though.

From 6e006ea0502bcb79e006a08be833acaaefc9bd21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 14:14:33 +0100
Subject: [PATCH 028/213] Formatter - adapt a new engine API

---
 packages/docgen/src/formatter.js                 | 2 +-
 packages/docgen/tests/test-formatter-markdown.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 44100b462edd8d..8254b995e22db8 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -6,7 +6,7 @@ module.exports = function( artifacts ) {
 		docs.push( `## ${ artifact.name }` );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( artifact.jsdoc.description.replace( '\n', ' ' ) );
+		docs.push( artifact.description.replace( '\n', ' ' ) );
 		docs.push( '\n' );
 		docs.push( '\n' );
 	} );
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index e378b37dcc162d..4e05c00f01e9a4 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -9,7 +9,7 @@ const test = require( 'tape' );
 const formatter = require( '../src/formatter' );
 
 test( 'formatter returns markdown', ( t ) => {
-	const docs = formatter( [ { name: 'myDeclaration', jsdoc: { description: 'My declaration example.', tags: [] } } ] );
+	const docs = formatter( [ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ] );
 	t.equal(
 		docs,
 		'# API\n\n## myDeclaration\n\nMy declaration example.\n'

From 560abda27a478c44a9492896320111ad31a8285f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 14:15:48 +0100
Subject: [PATCH 029/213] Add test for looking up JSDoc in dependency

---
 packages/docgen/tests/test-engine.js | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index d5ba6349af6be2..234f5860816bd0 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -110,6 +110,25 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from i
 	t.end();
 } );
 
+test( 'engine returns IR for named export (single identifier) using JSDoc from dependency', ( t ) => {
+	const getDependency = () => `/**
+ 		 * My declaration example.
+ 		 */
+		export const myDeclaration = function() {
+			// do nothing
+		}
+	`;
+	const ir = engine(
+		`export { myDeclaration } from './my-dependency';`,
+		getDependency
+	);
+	t.deepEqual(
+		ir,
+		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+	);
+	t.end();
+} );
+
 test( 'engine returns IR for default export (named function)', ( t ) => {
 	const ir = engine( `
 		/**
@@ -210,3 +229,9 @@ test( 'engine returns IR for undocumented export', ( t ) => {
 	);
 	t.end();
 } );
+
+test( 'engine returns IR for undefined code', ( t ) => {
+	const ir = engine( undefined );
+	t.deepEqual( ir, [ ] );
+	t.end();
+} );

From 444891a32e9ed0c42ca9bd91a6dd5f3720606b50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 14:16:32 +0100
Subject: [PATCH 030/213] CLI: adapt to new engine API

---
 packages/docgen/src/cli.js | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 1ece71e63bfe43..bec6729c63574c 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -20,16 +20,19 @@ const root = path.join( __dirname, '../../../' );
 // TODO:
 // - take input file from package.json?
 // - make CLI take input file instead of package?
-const input = path.join( root, `packages/${ packageName }/src/index.js` );
+const srcDir = path.join( root, `packages/${ packageName }/src/` );
+const input = path.join( srcDir, `index.js` );
 const output = path.join( root, `packages/${ packageName }/api.md` );
 
-fs.readFile( input, 'utf8', ( err, data ) => {
+const getCodeFromFile = ( file ) => fs.readFileSync( path.join( srcDir, file + '.js' ), 'utf8' );
+
+fs.readFile( input, 'utf8', ( err, code ) => {
 	if ( err ) {
 		process.stdout.write( `\n${ input } does not exists.\n\n\n` );
 		process.exit( 1 );
 	}
 
-	const json = engine( data );
+	const json = engine( code, getCodeFromFile );
 	const docs = formatter( json );
 	fs.writeFileSync( output, docs );
 } );

From fe14068bd29512e4613a755e3502511910192073 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 14:21:27 +0100
Subject: [PATCH 031/213] Engine: enable JSX support

---
 packages/docgen/src/engine.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index a1a7e5bd326500..712c6d26ceaa2c 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -11,6 +11,9 @@ const getIntermediateRepresentation = require( './get-intermediate-representatio
 const getAST = ( source ) => espree.parse( source, {
 	attachComment: true,
 	ecmaVersion: 2018,
+	ecmaFeatures: {
+		jsx: true,
+	},
 	sourceType: 'module',
 } );
 

From 0ab135f0a5b72e3632711029b85b0ab01b98ef0e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 18:22:31 +0100
Subject: [PATCH 032/213] Evaluate how much coverage do we have already

---
 packages/docgen/coverage.md | 57 +++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 packages/docgen/coverage.md

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
new file mode 100644
index 00000000000000..d65358502c629f
--- /dev/null
+++ b/packages/docgen/coverage.md
@@ -0,0 +1,57 @@
+# Coverage
+
+- [x] a11y
+- [x] annotations - export nothing
+- [x] api-fetch
+- [x] autop
+- [x] babel-plugin-import-jsx-pragma
+- [ ] babel-plugin-makepot - NODE EXPORT
+- [ ] babel-preset-default - NODE EXPORT, not `src/index.js`
+- [x] blob
+- [x] block-library
+- [x] block-serialization-default-parser
+- [ ] block-serialization-spec-parser - not `src/index.js`, multiple named exports
+- [ ] blocks - `export *`
+- [ ] browserslist-config - NODE, not `src/index.js`
+- [ ] components - `export *`, `default as`
+- [ ] compose - directory dependency
+- [x] core-data - export nothing
+- [ ] custom-templated-path-webpack-plugin - NODE EXPORT
+- [ ] data - directory dependency
+- [x] date
+- [ ] deprecated - do not name default export
+- [ ] docgen - not `src/index.js`
+- [ ] dom - `export *`
+- [x] dom-ready
+- [ ] e2e-tests - what shall be documented?
+- [ ] e2e-test-utils - what shall be documented?
+- [ ] editor - `export *`
+- [ ] edit-post - directory dependency
+- [ ] element - `export *`, `default as`
+- [x] escape-html
+- [ ] eslint-plugin - NODE EXPORT
+- [x] format-library - exports nothing
+- [ ] hooks - multiple named exports
+- [x] html-entities
+- [x] i18n
+- [ ] is-shallow-equal - NODE EXPORT
+- [x] jest-console - export nothing
+- [ ] jest-preset-default - NODE EXPORT, not `src/index.js`
+- [x] jest-puppeteer-axe - export nothing
+- [-] keycodes - how to document CONSTANTS?
+- [ ] library-export-default-webpack-plugin - NODE EXPORT
+- [x] list-reusable-blocks - export nothing
+- [ ] notices - REVIEW. Does weird things.
+- [ ] npm-package-json-lint-config - CONFIG file
+- [ ] nux - `default as`, directory dependency 
+- [ ] plugins - `export *`
+- [ ] postcss-themes - NODE export
+- [x] priority-queue
+- [-] redux-routine - check description with many paragraphs
+- [x] rich-text
+- [ ] scripts - what shall be documented?
+- [x] shortcode
+- [ ] token-list - `export class`
+- [x] url
+- [ ] viewport - `default as`
+- [x] wordcount

From a2a5a6a6a2634f09f32d6957b48da55f85bd8f9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 17 Jan 2019 18:22:47 +0100
Subject: [PATCH 033/213] Remove unused file

---
 docs/tool/goal.md | 19 -------------------
 1 file changed, 19 deletions(-)
 delete mode 100644 docs/tool/goal.md

diff --git a/docs/tool/goal.md b/docs/tool/goal.md
deleted file mode 100644
index 885e3a51bf13d4..00000000000000
--- a/docs/tool/goal.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# «X» API
-
-## «API_ARTIFACT»
-
-_Introduced in «SINCE_DESCRIPTION»._
-
-«JSDOC_DESCRIPTION»
-
-**Parameters**
-
-- «PARAMETER_DESCRIPTION»
-
-**Returns**
-
-«RETURN_DESCRIPTION»
-
-**Examples**
-
-«EXAMPLES_DESCRIPTION»

From 2d7268a5058d8f72820f59de8702a625873374e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 10:41:24 +0100
Subject: [PATCH 034/213] Add test for multiple named exports

---
 packages/docgen/tests/test-engine.js | 30 +++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 234f5860816bd0..5b981499a62c48 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -92,7 +92,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (single identifier) using JSDoc from identifier', ( t ) => {
+test( 'engine returns IR for named export (single identifier) using JSDoc from declaration', ( t ) => {
 	const ir = engine( `
 		/**
  		 * My declaration example.
@@ -110,6 +110,34 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from i
 	t.end();
 } );
 
+test( 'engine returns IR for named export (multiple identifiers) using JSDoc from declaration', ( t ) => {
+	const ir = engine( `
+		/**
+ 		 * First declaration example.
+ 		 */
+		const firstDeclaration = function() {
+			// do nothing
+		}
+
+		/**
+ 		 * Second declaration example.
+ 		 */
+		const secondDeclaration = function() {
+			// do nothing
+		}
+
+		export { firstDeclaration, secondDeclaration };
+` );
+	t.deepEqual(
+		ir,
+		[
+			{ description: 'First declaration example.', tags: [], name: 'firstDeclaration' },
+			{ description: 'Second declaration example.', tags: [], name: 'secondDeclaration' },
+		]
+	);
+	t.end();
+} );
+
 test( 'engine returns IR for named export (single identifier) using JSDoc from dependency', ( t ) => {
 	const getDependency = () => `/**
  		 * My declaration example.

From f017dfe89711e3ad101c734ad841b69596509c60 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 17:57:38 +0100
Subject: [PATCH 035/213] Add more info for debugging purposes

---
 packages/docgen/src/cli.js    | 15 ++++++++++-----
 packages/docgen/src/engine.js | 13 ++++++++-----
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index bec6729c63574c..e9d0a1ae6a8314 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -22,9 +22,12 @@ const root = path.join( __dirname, '../../../' );
 // - make CLI take input file instead of package?
 const srcDir = path.join( root, `packages/${ packageName }/src/` );
 const input = path.join( srcDir, `index.js` );
-const output = path.join( root, `packages/${ packageName }/api.md` );
+const doc = path.join( root, `packages/${ packageName }/api.md` );
+const ir = path.join( root, `packages/${ packageName }/ir.json` );
+const tokens = path.join( root, `packages/${ packageName }/tokens.json` );
+const ast = path.join( root, `packages/${ packageName }/ast.json` );
 
-const getCodeFromFile = ( file ) => fs.readFileSync( path.join( srcDir, file + '.js' ), 'utf8' );
+const getCodeFromPath = ( file ) => fs.readFileSync( path.join( srcDir, file + '.js' ), 'utf8' );
 
 fs.readFile( input, 'utf8', ( err, code ) => {
 	if ( err ) {
@@ -32,7 +35,9 @@ fs.readFile( input, 'utf8', ( err, code ) => {
 		process.exit( 1 );
 	}
 
-	const json = engine( code, getCodeFromFile );
-	const docs = formatter( json );
-	fs.writeFileSync( output, docs );
+	const result = engine( code, getCodeFromPath );
+	fs.writeFileSync( doc, formatter( result.ir ) );
+	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
+	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
+	fs.writeFileSync( ast, JSON.stringify( result.ast ) );
 } );
diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 712c6d26ceaa2c..3b64a357904d10 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -28,22 +28,25 @@ const getExportTokens = ( ast ) => ast.body.filter(
 const getIRFromDependency = ( getCodeFromPath ) => ( path ) => engine( getCodeFromPath( path ) );
 
 const engine = ( code, getCodeFromPath = () => {} ) => {
-	const ast = getAST( code );
-	const tokens = getExportTokens( ast );
-	return tokens.map(
+	const result = {};
+	result.ast = getAST( code );
+	result.tokens = getExportTokens( result.ast );
+	result.ir = result.tokens.map(
 		( token ) => getIntermediateRepresentation(
 			token,
-			ast,
+			result.ast,
 			getIRFromDependency( getCodeFromPath )
 		)
 	);
+
+	return result;
 };
 
 /**
  * Function that takes code and returns an intermediate representation.
  *
  * @param {string} code The code to parse.
- * @param {Function} getCodeFromDependency Callback to retrieve code
+ * @param {Function} [getCodeFromPath=noop] Callback to retrieve code
  * from a relative path.
  *
  * @return {Object} Intermediate Representation in JSON.

From 84f4dbca217d917422d0b71b0249565b374f6868 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:03:43 +0100
Subject: [PATCH 036/213] Add tests for get name of named function and variable

---
 packages/docgen/package.json                  |  3 +-
 .../docgen/tests/fixtures/named-function.js   |  4 ++
 .../docgen/tests/fixtures/named-function.json | 56 ++++++++++++++++
 .../docgen/tests/fixtures/named-variable.js   |  5 ++
 .../docgen/tests/fixtures/named-variable.json | 65 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 35 ++++++++++
 6 files changed, 167 insertions(+), 1 deletion(-)
 create mode 100644 packages/docgen/tests/fixtures/named-function.js
 create mode 100644 packages/docgen/tests/fixtures/named-function.json
 create mode 100644 packages/docgen/tests/fixtures/named-variable.js
 create mode 100644 packages/docgen/tests/fixtures/named-variable.json
 create mode 100644 packages/docgen/tests/test-get-name-declaration.js

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 04a8a998626014..4fe91d84b877dc 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -26,6 +26,7 @@
 	},
 	"scripts": {
 		"test": "tape tests/test-*.js | faucet",
-		"test:engine": "tape tests/test-engine.js | faucet"
+		"test:engine": "tape tests/test-engine.js | faucet",
+		"test:get-name-declaration": "tape tests/test-get-name-declaration.js | faucet"
 	}
 }
diff --git a/packages/docgen/tests/fixtures/named-function.js b/packages/docgen/tests/fixtures/named-function.js
new file mode 100644
index 00000000000000..eadb279918d042
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function.js
@@ -0,0 +1,4 @@
+/**
+ * My declaration example.
+ */
+export function myDeclaration() {}
diff --git a/packages/docgen/tests/fixtures/named-function.json b/packages/docgen/tests/fixtures/named-function.json
new file mode 100644
index 00000000000000..f75087e8b740bd
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function.json
@@ -0,0 +1,56 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 46,
+	"end": 100,
+	"range": [
+		46,
+		100
+	],
+	"declaration": {
+		"type": "FunctionDeclaration",
+		"start": 53,
+		"end": 100,
+		"range": [
+			53,
+			100
+		],
+		"id": {
+			"type": "Identifier",
+			"start": 62,
+			"end": 75,
+			"range": [
+				62,
+				75
+			],
+			"name": "myDeclaration"
+		},
+		"generator": false,
+		"expression": false,
+		"async": false,
+		"params": [],
+		"body": {
+			"type": "BlockStatement",
+			"start": 78,
+			"end": 100,
+			"range": [
+				78,
+				100
+			],
+			"body": []
+		}
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n \t\t * My declaration example.\n \t\t ",
+			"start": 3,
+			"end": 43,
+			"range": [
+				3,
+				43
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-variable.js b/packages/docgen/tests/fixtures/named-variable.js
new file mode 100644
index 00000000000000..e89c8a9751394c
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-variable.js
@@ -0,0 +1,5 @@
+/**
+ * My declaration example.
+ */
+export const myDeclaration = true;
+
diff --git a/packages/docgen/tests/fixtures/named-variable.json b/packages/docgen/tests/fixtures/named-variable.json
new file mode 100644
index 00000000000000..a5cab04541dfef
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-variable.json
@@ -0,0 +1,65 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 35,
+	"end": 69,
+	"range": [
+		35,
+		69
+	],
+	"declaration": {
+		"type": "VariableDeclaration",
+		"start": 42,
+		"end": 69,
+		"range": [
+			42,
+			69
+		],
+		"declarations": [
+			{
+				"type": "VariableDeclarator",
+				"start": 48,
+				"end": 68,
+				"range": [
+					48,
+					68
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 48,
+					"end": 61,
+					"range": [
+						48,
+						61
+					],
+					"name": "myDeclaration"
+				},
+				"init": {
+					"type": "Literal",
+					"start": 64,
+					"end": 68,
+					"range": [
+						64,
+						68
+					],
+					"value": true,
+					"raw": "true"
+				}
+			}
+		],
+		"kind": "const"
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
+			"range": [
+				0,
+				34
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
new file mode 100644
index 00000000000000..4c113646eddac8
--- /dev/null
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -0,0 +1,35 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies.
+ */
+const getNameDeclaration = require( '../src/get-name-declaration' );
+
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+test( 'returns name for named export (function)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-function.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'myDeclaration' );
+	t.end();
+} );
+
+test( 'returns name for named export (variable)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-variable.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'myDeclaration' );
+	t.end();
+} );

From 844d74ab82d847af8290111720674752fc995ece Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:06:53 +0100
Subject: [PATCH 037/213] Add support and test for parsing classes

---
 packages/docgen/src/get-name-declaration.js   |  4 ++
 packages/docgen/tests/fixtures/named-class.js |  4 ++
 .../docgen/tests/fixtures/named-class.json    | 53 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 10 ++++
 4 files changed, 71 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-class.js
 create mode 100644 packages/docgen/tests/fixtures/named-class.json

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 9991d699d8b215..b0bd60d190898c 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -18,6 +18,10 @@ module.exports = function( token ) {
 
 	let name;
 	switch ( token.declaration.type ) {
+		case 'ClassDeclaration':
+			name = token.declaration.id.name;
+			break;
+
 		case 'FunctionDeclaration':
 			name = get( token.declaration, [ 'id', 'name' ], 'default export' );
 			break;
diff --git a/packages/docgen/tests/fixtures/named-class.js b/packages/docgen/tests/fixtures/named-class.js
new file mode 100644
index 00000000000000..8310ea0c9f7f17
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-class.js
@@ -0,0 +1,4 @@
+/**
+ * My declaration example.
+ */
+export class MyDeclaration {}
diff --git a/packages/docgen/tests/fixtures/named-class.json b/packages/docgen/tests/fixtures/named-class.json
new file mode 100644
index 00000000000000..163fcdb31cf250
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-class.json
@@ -0,0 +1,53 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 35,
+	"end": 64,
+	"range": [
+		35,
+		64
+	],
+	"declaration": {
+		"type": "ClassDeclaration",
+		"start": 42,
+		"end": 64,
+		"range": [
+			42,
+			64
+		],
+		"id": {
+			"type": "Identifier",
+			"start": 48,
+			"end": 61,
+			"range": [
+				48,
+				61
+			],
+			"name": "MyDeclaration"
+		},
+		"superClass": null,
+		"body": {
+			"type": "ClassBody",
+			"start": 62,
+			"end": 64,
+			"range": [
+				62,
+				64
+			],
+			"body": []
+		}
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
+			"range": [
+				0,
+				34
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 4c113646eddac8..b6ea640e1a487e 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -14,6 +14,16 @@ const getNameDeclaration = require( '../src/get-name-declaration' );
  */
 const test = require( 'tape' );
 
+test( 'returns name for named export (class)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-class.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'MyDeclaration' );
+	t.end();
+} );
+
 test( 'returns name for named export (function)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-function.json' ),

From bb34043017991761adfd52beb05bed8864adabcb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:10:04 +0100
Subject: [PATCH 038/213] Add test for single identifier

---
 .../tests/fixtures/named-identifier-single.js |  6 +++
 .../fixtures/named-identifier-single.json     | 42 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 10 +++++
 3 files changed, 58 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-single.js
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-single.json

diff --git a/packages/docgen/tests/fixtures/named-identifier-single.js b/packages/docgen/tests/fixtures/named-identifier-single.js
new file mode 100644
index 00000000000000..8fbd063086c192
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-single.js
@@ -0,0 +1,6 @@
+/**
+ * My declaration example.
+ */
+function myDeclaration() {}
+
+export { myDeclaration };
diff --git a/packages/docgen/tests/fixtures/named-identifier-single.json b/packages/docgen/tests/fixtures/named-identifier-single.json
new file mode 100644
index 00000000000000..73b4c8f12b95b5
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-single.json
@@ -0,0 +1,42 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 64,
+	"end": 89,
+	"range": [
+		64,
+		89
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 73,
+			"end": 86,
+			"range": [
+				73,
+				86
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 73,
+				"end": 86,
+				"range": [
+					73,
+					86
+				],
+				"name": "myDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 73,
+				"end": 86,
+				"range": [
+					73,
+					86
+				],
+				"name": "myDeclaration"
+			}
+		}
+	],
+	"source": null
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index b6ea640e1a487e..195616760ab348 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -43,3 +43,13 @@ test( 'returns name for named export (variable)', function( t ) {
 	t.equal( name, 'myDeclaration' );
 	t.end();
 } );
+
+test( 'returns name for named export (single identifier)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-single.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'myDeclaration' );
+	t.end();
+} );

From 8cc1be85087c89a6d2f1b3378dbaa6e10abc9d25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:15:37 +0100
Subject: [PATCH 039/213] Add test for multiple named identifiers

---
 .../fixtures/named-identifier-multiple.js     |  16 +++
 .../fixtures/named-identifier-multiple.json   | 100 ++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js |  10 ++
 3 files changed, 126 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-multiple.js
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-multiple.json

diff --git a/packages/docgen/tests/fixtures/named-identifier-multiple.js b/packages/docgen/tests/fixtures/named-identifier-multiple.js
new file mode 100644
index 00000000000000..6c608a4eea4e7a
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-multiple.js
@@ -0,0 +1,16 @@
+/**
+ * Function declaration example.
+ */
+function functionDeclaration() {}
+
+/**
+ * Class declaration example.
+ */
+class ClassDeclaration {}
+
+/**
+ * Variable declaration example.
+ */
+const variableDeclaration = true;
+
+export { functionDeclaration, variableDeclaration, ClassDeclaration };
diff --git a/packages/docgen/tests/fixtures/named-identifier-multiple.json b/packages/docgen/tests/fixtures/named-identifier-multiple.json
new file mode 100644
index 00000000000000..918c76213557ca
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-multiple.json
@@ -0,0 +1,100 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 217,
+	"end": 287,
+	"range": [
+		217,
+		287
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 226,
+			"end": 245,
+			"range": [
+				226,
+				245
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 226,
+				"end": 245,
+				"range": [
+					226,
+					245
+				],
+				"name": "functionDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 226,
+				"end": 245,
+				"range": [
+					226,
+					245
+				],
+				"name": "functionDeclaration"
+			}
+		},
+		{
+			"type": "ExportSpecifier",
+			"start": 247,
+			"end": 266,
+			"range": [
+				247,
+				266
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 247,
+				"end": 266,
+				"range": [
+					247,
+					266
+				],
+				"name": "variableDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 247,
+				"end": 266,
+				"range": [
+					247,
+					266
+				],
+				"name": "variableDeclaration"
+			}
+		},
+		{
+			"type": "ExportSpecifier",
+			"start": 268,
+			"end": 284,
+			"range": [
+				268,
+				284
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 268,
+				"end": 284,
+				"range": [
+					268,
+					284
+				],
+				"name": "ClassDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 268,
+				"end": 284,
+				"range": [
+					268,
+					284
+				],
+				"name": "ClassDeclaration"
+			}
+		}
+	],
+	"source": null
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 195616760ab348..d5fd382ca250b6 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -53,3 +53,13 @@ test( 'returns name for named export (single identifier)', function( t ) {
 	t.equal( name, 'myDeclaration' );
 	t.end();
 } );
+
+test( 'returns name for named export (multiple identifier)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-multiple.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
+	t.end();
+} );

From 0f80013e7e6dd6dd98951edcdf58c26bd497a5de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:20:03 +0100
Subject: [PATCH 040/213] Add tests for default export of functions (anonymous
 and named)

---
 .../fixtures/default-function-anonymous.js    |  4 ++
 .../fixtures/default-function-anonymous.json  | 45 ++++++++++++++++
 .../tests/fixtures/default-function-named.js  |  4 ++
 .../fixtures/default-function-named.json      | 54 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 20 +++++++
 5 files changed, 127 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/default-function-anonymous.js
 create mode 100644 packages/docgen/tests/fixtures/default-function-anonymous.json
 create mode 100644 packages/docgen/tests/fixtures/default-function-named.js
 create mode 100644 packages/docgen/tests/fixtures/default-function-named.json

diff --git a/packages/docgen/tests/fixtures/default-function-anonymous.js b/packages/docgen/tests/fixtures/default-function-anonymous.js
new file mode 100644
index 00000000000000..5c8c7e23a946c8
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-anonymous.js
@@ -0,0 +1,4 @@
+/**
+ * Function declaration example.
+ */
+export default function() {}
diff --git a/packages/docgen/tests/fixtures/default-function-anonymous.json b/packages/docgen/tests/fixtures/default-function-anonymous.json
new file mode 100644
index 00000000000000..59f92aac1b9fa7
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-anonymous.json
@@ -0,0 +1,45 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 41,
+	"end": 69,
+	"range": [
+		41,
+		69
+	],
+	"declaration": {
+		"type": "FunctionDeclaration",
+		"start": 56,
+		"end": 69,
+		"range": [
+			56,
+			69
+		],
+		"id": null,
+		"generator": false,
+		"expression": false,
+		"async": false,
+		"params": [],
+		"body": {
+			"type": "BlockStatement",
+			"start": 67,
+			"end": 69,
+			"range": [
+				67,
+				69
+			],
+			"body": []
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-function-named.js b/packages/docgen/tests/fixtures/default-function-named.js
new file mode 100644
index 00000000000000..74318a75d6ab93
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-named.js
@@ -0,0 +1,4 @@
+/**
+ * Function declaration example.
+ */
+export default function myDeclaration() {}
diff --git a/packages/docgen/tests/fixtures/default-function-named.json b/packages/docgen/tests/fixtures/default-function-named.json
new file mode 100644
index 00000000000000..1905a0ebba22de
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-named.json
@@ -0,0 +1,54 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 41,
+	"end": 83,
+	"range": [
+		41,
+		83
+	],
+	"declaration": {
+		"type": "FunctionDeclaration",
+		"start": 56,
+		"end": 83,
+		"range": [
+			56,
+			83
+		],
+		"id": {
+			"type": "Identifier",
+			"start": 65,
+			"end": 78,
+			"range": [
+				65,
+				78
+			],
+			"name": "myDeclaration"
+		},
+		"generator": false,
+		"expression": false,
+		"async": false,
+		"params": [],
+		"body": {
+			"type": "BlockStatement",
+			"start": 81,
+			"end": 83,
+			"range": [
+				81,
+				83
+			],
+			"body": []
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index d5fd382ca250b6..c9cf1a464eee4d 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -63,3 +63,23 @@ test( 'returns name for named export (multiple identifier)', function( t ) {
 	t.equal( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
 	t.end();
 } );
+
+test( 'returns name for default export (function anonymous)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );
+
+test( 'returns name for default export (function named)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-function-named.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );

From 0fb9542d79e0aa18ed5f05f64e952a4b07d4795a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:29:01 +0100
Subject: [PATCH 041/213] Add tests for default export of variables

---
 packages/docgen/src/get-name-declaration.js   |  9 ++--
 .../fixtures/default-variable-anonymous.js    |  4 ++
 .../fixtures/default-variable-anonymous.json  | 32 ++++++++++++
 .../tests/fixtures/default-variable-named.js  |  5 ++
 .../fixtures/default-variable-named.json      | 52 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 20 +++++++
 6 files changed, 118 insertions(+), 4 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/default-variable-anonymous.js
 create mode 100644 packages/docgen/tests/fixtures/default-variable-anonymous.json
 create mode 100644 packages/docgen/tests/fixtures/default-variable-named.js
 create mode 100644 packages/docgen/tests/fixtures/default-variable-named.json

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index b0bd60d190898c..a6b2ae6106f059 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -12,6 +12,10 @@ const { first, get } = require( 'lodash' );
  * @return {?string} Exported declaration name.
  */
 module.exports = function( token ) {
+	if ( token.type === 'ExportDefaultDeclaration' ) {
+		return 'default export';
+	}
+
 	if ( token.declaration === null ) {
 		return first( token.specifiers ).local.name;
 	}
@@ -19,11 +23,8 @@ module.exports = function( token ) {
 	let name;
 	switch ( token.declaration.type ) {
 		case 'ClassDeclaration':
-			name = token.declaration.id.name;
-			break;
-
 		case 'FunctionDeclaration':
-			name = get( token.declaration, [ 'id', 'name' ], 'default export' );
+			name = token.declaration.id.name;
 			break;
 
 		case 'VariableDeclaration':
diff --git a/packages/docgen/tests/fixtures/default-variable-anonymous.js b/packages/docgen/tests/fixtures/default-variable-anonymous.js
new file mode 100644
index 00000000000000..2e1a56238583f6
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-variable-anonymous.js
@@ -0,0 +1,4 @@
+/**
+ * Variable declaration example.
+ */
+export default true;
diff --git a/packages/docgen/tests/fixtures/default-variable-anonymous.json b/packages/docgen/tests/fixtures/default-variable-anonymous.json
new file mode 100644
index 00000000000000..71688384b70d65
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-variable-anonymous.json
@@ -0,0 +1,32 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 41,
+	"end": 61,
+	"range": [
+		41,
+		61
+	],
+	"declaration": {
+		"type": "Literal",
+		"start": 56,
+		"end": 60,
+		"range": [
+			56,
+			60
+		],
+		"value": true,
+		"raw": "true"
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Variable declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-variable-named.js b/packages/docgen/tests/fixtures/default-variable-named.js
new file mode 100644
index 00000000000000..b3c51b207371f8
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-variable-named.js
@@ -0,0 +1,5 @@
+/**
+ * Variable declaration example.
+ */
+let myDeclaration; // eslint-disable-line no-unused-vars
+export default myDeclaration = true;
diff --git a/packages/docgen/tests/fixtures/default-variable-named.json b/packages/docgen/tests/fixtures/default-variable-named.json
new file mode 100644
index 00000000000000..bc38b4f272e3a9
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-variable-named.json
@@ -0,0 +1,52 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 98,
+	"end": 134,
+	"range": [
+		98,
+		134
+	],
+	"declaration": {
+		"type": "AssignmentExpression",
+		"start": 113,
+		"end": 133,
+		"range": [
+			113,
+			133
+		],
+		"operator": "=",
+		"left": {
+			"type": "Identifier",
+			"start": 113,
+			"end": 126,
+			"range": [
+				113,
+				126
+			],
+			"name": "myDeclaration"
+		},
+		"right": {
+			"type": "Literal",
+			"start": 129,
+			"end": 133,
+			"range": [
+				129,
+				133
+			],
+			"value": true,
+			"raw": "true"
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Line",
+			"value": " eslint-disable-line no-unused-vars",
+			"start": 60,
+			"end": 97,
+			"range": [
+				60,
+				97
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index c9cf1a464eee4d..82314d71dd8f52 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -83,3 +83,23 @@ test( 'returns name for default export (function named)', function( t ) {
 	t.equal( name, 'default export' );
 	t.end();
 } );
+
+test( 'returns name for default export (variable anonymous)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-variable-anonymous.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );
+
+test( 'returns name for default export (variable named)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-variable-named.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );

From c3a74d743e27285683d083b02543e3e1afa11c01 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:31:34 +0100
Subject: [PATCH 042/213] Add tests for default export of classes

---
 .../tests/fixtures/default-class-anonymous.js |  4 ++
 .../fixtures/default-class-anonymous.json     | 42 +++++++++++++++
 .../tests/fixtures/default-class-named.js     |  4 ++
 .../tests/fixtures/default-class-named.json   | 51 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 20 ++++++++
 5 files changed, 121 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/default-class-anonymous.js
 create mode 100644 packages/docgen/tests/fixtures/default-class-anonymous.json
 create mode 100644 packages/docgen/tests/fixtures/default-class-named.js
 create mode 100644 packages/docgen/tests/fixtures/default-class-named.json

diff --git a/packages/docgen/tests/fixtures/default-class-anonymous.js b/packages/docgen/tests/fixtures/default-class-anonymous.js
new file mode 100644
index 00000000000000..79ca0d6a39fcdb
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-class-anonymous.js
@@ -0,0 +1,4 @@
+/**
+ * Class declaration example.
+ */
+export default class {}
diff --git a/packages/docgen/tests/fixtures/default-class-anonymous.json b/packages/docgen/tests/fixtures/default-class-anonymous.json
new file mode 100644
index 00000000000000..55951cf7ce10d3
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-class-anonymous.json
@@ -0,0 +1,42 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 38,
+	"end": 61,
+	"range": [
+		38,
+		61
+	],
+	"declaration": {
+		"type": "ClassDeclaration",
+		"start": 53,
+		"end": 61,
+		"range": [
+			53,
+			61
+		],
+		"id": null,
+		"superClass": null,
+		"body": {
+			"type": "ClassBody",
+			"start": 59,
+			"end": 61,
+			"range": [
+				59,
+				61
+			],
+			"body": []
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Class declaration example.\n ",
+			"start": 0,
+			"end": 37,
+			"range": [
+				0,
+				37
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-class-named.js b/packages/docgen/tests/fixtures/default-class-named.js
new file mode 100644
index 00000000000000..91649c8da44b53
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-class-named.js
@@ -0,0 +1,4 @@
+/**
+ * Class declaration example.
+ */
+export default class ClassDeclaration {}
diff --git a/packages/docgen/tests/fixtures/default-class-named.json b/packages/docgen/tests/fixtures/default-class-named.json
new file mode 100644
index 00000000000000..d460be909ffd53
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-class-named.json
@@ -0,0 +1,51 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 38,
+	"end": 78,
+	"range": [
+		38,
+		78
+	],
+	"declaration": {
+		"type": "ClassDeclaration",
+		"start": 53,
+		"end": 78,
+		"range": [
+			53,
+			78
+		],
+		"id": {
+			"type": "Identifier",
+			"start": 59,
+			"end": 75,
+			"range": [
+				59,
+				75
+			],
+			"name": "ClassDeclaration"
+		},
+		"superClass": null,
+		"body": {
+			"type": "ClassBody",
+			"start": 76,
+			"end": 78,
+			"range": [
+				76,
+				78
+			],
+			"body": []
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Class declaration example.\n ",
+			"start": 0,
+			"end": 37,
+			"range": [
+				0,
+				37
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 82314d71dd8f52..67f5a41e82f234 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -103,3 +103,23 @@ test( 'returns name for default export (variable named)', function( t ) {
 	t.equal( name, 'default export' );
 	t.end();
 } );
+
+test( 'returns name for default export (class anonymous)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );
+
+test( 'returns name for default export (class named)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-class-named.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );

From 633e0f9cae4741c3b3a337155f51c5573ccd59d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:34:41 +0100
Subject: [PATCH 043/213] Add tests for default export of identifier

---
 .../tests/fixtures/default-identifier.js      |  6 ++++++
 .../tests/fixtures/default-identifier.json    | 19 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 10 ++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/default-identifier.js
 create mode 100644 packages/docgen/tests/fixtures/default-identifier.json

diff --git a/packages/docgen/tests/fixtures/default-identifier.js b/packages/docgen/tests/fixtures/default-identifier.js
new file mode 100644
index 00000000000000..2a172ecc0578fa
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-identifier.js
@@ -0,0 +1,6 @@
+/**
+ * Class declaration example.
+ */
+class ClassDeclaration {}
+
+export default ClassDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-identifier.json b/packages/docgen/tests/fixtures/default-identifier.json
new file mode 100644
index 00000000000000..6921571287c53b
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-identifier.json
@@ -0,0 +1,19 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 65,
+	"end": 97,
+	"range": [
+		65,
+		97
+	],
+	"declaration": {
+		"type": "Identifier",
+		"start": 80,
+		"end": 96,
+		"range": [
+			80,
+			96
+		],
+		"name": "ClassDeclaration"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 67f5a41e82f234..b80590c90b7593 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -123,3 +123,13 @@ test( 'returns name for default export (class named)', function( t ) {
 	t.equal( name, 'default export' );
 	t.end();
 } );
+
+test( 'returns name for default export (identifier)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-identifier.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, 'default export' );
+	t.end();
+} );

From 009cf5d393c51e5a59ec1abe2aa95488b8564ceb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:52:38 +0100
Subject: [PATCH 044/213] Add test for export redirects (* and default)

---
 .../docgen/tests/fixtures/named-default.js    |  1 +
 .../docgen/tests/fixtures/named-default.json  | 52 +++++++++++++++++++
 packages/docgen/tests/fixtures/named-star.js  |  1 +
 .../docgen/tests/fixtures/named-star.json     | 20 +++++++
 .../docgen/tests/test-get-name-declaration.js | 20 +++++++
 5 files changed, 94 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-default.js
 create mode 100644 packages/docgen/tests/fixtures/named-default.json
 create mode 100644 packages/docgen/tests/fixtures/named-star.js
 create mode 100644 packages/docgen/tests/fixtures/named-star.json

diff --git a/packages/docgen/tests/fixtures/named-default.js b/packages/docgen/tests/fixtures/named-default.js
new file mode 100644
index 00000000000000..d533cc9693579b
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default.js
@@ -0,0 +1 @@
+export { default } from './module';
diff --git a/packages/docgen/tests/fixtures/named-default.json b/packages/docgen/tests/fixtures/named-default.json
new file mode 100644
index 00000000000000..31d5442cd5265b
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default.json
@@ -0,0 +1,52 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 0,
+	"end": 35,
+	"range": [
+		0,
+		35
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 9,
+			"end": 16,
+			"range": [
+				9,
+				16
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 16,
+				"range": [
+					9,
+					16
+				],
+				"name": "default"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 16,
+				"range": [
+					9,
+					16
+				],
+				"name": "default"
+			}
+		}
+	],
+	"source": {
+		"type": "Literal",
+		"start": 24,
+		"end": 34,
+		"range": [
+			24,
+			34
+		],
+		"value": "./module",
+		"raw": "'./module'"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-star.js b/packages/docgen/tests/fixtures/named-star.js
new file mode 100644
index 00000000000000..20a96c9a596af9
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-star.js
@@ -0,0 +1 @@
+export * from './module';
diff --git a/packages/docgen/tests/fixtures/named-star.json b/packages/docgen/tests/fixtures/named-star.json
new file mode 100644
index 00000000000000..18c84ba7e42e57
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-star.json
@@ -0,0 +1,20 @@
+{
+	"type": "ExportAllDeclaration",
+	"start": 0,
+	"end": 25,
+	"range": [
+		0,
+		25
+	],
+	"source": {
+		"type": "Literal",
+		"start": 14,
+		"end": 24,
+		"range": [
+			14,
+			24
+		],
+		"value": "./module",
+		"raw": "'./module'"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index b80590c90b7593..ab9fec5716f921 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -133,3 +133,23 @@ test( 'returns name for default export (identifier)', function( t ) {
 	t.equal( name, 'default export' );
 	t.end();
 } );
+
+test( 'returns name for named export redirections (*)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-star.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, [ 'TODO' ] );
+	t.end();
+} );
+
+test( 'returns name for named export redirections (default)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.equal( name, [ 'TODO' ] );
+	t.end();
+} );

From d939c4a2cce575941a6218545345c1ca6f7e84f2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 18:54:31 +0100
Subject: [PATCH 045/213] Placeholder to implement ExportAllDeclaration

---
 packages/docgen/src/get-name-declaration.js | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index a6b2ae6106f059..7fc06bf86579a0 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -16,6 +16,10 @@ module.exports = function( token ) {
 		return 'default export';
 	}
 
+	if ( token.type === 'ExportAllDeclaration' ) {
+		return 'TODO'; // need to look up in dependency
+	}
+
 	if ( token.declaration === null ) {
 		return first( token.specifiers ).local.name;
 	}

From aca12d4ae9eedca36148c561364f33dde2a27d71 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 19:04:08 +0100
Subject: [PATCH 046/213] Update engine and tests

---
 packages/docgen/src/engine.js        |  5 +++-
 packages/docgen/tests/test-engine.js | 36 ++++++++++++++--------------
 2 files changed, 22 insertions(+), 19 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 3b64a357904d10..08976e0bb54a7b 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -25,7 +25,10 @@ const getExportTokens = ( ast ) => ast.body.filter(
 	].some( ( declaration ) => declaration === node.type )
 );
 
-const getIRFromDependency = ( getCodeFromPath ) => ( path ) => engine( getCodeFromPath( path ) );
+const getIRFromDependency = ( getCodeFromPath ) => ( path ) => {
+	const { ir } = engine( getCodeFromPath( path ) );
+	return ir;
+};
 
 const engine = ( code, getCodeFromPath = () => {} ) => {
 	const result = {};
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 5b981499a62c48..62f7d64ad71984 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -9,7 +9,7 @@ const test = require( 'tape' );
 const engine = require( '../src/engine' );
 
 test( 'engine returns IR for many exports at once', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * First declaration example.
  		 */
@@ -43,7 +43,7 @@ test( 'engine returns IR for many exports at once', ( t ) => {
 } );
 
 test( 'engine returns IR for named export (function)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * My declaration example.
  		 */
@@ -59,7 +59,7 @@ test( 'engine returns IR for named export (function)', ( t ) => {
 } );
 
 test( 'engine returns IR for named export (variable)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * My declaration example.
  		 */
@@ -75,7 +75,7 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 } );
 
 test( 'engine returns IR for named export (single identifier)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 	const myDeclaration = function() {
 		// do nothing
 	}
@@ -93,7 +93,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 } );
 
 test( 'engine returns IR for named export (single identifier) using JSDoc from declaration', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * My declaration example.
  		 */
@@ -111,7 +111,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 } );
 
 test( 'engine returns IR for named export (multiple identifiers) using JSDoc from declaration', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * First declaration example.
  		 */
@@ -146,7 +146,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 			// do nothing
 		}
 	`;
-	const ir = engine(
+	const { ir } = engine(
 		`export { myDeclaration } from './my-dependency';`,
 		getDependency
 	);
@@ -158,7 +158,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 } );
 
 test( 'engine returns IR for default export (named function)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * My declaration example.
  		 */
@@ -174,7 +174,7 @@ test( 'engine returns IR for default export (named function)', ( t ) => {
 } );
 
 test( 'engine returns IR for default export (anonymous function)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
  		 * My declaration example.
  		 */
@@ -190,7 +190,7 @@ test( 'engine returns IR for default export (anonymous function)', ( t ) => {
 } );
 
 test( 'engine returns IR for default export (identifier)', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		function myDeclaration() {
 			// do nothing
 		}
@@ -202,13 +202,13 @@ test( 'engine returns IR for default export (identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
 	);
 	t.end();
 } );
 
 test( 'engine returns IR for default export (identifier) using JSDoc from function', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
 		 * My declaration example.
 		 */
@@ -220,13 +220,13 @@ test( 'engine returns IR for default export (identifier) using JSDoc from functi
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
 	);
 	t.end();
 } );
 
 test( 'engine returns IR for default export (identifier) using JSDoc from variable', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		/**
 		 * My declaration example.
 		 */
@@ -238,13 +238,13 @@ test( 'engine returns IR for default export (identifier) using JSDoc from variab
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
 	);
 	t.end();
 } );
 
 test( 'engine returns IR for undocumented export', ( t ) => {
-	const ir = engine( `
+	const { ir } = engine( `
 		const myDeclaration = function() {
 			// do nothing
 		}
@@ -253,13 +253,13 @@ test( 'engine returns IR for undocumented export', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'Undocumented declaration.', tags: [], name: 'myDeclaration' } ]
+		[ { description: 'Undocumented declaration.', tags: [], name: 'default export' } ]
 	);
 	t.end();
 } );
 
 test( 'engine returns IR for undefined code', ( t ) => {
-	const ir = engine( undefined );
+	const { ir } = engine( undefined );
 	t.deepEqual( ir, [ ] );
 	t.end();
 } );

From 6986119beb60c8de5ed09ed646d6123dbb0d0752 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 19:12:15 +0100
Subject: [PATCH 047/213] Adapt get-name-declaration to return an array

---
 packages/docgen/src/get-name-declaration.js   | 17 ++++++------
 .../docgen/tests/test-get-name-declaration.js | 26 +++++++++----------
 2 files changed, 22 insertions(+), 21 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 7fc06bf86579a0..c135cae33058fe 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -9,34 +9,35 @@ const { first, get } = require( 'lodash' );
  *
  * @param {Object} token Espree node.
  *
- * @return {?string} Exported declaration name.
+ * @return {Array} Exported declaration names.
  */
 module.exports = function( token ) {
 	if ( token.type === 'ExportDefaultDeclaration' ) {
-		return 'default export';
+		return [ 'default export' ];
 	}
 
 	if ( token.type === 'ExportAllDeclaration' ) {
-		return 'TODO'; // need to look up in dependency
+		return [ 'TODO' ]; // need to look up in dependency
 	}
 
+	const name = [];
 	if ( token.declaration === null ) {
-		return first( token.specifiers ).local.name;
+		name.push( first( token.specifiers ).local.name );
+		return name;
 	}
 
-	let name;
 	switch ( token.declaration.type ) {
 		case 'ClassDeclaration':
 		case 'FunctionDeclaration':
-			name = token.declaration.id.name;
+			name.push( token.declaration.id.name );
 			break;
 
 		case 'VariableDeclaration':
-			name = get( first( token.declaration.declarations ), [ 'id', 'name' ] );
+			name.push( get( first( token.declaration.declarations ), [ 'id', 'name' ] ) );
 			break;
 
 		case 'Identifier':
-			name = token.declaration.name;
+			name.push( token.declaration.name );
 			break;
 	}
 
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index ab9fec5716f921..d692d31192ca96 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -20,7 +20,7 @@ test( 'returns name for named export (class)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'MyDeclaration' );
+	t.deepEqual( name, [ 'MyDeclaration' ] );
 	t.end();
 } );
 
@@ -30,7 +30,7 @@ test( 'returns name for named export (function)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'myDeclaration' );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
@@ -40,7 +40,7 @@ test( 'returns name for named export (variable)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'myDeclaration' );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
@@ -50,7 +50,7 @@ test( 'returns name for named export (single identifier)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'myDeclaration' );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
@@ -70,7 +70,7 @@ test( 'returns name for default export (function anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -80,7 +80,7 @@ test( 'returns name for default export (function named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -90,7 +90,7 @@ test( 'returns name for default export (variable anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -100,7 +100,7 @@ test( 'returns name for default export (variable named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -110,7 +110,7 @@ test( 'returns name for default export (class anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -120,7 +120,7 @@ test( 'returns name for default export (class named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -130,7 +130,7 @@ test( 'returns name for default export (identifier)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, 'default export' );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
@@ -140,7 +140,7 @@ test( 'returns name for named export redirections (*)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, [ 'TODO' ] );
+	t.deepEqual( name, [ 'TODO: to look up in module' ] );
 	t.end();
 } );
 
@@ -150,6 +150,6 @@ test( 'returns name for named export redirections (default)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, [ 'TODO' ] );
+	t.deepEqual( name, [ 'TODO: default export?' ] );
 	t.end();
 } );

From 4b063a0138f54373827a57f97793ccec39fb34f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 18 Jan 2019 19:16:34 +0100
Subject: [PATCH 048/213] Implement retrieval of multiple specifiers

---
 packages/docgen/src/get-name-declaration.js        | 2 +-
 packages/docgen/tests/test-get-name-declaration.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index c135cae33058fe..0af34ba81b923c 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -22,7 +22,7 @@ module.exports = function( token ) {
 
 	const name = [];
 	if ( token.declaration === null ) {
-		name.push( first( token.specifiers ).local.name );
+		token.specifiers.forEach( ( specifier ) => name.push( specifier.local.name ) );
 		return name;
 	}
 
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index d692d31192ca96..adf224a3a36a60 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -60,7 +60,7 @@ test( 'returns name for named export (multiple identifier)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.equal( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
+	t.deepEqual( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
 	t.end();
 } );
 

From 255af56c4aabdba93a7ea99fbb88e73edfd77f41 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 17:42:55 +0100
Subject: [PATCH 049/213] Reorganize test to prepare next steps

---
 ...entifier-single.js => named-identifier.js} |  0
 ...fier-single.json => named-identifier.json} |  0
 ...ifier-multiple.js => named-identifiers.js} |  0
 ...r-multiple.json => named-identifiers.json} |  0
 .../fixtures/{named-star.js => namespace.js}  |  0
 .../{named-star.json => namespace.json}       |  0
 .../docgen/tests/test-get-name-declaration.js | 80 +++++++++----------
 7 files changed, 40 insertions(+), 40 deletions(-)
 rename packages/docgen/tests/fixtures/{named-identifier-single.js => named-identifier.js} (100%)
 rename packages/docgen/tests/fixtures/{named-identifier-single.json => named-identifier.json} (100%)
 rename packages/docgen/tests/fixtures/{named-identifier-multiple.js => named-identifiers.js} (100%)
 rename packages/docgen/tests/fixtures/{named-identifier-multiple.json => named-identifiers.json} (100%)
 rename packages/docgen/tests/fixtures/{named-star.js => namespace.js} (100%)
 rename packages/docgen/tests/fixtures/{named-star.json => namespace.json} (100%)

diff --git a/packages/docgen/tests/fixtures/named-identifier-single.js b/packages/docgen/tests/fixtures/named-identifier.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-single.js
rename to packages/docgen/tests/fixtures/named-identifier.js
diff --git a/packages/docgen/tests/fixtures/named-identifier-single.json b/packages/docgen/tests/fixtures/named-identifier.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-single.json
rename to packages/docgen/tests/fixtures/named-identifier.json
diff --git a/packages/docgen/tests/fixtures/named-identifier-multiple.js b/packages/docgen/tests/fixtures/named-identifiers.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-multiple.js
rename to packages/docgen/tests/fixtures/named-identifiers.js
diff --git a/packages/docgen/tests/fixtures/named-identifier-multiple.json b/packages/docgen/tests/fixtures/named-identifiers.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-multiple.json
rename to packages/docgen/tests/fixtures/named-identifiers.json
diff --git a/packages/docgen/tests/fixtures/named-star.js b/packages/docgen/tests/fixtures/namespace.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-star.js
rename to packages/docgen/tests/fixtures/namespace.js
diff --git a/packages/docgen/tests/fixtures/named-star.json b/packages/docgen/tests/fixtures/namespace.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-star.json
rename to packages/docgen/tests/fixtures/namespace.json
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index adf224a3a36a60..4151e999807aa7 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -14,59 +14,59 @@ const getNameDeclaration = require( '../src/get-name-declaration' );
  */
 const test = require( 'tape' );
 
-test( 'returns name for named export (class)', function( t ) {
+test( 'default export class (anonymous)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-class.json' ),
+		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'MyDeclaration' ] );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
-test( 'returns name for named export (function)', function( t ) {
+test( 'default export class (named)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function.json' ),
+		path.join( __dirname, './fixtures/default-class-named.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
-test( 'returns name for named export (variable)', function( t ) {
+test( 'default export function (anonymous)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variable.json' ),
+		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
-test( 'returns name for named export (single identifier)', function( t ) {
+test( 'default export function (named)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-single.json' ),
+		path.join( __dirname, './fixtures/default-function-named.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
-test( 'returns name for named export (multiple identifier)', function( t ) {
+test( 'default export identifier', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-multiple.json' ),
+		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
+	t.deepEqual( name, [ 'default export' ] );
 	t.end();
 } );
 
-test( 'returns name for default export (function anonymous)', function( t ) {
+test( 'default export variable (anonymous)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
+		path.join( __dirname, './fixtures/default-variable-anonymous.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
@@ -74,9 +74,9 @@ test( 'returns name for default export (function anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'returns name for default export (function named)', function( t ) {
+test( 'default export variable (named)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-named.json' ),
+		path.join( __dirname, './fixtures/default-variable-named.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
@@ -84,72 +84,72 @@ test( 'returns name for default export (function named)', function( t ) {
 	t.end();
 } );
 
-test( 'returns name for default export (variable anonymous)', function( t ) {
+test( 'named export class', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable-anonymous.json' ),
+		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ 'MyDeclaration' ] );
 	t.end();
 } );
 
-test( 'returns name for default export (variable named)', function( t ) {
+test( 'named export default', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable-named.json' ),
+		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ 'TODO: default export?' ] );
 	t.end();
 } );
 
-test( 'returns name for default export (class anonymous)', function( t ) {
+test( 'named export function', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
+		path.join( __dirname, './fixtures/named-function.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
-test( 'returns name for default export (class named)', function( t ) {
+test( 'named export identifier', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-named.json' ),
+		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
-test( 'returns name for default export (identifier)', function( t ) {
+test( 'named export identifiers', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier.json' ),
+		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
 	t.end();
 } );
 
-test( 'returns name for named export redirections (*)', function( t ) {
+test( 'named export variable', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-star.json' ),
+		path.join( __dirname, './fixtures/named-variable.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'TODO: to look up in module' ] );
+	t.deepEqual( name, [ 'myDeclaration' ] );
 	t.end();
 } );
 
-test( 'returns name for named export redirections (default)', function( t ) {
+test( 'namespace export (*)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default.json' ),
+		path.join( __dirname, './fixtures/namespace.json' ),
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'TODO: default export?' ] );
+	t.deepEqual( name, [ 'TODO: to look up in module' ] );
 	t.end();
 } );

From ec547fc1789c00d5ce8caba4e7db30fbeeb773c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 18:06:55 +0100
Subject: [PATCH 050/213] Refactor default and namespace exports

---
 packages/docgen/src/get-name-declaration.js   | 30 +++++++++-
 .../docgen/tests/test-get-name-declaration.js | 56 ++++++++++++++++---
 2 files changed, 76 insertions(+), 10 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 0af34ba81b923c..26dba7639ba9c9 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -13,11 +13,37 @@ const { first, get } = require( 'lodash' );
  */
 module.exports = function( token ) {
 	if ( token.type === 'ExportDefaultDeclaration' ) {
-		return [ 'default export' ];
+		const getLocalName = ( t ) => {
+			let name;
+			switch ( t.declaration.type ) {
+				case 'Identifier':
+					name = t.declaration.name;
+					break;
+				case 'AssignmentExpression':
+					name = t.declaration.left.name;
+					break;
+				//case 'FunctionDeclaration'
+				//case 'ClassDeclaration'
+				default:
+					name = get( t.declaration, [ 'id', 'name' ], '*default*' );
+			}
+			return name;
+		};
+		return [ {
+			importName: null,
+			localName: getLocalName( token ),
+			exportName: 'default',
+			module: null,
+		} ];
 	}
 
 	if ( token.type === 'ExportAllDeclaration' ) {
-		return [ 'TODO' ]; // need to look up in dependency
+		return [ {
+			importName: '*',
+			localName: null,
+			exportName: null,
+			module: token.source.value,
+		} ];
 	}
 
 	const name = [];
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 4151e999807aa7..2e00bad8c229c0 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -20,7 +20,12 @@ test( 'default export class (anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: '*default*',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -30,7 +35,12 @@ test( 'default export class (named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: 'ClassDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -40,7 +50,12 @@ test( 'default export function (anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: '*default*',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -50,7 +65,12 @@ test( 'default export function (named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: 'myDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -60,7 +80,12 @@ test( 'default export identifier', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: 'ClassDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -70,7 +95,12 @@ test( 'default export variable (anonymous)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: '*default*',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -80,7 +110,12 @@ test( 'default export variable (named)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'default export' ] );
+	t.deepEqual( name, [ {
+		importName: null,
+		localName: 'myDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -150,6 +185,11 @@ test( 'namespace export (*)', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'TODO: to look up in module' ] );
+	t.deepEqual( name, [ {
+		importName: '*',
+		localName: null,
+		exportName: null,
+		module: './module',
+	} ] );
 	t.end();
 } );

From 9f5eafb8bde187547123fb4ea79b790729af1527 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 18:19:31 +0100
Subject: [PATCH 051/213] Flatten importName and localName

Although the standard differentiate between the two
http://www.ecma-international.org/ecma-262/9.0/#exportentry-record
importName and localName are disjoint sets: if module is set,
the name is stored in importName variable and if it is unset,
the name is stored in localName variable.

Espree doesn't make that difference.
---
 packages/docgen/src/get-name-declaration.js        |  4 +---
 packages/docgen/tests/test-get-name-declaration.js | 10 +---------
 2 files changed, 2 insertions(+), 12 deletions(-)

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index 26dba7639ba9c9..ce00afaf954e1a 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -30,7 +30,6 @@ module.exports = function( token ) {
 			return name;
 		};
 		return [ {
-			importName: null,
 			localName: getLocalName( token ),
 			exportName: 'default',
 			module: null,
@@ -39,8 +38,7 @@ module.exports = function( token ) {
 
 	if ( token.type === 'ExportAllDeclaration' ) {
 		return [ {
-			importName: '*',
-			localName: null,
+			localName: '*',
 			exportName: null,
 			module: token.source.value,
 		} ];
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index 2e00bad8c229c0..f2142a4ba11285 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -21,7 +21,6 @@ test( 'default export class (anonymous)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
@@ -36,7 +35,6 @@ test( 'default export class (named)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: 'ClassDeclaration',
 		exportName: 'default',
 		module: null,
@@ -51,7 +49,6 @@ test( 'default export function (anonymous)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
@@ -66,7 +63,6 @@ test( 'default export function (named)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: 'myDeclaration',
 		exportName: 'default',
 		module: null,
@@ -81,7 +77,6 @@ test( 'default export identifier', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: 'ClassDeclaration',
 		exportName: 'default',
 		module: null,
@@ -96,7 +91,6 @@ test( 'default export variable (anonymous)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
@@ -111,7 +105,6 @@ test( 'default export variable (named)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: null,
 		localName: 'myDeclaration',
 		exportName: 'default',
 		module: null,
@@ -186,8 +179,7 @@ test( 'namespace export (*)', function( t ) {
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		importName: '*',
-		localName: null,
+		localName: '*',
 		exportName: null,
 		module: './module',
 	} ] );

From dc95707f70e5a9931f42c7cfb866eafac65dacff Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 18:47:38 +0100
Subject: [PATCH 052/213] get-name-declaration: refactor to return export entry
 list

---
 packages/docgen/src/get-name-declaration.js   | 40 +++++---
 .../docgen/tests/fixtures/named-variables.js  |  6 ++
 .../tests/fixtures/named-variables.json       | 95 +++++++++++++++++++
 .../docgen/tests/test-get-name-declaration.js | 49 ++++++++--
 4 files changed, 172 insertions(+), 18 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-variables.js
 create mode 100644 packages/docgen/tests/fixtures/named-variables.json

diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-name-declaration.js
index ce00afaf954e1a..be3ac15802f92d 100644
--- a/packages/docgen/src/get-name-declaration.js
+++ b/packages/docgen/src/get-name-declaration.js
@@ -1,15 +1,21 @@
 /**
  * External dependencies
  */
-const { first, get } = require( 'lodash' );
+const { get } = require( 'lodash' );
 
 /**
- * Returns the assigned name for a given export node type,
- * or undefined if it cannot be determined.
+ * Returns the export entry records of the given export statement.
+ * Unlike [the standard](http://www.ecma-international.org/ecma-262/9.0/#exportentry-record),
+ * the `importName` and the `localName` are merged together.
  *
- * @param {Object} token Espree node.
+ * @param {Object} token Espree node representing an export.
  *
- * @return {Array} Exported declaration names.
+ * @return {Array} Exported entry records. Example:
+ * [ {
+ *    localName: 'localName',
+ *    exportName: 'exportedName',
+ *    module: null,
+ * } ]
  */
 module.exports = function( token ) {
 	if ( token.type === 'ExportDefaultDeclaration' ) {
@@ -46,22 +52,32 @@ module.exports = function( token ) {
 
 	const name = [];
 	if ( token.declaration === null ) {
-		token.specifiers.forEach( ( specifier ) => name.push( specifier.local.name ) );
+		token.specifiers.forEach( ( specifier ) => name.push( {
+			localName: specifier.local.name,
+			exportName: specifier.local.name,
+			module: null,
+		} ) );
 		return name;
 	}
 
 	switch ( token.declaration.type ) {
 		case 'ClassDeclaration':
 		case 'FunctionDeclaration':
-			name.push( token.declaration.id.name );
+			name.push( {
+				localName: token.declaration.id.name,
+				exportName: token.declaration.id.name,
+				module: null,
+			} );
 			break;
 
 		case 'VariableDeclaration':
-			name.push( get( first( token.declaration.declarations ), [ 'id', 'name' ] ) );
-			break;
-
-		case 'Identifier':
-			name.push( token.declaration.name );
+			token.declaration.declarations.forEach( ( declaration ) => {
+				name.push( {
+					localName: declaration.id.name,
+					exportName: declaration.id.name,
+					module: null,
+				} );
+			} );
 			break;
 	}
 
diff --git a/packages/docgen/tests/fixtures/named-variables.js b/packages/docgen/tests/fixtures/named-variables.js
new file mode 100644
index 00000000000000..8f56e0aff46e5a
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-variables.js
@@ -0,0 +1,6 @@
+/**
+ * My declaration example.
+ */
+export const firstDeclaration = true,
+	secondDeclaration = 42;
+
diff --git a/packages/docgen/tests/fixtures/named-variables.json b/packages/docgen/tests/fixtures/named-variables.json
new file mode 100644
index 00000000000000..ac491c7dcafc04
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-variables.json
@@ -0,0 +1,95 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 35,
+	"end": 97,
+	"range": [
+		35,
+		97
+	],
+	"declaration": {
+		"type": "VariableDeclaration",
+		"start": 42,
+		"end": 97,
+		"range": [
+			42,
+			97
+		],
+		"declarations": [
+			{
+				"type": "VariableDeclarator",
+				"start": 48,
+				"end": 71,
+				"range": [
+					48,
+					71
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 48,
+					"end": 64,
+					"range": [
+						48,
+						64
+					],
+					"name": "firstDeclaration"
+				},
+				"init": {
+					"type": "Literal",
+					"start": 67,
+					"end": 71,
+					"range": [
+						67,
+						71
+					],
+					"value": true,
+					"raw": "true"
+				}
+			},
+			{
+				"type": "VariableDeclarator",
+				"start": 74,
+				"end": 96,
+				"range": [
+					74,
+					96
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 74,
+					"end": 91,
+					"range": [
+						74,
+						91
+					],
+					"name": "secondDeclaration"
+				},
+				"init": {
+					"type": "Literal",
+					"start": 94,
+					"end": 96,
+					"range": [
+						94,
+						96
+					],
+					"value": 42,
+					"raw": "42"
+				}
+			}
+		],
+		"kind": "const"
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
+			"range": [
+				0,
+				34
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-name-declaration.js
index f2142a4ba11285..c0de9a9b74e50c 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-name-declaration.js
@@ -118,7 +118,11 @@ test( 'named export class', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'MyDeclaration' ] );
+	t.deepEqual( name, [ {
+		localName: 'MyDeclaration',
+		exportName: 'MyDeclaration',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -128,7 +132,11 @@ test( 'named export default', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'TODO: default export?' ] );
+	t.deepEqual( name, [ {
+		localName: 'default',
+		exportName: 'default',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -138,7 +146,11 @@ test( 'named export function', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ {
+		localName: 'myDeclaration',
+		exportName: 'myDeclaration',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -148,7 +160,11 @@ test( 'named export identifier', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ {
+		localName: 'myDeclaration',
+		exportName: 'myDeclaration',
+		module: null,
+	} ] );
 	t.end();
 } );
 
@@ -158,7 +174,11 @@ test( 'named export identifiers', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'functionDeclaration', 'variableDeclaration', 'ClassDeclaration' ] );
+	t.deepEqual( name, [
+		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null },
+		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
+		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null },
+	] );
 	t.end();
 } );
 
@@ -168,7 +188,24 @@ test( 'named export variable', function( t ) {
 		'utf-8'
 	);
 	const name = getNameDeclaration( JSON.parse( token ) );
-	t.deepEqual( name, [ 'myDeclaration' ] );
+	t.deepEqual( name, [ {
+		localName: 'myDeclaration',
+		exportName: 'myDeclaration',
+		module: null,
+	} ] );
+	t.end();
+} );
+
+test( 'named export variables', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-variables.json' ),
+		'utf-8'
+	);
+	const name = getNameDeclaration( JSON.parse( token ) );
+	t.deepEqual( name, [
+		{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null },
+		{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null },
+	] );
 	t.end();
 } );
 

From 10b271fa3c4e37ddcb76f639fb3ac89dbbaa7515 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 18:49:54 +0100
Subject: [PATCH 053/213] get-name-declaration renamed to get-export-entries

---
 packages/docgen/package.json                  |  2 +-
 ...e-declaration.js => get-export-entries.js} |  0
 .../src/get-intermediate-representation.js    |  2 +-
 ...laration.js => test-get-export-entries.js} | 32 +++++++++----------
 4 files changed, 18 insertions(+), 18 deletions(-)
 rename packages/docgen/src/{get-name-declaration.js => get-export-entries.js} (100%)
 rename packages/docgen/tests/{test-get-name-declaration.js => test-get-export-entries.js} (83%)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 4fe91d84b877dc..97bd4310983a43 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -27,6 +27,6 @@
 	"scripts": {
 		"test": "tape tests/test-*.js | faucet",
 		"test:engine": "tape tests/test-engine.js | faucet",
-		"test:get-name-declaration": "tape tests/test-get-name-declaration.js | faucet"
+		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet"
 	}
 }
diff --git a/packages/docgen/src/get-name-declaration.js b/packages/docgen/src/get-export-entries.js
similarity index 100%
rename from packages/docgen/src/get-name-declaration.js
rename to packages/docgen/src/get-export-entries.js
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 8f6fd6153d1810..697c6c97a009d0 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -6,7 +6,7 @@ const { first } = require( 'lodash' );
 /**
  * Internal dependencies.
  */
-const getNameDeclaration = require( './get-name-declaration' );
+const getNameDeclaration = require( './get-export-entries' );
 const getJSDoc = require( './get-jsdoc' );
 const isIdentifierInSameFile = require( './is-identifier-in-same-file' );
 const isIdentifierInDependency = require( './is-identifier-in-dependency' );
diff --git a/packages/docgen/tests/test-get-name-declaration.js b/packages/docgen/tests/test-get-export-entries.js
similarity index 83%
rename from packages/docgen/tests/test-get-name-declaration.js
rename to packages/docgen/tests/test-get-export-entries.js
index c0de9a9b74e50c..43c3e81113d648 100644
--- a/packages/docgen/tests/test-get-name-declaration.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -7,7 +7,7 @@ const path = require( 'path' );
 /**
  * Internal dependencies.
  */
-const getNameDeclaration = require( '../src/get-name-declaration' );
+const getExportEntries = require( '../src/get-export-entries' );
 
 /**
  * External dependencies.
@@ -19,7 +19,7 @@ test( 'default export class (anonymous)', function( t ) {
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: '*default*',
 		exportName: 'default',
@@ -33,7 +33,7 @@ test( 'default export class (named)', function( t ) {
 		path.join( __dirname, './fixtures/default-class-named.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'ClassDeclaration',
 		exportName: 'default',
@@ -47,7 +47,7 @@ test( 'default export function (anonymous)', function( t ) {
 		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: '*default*',
 		exportName: 'default',
@@ -61,7 +61,7 @@ test( 'default export function (named)', function( t ) {
 		path.join( __dirname, './fixtures/default-function-named.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'myDeclaration',
 		exportName: 'default',
@@ -75,7 +75,7 @@ test( 'default export identifier', function( t ) {
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'ClassDeclaration',
 		exportName: 'default',
@@ -89,7 +89,7 @@ test( 'default export variable (anonymous)', function( t ) {
 		path.join( __dirname, './fixtures/default-variable-anonymous.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: '*default*',
 		exportName: 'default',
@@ -103,7 +103,7 @@ test( 'default export variable (named)', function( t ) {
 		path.join( __dirname, './fixtures/default-variable-named.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'myDeclaration',
 		exportName: 'default',
@@ -117,7 +117,7 @@ test( 'named export class', function( t ) {
 		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'MyDeclaration',
 		exportName: 'MyDeclaration',
@@ -131,7 +131,7 @@ test( 'named export default', function( t ) {
 		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'default',
 		exportName: 'default',
@@ -145,7 +145,7 @@ test( 'named export function', function( t ) {
 		path.join( __dirname, './fixtures/named-function.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
@@ -159,7 +159,7 @@ test( 'named export identifier', function( t ) {
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
@@ -173,7 +173,7 @@ test( 'named export identifiers', function( t ) {
 		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [
 		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null },
 		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
@@ -187,7 +187,7 @@ test( 'named export variable', function( t ) {
 		path.join( __dirname, './fixtures/named-variable.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
@@ -201,7 +201,7 @@ test( 'named export variables', function( t ) {
 		path.join( __dirname, './fixtures/named-variables.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [
 		{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null },
 		{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null },
@@ -214,7 +214,7 @@ test( 'namespace export (*)', function( t ) {
 		path.join( __dirname, './fixtures/namespace.json' ),
 		'utf-8'
 	);
-	const name = getNameDeclaration( JSON.parse( token ) );
+	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
 		localName: '*',
 		exportName: null,

From 461ec44964fc94329a1d7f8e416ad90519ba1d7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 19:40:02 +0100
Subject: [PATCH 054/213] Reorder dependency statements

---
 packages/docgen/tests/test-get-export-entries.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 43c3e81113d648..e701c4f10645d3 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -5,14 +5,14 @@ const fs = require( 'fs' );
 const path = require( 'path' );
 
 /**
- * Internal dependencies.
+ * External dependencies.
  */
-const getExportEntries = require( '../src/get-export-entries' );
+const test = require( 'tape' );
 
 /**
- * External dependencies.
+ * Internal dependencies.
  */
-const test = require( 'tape' );
+const getExportEntries = require( '../src/get-export-entries' );
 
 test( 'default export class (anonymous)', function( t ) {
 	const token = fs.readFileSync(

From e714f9af095d3739b078596901d3f5a0bbc1ba12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 19:42:33 +0100
Subject: [PATCH 055/213] Remove uncessary test

---
 .../tests/fixtures/default-variable-named.js  |  5 --
 .../fixtures/default-variable-named.json      | 52 -------------------
 ...iable-anonymous.js => default-variable.js} |  0
 ...e-anonymous.json => default-variable.json} |  0
 .../docgen/tests/test-get-export-entries.js   | 18 +------
 5 files changed, 2 insertions(+), 73 deletions(-)
 delete mode 100644 packages/docgen/tests/fixtures/default-variable-named.js
 delete mode 100644 packages/docgen/tests/fixtures/default-variable-named.json
 rename packages/docgen/tests/fixtures/{default-variable-anonymous.js => default-variable.js} (100%)
 rename packages/docgen/tests/fixtures/{default-variable-anonymous.json => default-variable.json} (100%)

diff --git a/packages/docgen/tests/fixtures/default-variable-named.js b/packages/docgen/tests/fixtures/default-variable-named.js
deleted file mode 100644
index b3c51b207371f8..00000000000000
--- a/packages/docgen/tests/fixtures/default-variable-named.js
+++ /dev/null
@@ -1,5 +0,0 @@
-/**
- * Variable declaration example.
- */
-let myDeclaration; // eslint-disable-line no-unused-vars
-export default myDeclaration = true;
diff --git a/packages/docgen/tests/fixtures/default-variable-named.json b/packages/docgen/tests/fixtures/default-variable-named.json
deleted file mode 100644
index bc38b4f272e3a9..00000000000000
--- a/packages/docgen/tests/fixtures/default-variable-named.json
+++ /dev/null
@@ -1,52 +0,0 @@
-{
-	"type": "ExportDefaultDeclaration",
-	"start": 98,
-	"end": 134,
-	"range": [
-		98,
-		134
-	],
-	"declaration": {
-		"type": "AssignmentExpression",
-		"start": 113,
-		"end": 133,
-		"range": [
-			113,
-			133
-		],
-		"operator": "=",
-		"left": {
-			"type": "Identifier",
-			"start": 113,
-			"end": 126,
-			"range": [
-				113,
-				126
-			],
-			"name": "myDeclaration"
-		},
-		"right": {
-			"type": "Literal",
-			"start": 129,
-			"end": 133,
-			"range": [
-				129,
-				133
-			],
-			"value": true,
-			"raw": "true"
-		}
-	},
-	"leadingComments": [
-		{
-			"type": "Line",
-			"value": " eslint-disable-line no-unused-vars",
-			"start": 60,
-			"end": 97,
-			"range": [
-				60,
-				97
-			]
-		}
-	]
-}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-variable-anonymous.js b/packages/docgen/tests/fixtures/default-variable.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-variable-anonymous.js
rename to packages/docgen/tests/fixtures/default-variable.js
diff --git a/packages/docgen/tests/fixtures/default-variable-anonymous.json b/packages/docgen/tests/fixtures/default-variable.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-variable-anonymous.json
rename to packages/docgen/tests/fixtures/default-variable.json
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index e701c4f10645d3..d53a3bb43d294a 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -84,9 +84,9 @@ test( 'default export identifier', function( t ) {
 	t.end();
 } );
 
-test( 'default export variable (anonymous)', function( t ) {
+test( 'default export variable', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable-anonymous.json' ),
+		path.join( __dirname, './fixtures/default-variable.json' ),
 		'utf-8'
 	);
 	const name = getExportEntries( JSON.parse( token ) );
@@ -98,20 +98,6 @@ test( 'default export variable (anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'default export variable (named)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable-named.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'myDeclaration',
-		exportName: 'default',
-		module: null,
-	} ] );
-	t.end();
-} );
-
 test( 'named export class', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-class.json' ),

From d59f26c3b648a5da73cf6cf1ef5274ae9cf58a5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 20:29:25 +0100
Subject: [PATCH 056/213] Refactor get IR and add tests for default exports

---
 packages/docgen/package.json                  |  3 +-
 .../src/get-intermediate-representation.js    | 75 +++++++++-------
 .../docgen/src/is-identifier-in-dependency.js |  8 --
 .../docgen/src/is-identifier-in-same-file.js  | 13 ---
 .../fixtures/default-identifier-ast.json      | 85 +++++++++++++++++++
 .../test-get-intermediate-representation.js   | 81 ++++++++++++++++++
 6 files changed, 210 insertions(+), 55 deletions(-)
 delete mode 100644 packages/docgen/src/is-identifier-in-dependency.js
 delete mode 100644 packages/docgen/src/is-identifier-in-same-file.js
 create mode 100644 packages/docgen/tests/fixtures/default-identifier-ast.json
 create mode 100644 packages/docgen/tests/test-get-intermediate-representation.js

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 97bd4310983a43..830686a1c080ab 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -27,6 +27,7 @@
 	"scripts": {
 		"test": "tape tests/test-*.js | faucet",
 		"test:engine": "tape tests/test-engine.js | faucet",
-		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet"
+		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
+		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet"
 	}
 }
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 697c6c97a009d0..2b851bbc832c6b 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -1,52 +1,61 @@
 /**
  * External dependencies.
  */
-const { first } = require( 'lodash' );
+const { get } = require( 'lodash' );
 
 /**
  * Internal dependencies.
  */
-const getNameDeclaration = require( './get-export-entries' );
-const getJSDoc = require( './get-jsdoc' );
-const isIdentifierInSameFile = require( './is-identifier-in-same-file' );
-const isIdentifierInDependency = require( './is-identifier-in-dependency' );
+const getExportEntries = require( './get-export-entries' );
+const getJSDocFromToken = require( './get-jsdoc' );
 const getDependencyPath = require( './get-dependency-path' );
 
+const UNDOCUMENTED = 'Undocumented declaration.';
+
+const getJSDoc = ( token, entry, ast, parseDependency ) => {
+	let doc = getJSDocFromToken( token );
+	if ( doc === undefined && entry.module === null ) {
+		const candidates = ast.body.filter( ( node ) => {
+			return ( node.type === 'ClassDeclaration' && node.id.name === entry.localName ) ||
+				( node.type === 'FunctionDeclaration' && node.id.name === entry.localName ) ||
+				( node.type === 'VariableDeclaration' && ( node.declarations ).some(
+					( declaration ) => declaration.id.name === entry.localName )
+				);
+		} );
+		if ( candidates.length === 1 ) {
+			doc = getJSDoc( candidates[ 0 ] );
+		}
+	} else if ( doc === undefined && entry.module !== null ) {
+		const irFromDependency = parseDependency( getDependencyPath( token ) );
+		doc = irFromDependency.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+	}
+	return doc;
+};
+
 /**
- * Takes a export token and the file AST
- * and returns an intermediate representation in JSON.
+ * Takes a export token and returns an intermediate representation in JSON.
+ *
+ * If the export token doesn't contain any JSDoc, and it's a identifier,
+ * the identifier declaration will be looked up in the file or dependency
+ * if an `ast` and `parseDependency` callback are provided.
  *
  * @param {Object} token Espree export token.
- * @param {Object} ast Espree ast of a single file.
- * @param {Function} parseDependency Function that takes a path
+ * @param {Object} [ast] Espree ast of a single file.
+ * @param {Function} [parseDependency] Function that takes a path
  * and returns the AST of the dependency file.
  *
  * @return {Object} Intermediate Representation in JSON.
  */
-module.exports = function( token, ast, parseDependency = () => {} ) {
-	let ir = getJSDoc( token );
-	const name = getNameDeclaration( token );
-	// If at this point, the ir is undefined, we'll lookup JSDoc comments either:
-	// 1) in the same file declaration
-	// 2) in the dependency file declaration
-	if ( ir === undefined && isIdentifierInSameFile( token ) ) {
-		const candidates = ast.body.filter( ( node ) => {
-			return ( node.type === 'FunctionDeclaration' && node.id.name === name ) ||
-			( node.type === 'VariableDeclaration' && first( node.declarations ).id.name === name );
+module.exports = function( token, ast = { body: [] }, parseDependency = () => {} ) {
+	const exportEntries = getExportEntries( token );
+	const ir = [];
+	exportEntries.forEach( ( entry ) => {
+		const doc = getJSDoc( token, entry, ast, parseDependency );
+		ir.push( {
+			name: entry.exportName,
+			description: get( doc, [ 'description' ], UNDOCUMENTED ),
+			tags: [],
 		} );
-		if ( candidates.length === 1 ) {
-			ir = getJSDoc( candidates[ 0 ] );
-		}
-	} else if ( ir === undefined && isIdentifierInDependency( token ) ) {
-		const irFromDependency = parseDependency( getDependencyPath( token ) );
-		ir = irFromDependency.find( ( exportDeclaration ) => exportDeclaration.name === name );
-	}
-
-	// Sometimes, humans do not add JSDoc, though.
-	if ( ir === undefined ) {
-		ir = { description: 'Undocumented declaration.', tags: [] };
-	}
-
-	ir.name = name;
+	} );
 	return ir;
 };
diff --git a/packages/docgen/src/is-identifier-in-dependency.js b/packages/docgen/src/is-identifier-in-dependency.js
deleted file mode 100644
index 261b7bd888828e..00000000000000
--- a/packages/docgen/src/is-identifier-in-dependency.js
+++ /dev/null
@@ -1,8 +0,0 @@
-module.exports = function( token ) {
-	if ( token.declaration === null &&
-		token.specifiers !== null &&
-		token.specifiers.length > 0 &&
-		token.source !== null ) {
-		return true;
-	}
-};
diff --git a/packages/docgen/src/is-identifier-in-same-file.js b/packages/docgen/src/is-identifier-in-same-file.js
deleted file mode 100644
index a0389f48917cab..00000000000000
--- a/packages/docgen/src/is-identifier-in-same-file.js
+++ /dev/null
@@ -1,13 +0,0 @@
-module.exports = function( token ) {
-	if ( token.declaration !== null &&
-		token.declaration.type === 'Identifier' ) {
-		return true;
-	}
-	if ( token.declaration === null &&
-		token.specifiers !== null &&
-		token.specifiers.length > 0 &&
-		token.source === null ) {
-		return true;
-	}
-	return false;
-};
diff --git a/packages/docgen/tests/fixtures/default-identifier-ast.json b/packages/docgen/tests/fixtures/default-identifier-ast.json
new file mode 100644
index 00000000000000..b7852864bcecda
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-identifier-ast.json
@@ -0,0 +1,85 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 98,
+	"range": [
+		38,
+		97
+	],
+	"body": [
+		{
+			"type": "ClassDeclaration",
+			"start": 38,
+			"end": 63,
+			"range": [
+				38,
+				63
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 44,
+				"end": 60,
+				"range": [
+					44,
+					60
+				],
+				"name": "ClassDeclaration"
+			},
+			"superClass": null,
+			"body": {
+				"type": "ClassBody",
+				"start": 61,
+				"end": 63,
+				"range": [
+					61,
+					63
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Class declaration example.\n ",
+					"start": 0,
+					"end": 37,
+					"range": [
+						0,
+						37
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportDefaultDeclaration",
+			"start": 65,
+			"end": 97,
+			"range": [
+				65,
+				97
+			],
+			"declaration": {
+				"type": "Identifier",
+				"start": 80,
+				"end": 96,
+				"range": [
+					80,
+					96
+				],
+				"name": "ClassDeclaration"
+			}
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * Class declaration example.\n ",
+			"start": 0,
+			"end": 37,
+			"range": [
+				0,
+				37
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
new file mode 100644
index 00000000000000..1e1745c0f926e4
--- /dev/null
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -0,0 +1,81 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+/**
+ * Internal dependencies.
+ */
+const getIntermediateRepresentation = require( '../src/get-intermediate-representation' );
+
+test( 'default export (inline)', function( t ) {
+	const tokenClassAnonymous = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassAnonymous ) ), [ {
+		name: 'default',
+		description: 'Class declaration example.',
+		tags: [],
+	} ] );
+	const tokenClassNamed = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-class-named.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassNamed ) ), [ {
+		name: 'default',
+		description: 'Class declaration example.',
+		tags: [],
+	} ] );
+	const tokenFnAnonymous = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnAnonymous ) ), [ {
+		name: 'default',
+		description: 'Function declaration example.',
+		tags: [],
+	} ] );
+	const tokenFnNamed = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-function-named.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnNamed ) ), [ {
+		name: 'default',
+		description: 'Function declaration example.',
+		tags: [],
+	} ] );
+	const tokenVariable = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-variable.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
+		name: 'default',
+		description: 'Variable declaration example.',
+		tags: [],
+	} ] );
+	t.end();
+} );
+
+test( 'default export (lookup identifier)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-identifier.json' ),
+		'utf-8'
+	);
+	const ast = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-identifier-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
+		name: 'default',
+		description: 'Class declaration example.',
+		tags: [],
+	} ] );
+	t.end();
+} );

From 421cdf0118c05f7aaf3dd1f98f07e93ceb714fe9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 20:30:11 +0100
Subject: [PATCH 057/213] Rename file

---
 packages/docgen/src/get-intermediate-representation.js        | 2 +-
 packages/docgen/src/{get-jsdoc.js => get-jsdoc-from-token.js} | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename packages/docgen/src/{get-jsdoc.js => get-jsdoc-from-token.js} (100%)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 2b851bbc832c6b..7f82a7bb616ff7 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -7,7 +7,7 @@ const { get } = require( 'lodash' );
  * Internal dependencies.
  */
 const getExportEntries = require( './get-export-entries' );
-const getJSDocFromToken = require( './get-jsdoc' );
+const getJSDocFromToken = require( './get-jsdoc-from-token' );
 const getDependencyPath = require( './get-dependency-path' );
 
 const UNDOCUMENTED = 'Undocumented declaration.';
diff --git a/packages/docgen/src/get-jsdoc.js b/packages/docgen/src/get-jsdoc-from-token.js
similarity index 100%
rename from packages/docgen/src/get-jsdoc.js
rename to packages/docgen/src/get-jsdoc-from-token.js

From f9b3a86584205087900063455f67b00bc6358970 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 20:36:26 +0100
Subject: [PATCH 058/213] Flatten export entries returned by IR

---
 packages/docgen/src/engine.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 08976e0bb54a7b..195c5c2d538cde 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -2,6 +2,7 @@
 * External dependencies.
 */
 const espree = require( 'espree' );
+const { flatten } = require( 'lodash' );
 
 /**
 * Internal dependencies.
@@ -34,13 +35,13 @@ const engine = ( code, getCodeFromPath = () => {} ) => {
 	const result = {};
 	result.ast = getAST( code );
 	result.tokens = getExportTokens( result.ast );
-	result.ir = result.tokens.map(
+	result.ir = flatten( result.tokens.map(
 		( token ) => getIntermediateRepresentation(
 			token,
 			result.ast,
 			getIRFromDependency( getCodeFromPath )
 		)
-	);
+	) );
 
 	return result;
 };

From 927ec0b0fed833e2714a59f997ac30fa4f8ee061 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 20:42:22 +0100
Subject: [PATCH 059/213] Fix engine tests

---
 packages/docgen/tests/test-engine.js | 32 ++++++++++++++--------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 62f7d64ad71984..9f58c5dcc87d50 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -34,9 +34,9 @@ test( 'engine returns IR for many exports at once', ( t ) => {
 	t.deepEqual(
 		ir,
 		[
-			{ description: 'First declaration example.', tags: [], name: 'firstDeclaration' },
-			{ description: 'Second declaration example.', tags: [], name: 'secondDeclaration' },
-			{ description: 'Default declaration example.', tags: [], name: 'default export' },
+			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
+			{ name: 'default', description: 'Default declaration example.', tags: [] },
 		]
 	);
 	t.end();
@@ -53,7 +53,7 @@ test( 'engine returns IR for named export (function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -69,7 +69,7 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -87,7 +87,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -105,7 +105,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -131,8 +131,8 @@ test( 'engine returns IR for named export (multiple identifiers) using JSDoc fro
 	t.deepEqual(
 		ir,
 		[
-			{ description: 'First declaration example.', tags: [], name: 'firstDeclaration' },
-			{ description: 'Second declaration example.', tags: [], name: 'secondDeclaration' },
+			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
 		]
 	);
 	t.end();
@@ -152,7 +152,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 	);
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -168,7 +168,7 @@ test( 'engine returns IR for default export (named function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -184,7 +184,7 @@ test( 'engine returns IR for default export (anonymous function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -202,7 +202,7 @@ test( 'engine returns IR for default export (identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -220,7 +220,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from functi
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -238,7 +238,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from variab
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'My declaration example.', tags: [], name: 'default export' } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -253,7 +253,7 @@ test( 'engine returns IR for undocumented export', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { description: 'Undocumented declaration.', tags: [], name: 'default export' } ]
+		[ { name: 'default', description: 'Undocumented declaration.', tags: [] } ]
 	);
 	t.end();
 } );

From 0b1e42c0a559b990594363e88df8f9e509612bae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 20:52:30 +0100
Subject: [PATCH 060/213] Update tests for IR

---
 .../test-get-intermediate-representation.js   | 71 ++++++++++++++++++-
 1 file changed, 69 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 1e1745c0f926e4..71011dd459fcec 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -14,7 +14,7 @@ const test = require( 'tape' );
  */
 const getIntermediateRepresentation = require( '../src/get-intermediate-representation' );
 
-test( 'default export (inline)', function( t ) {
+test( 'default export (JSDoc in export statement)', function( t ) {
 	const tokenClassAnonymous = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
@@ -63,7 +63,7 @@ test( 'default export (inline)', function( t ) {
 	t.end();
 } );
 
-test( 'default export (lookup identifier)', function( t ) {
+test( 'default export (JSDoc in identifier declaration, same file)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
@@ -79,3 +79,70 @@ test( 'default export (lookup identifier)', function( t ) {
 	} ] );
 	t.end();
 } );
+
+test( 'named export (JSDoc in export statement)', function( t ) {
+	const tokenClass = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-class.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClass ) ), [ {
+		name: 'MyDeclaration',
+		description: 'My declaration example.',
+		tags: [],
+	} ] );
+	const tokenFn = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-function.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFn ) ), [ {
+		name: 'myDeclaration',
+		description: 'My declaration example.',
+		tags: [],
+	} ] );
+	const tokenVariable = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-variable.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
+		name: 'myDeclaration',
+		description: 'My declaration example.',
+		tags: [],
+	} ] );
+	const tokenVariables = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-variables.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariables ) ), [
+		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [] },
+	] );
+	t.end();
+} );
+
+test( 'named export (JSDoc in identifier declaration, same file)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
+		name: 'myDeclaration',
+		description: 'My declaration example.',
+		tags: [] },
+	] );
+	const tokens = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifiers.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ) ), [
+		{ name: 'functionDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'variableDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'ClassDeclaration', description: 'My declaration example.', tags: [] },
+	] );
+	t.end();
+} );
+
+test( 'named export (JSDoc in identifer declaration, module dependency)', function( t ) {
+	// TODO: named-default, namespace, other names
+	t.equal( false, true );
+	t.end();
+} );

From d41beb8fbe4008e5fa3eb821046924539fa969b8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 21:23:31 +0100
Subject: [PATCH 061/213] Fix tests

---
 .../tests/fixtures/named-identifier-ast.json  |  1 +
 .../tests/fixtures/named-identifiers-ast.json |  1 +
 .../test-get-intermediate-representation.js   | 19 +++++++++++++------
 3 files changed, 15 insertions(+), 6 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-ast.json
 create mode 100644 packages/docgen/tests/fixtures/named-identifiers-ast.json

diff --git a/packages/docgen/tests/fixtures/named-identifier-ast.json b/packages/docgen/tests/fixtures/named-identifier-ast.json
new file mode 100644
index 00000000000000..ec2fa1f02031bc
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-ast.json
@@ -0,0 +1 @@
+{"type":"Program","start":0,"end":90,"range":[35,89],"body":[{"type":"FunctionDeclaration","start":35,"end":62,"range":[35,62],"id":{"type":"Identifier","start":44,"end":57,"range":[44,57],"name":"myDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":60,"end":62,"range":[60,62],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * My declaration example.\n ","start":0,"end":34,"range":[0,34]}]},{"type":"ExportNamedDeclaration","start":64,"end":89,"range":[64,89],"declaration":null,"specifiers":[{"type":"ExportSpecifier","start":73,"end":86,"range":[73,86],"local":{"type":"Identifier","start":73,"end":86,"range":[73,86],"name":"myDeclaration"},"exported":{"type":"Identifier","start":73,"end":86,"range":[73,86],"name":"myDeclaration"}}],"source":null}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * My declaration example.\n ","start":0,"end":34,"range":[0,34]}]}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ast.json b/packages/docgen/tests/fixtures/named-identifiers-ast.json
new file mode 100644
index 00000000000000..fa4a4a5ca77768
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifiers-ast.json
@@ -0,0 +1 @@
+{"type":"Program","start":0,"end":288,"range":[41,287],"body":[{"type":"FunctionDeclaration","start":41,"end":74,"range":[41,74],"id":{"type":"Identifier","start":50,"end":69,"range":[50,69],"name":"functionDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":72,"end":74,"range":[72,74],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}],"trailingComments":[{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]}]},{"type":"ClassDeclaration","start":114,"end":139,"range":[114,139],"id":{"type":"Identifier","start":120,"end":136,"range":[120,136],"name":"ClassDeclaration"},"superClass":null,"body":{"type":"ClassBody","start":137,"end":139,"range":[137,139],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]}],"trailingComments":[{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]},{"type":"VariableDeclaration","start":182,"end":215,"range":[182,215],"declarations":[{"type":"VariableDeclarator","start":188,"end":214,"range":[188,214],"id":{"type":"Identifier","start":188,"end":207,"range":[188,207],"name":"variableDeclaration"},"init":{"type":"Literal","start":210,"end":214,"range":[210,214],"value":true,"raw":"true"}}],"kind":"const","leadingComments":[{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]},{"type":"ExportNamedDeclaration","start":217,"end":287,"range":[217,287],"declaration":null,"specifiers":[{"type":"ExportSpecifier","start":226,"end":245,"range":[226,245],"local":{"type":"Identifier","start":226,"end":245,"range":[226,245],"name":"functionDeclaration"},"exported":{"type":"Identifier","start":226,"end":245,"range":[226,245],"name":"functionDeclaration"}},{"type":"ExportSpecifier","start":247,"end":266,"range":[247,266],"local":{"type":"Identifier","start":247,"end":266,"range":[247,266],"name":"variableDeclaration"},"exported":{"type":"Identifier","start":247,"end":266,"range":[247,266],"name":"variableDeclaration"}},{"type":"ExportSpecifier","start":268,"end":284,"range":[268,284],"local":{"type":"Identifier","start":268,"end":284,"range":[268,284],"name":"ClassDeclaration"},"exported":{"type":"Identifier","start":268,"end":284,"range":[268,284],"name":"ClassDeclaration"}}],"source":null}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]},{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]},{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 71011dd459fcec..8e6a356d557b2a 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -124,7 +124,11 @@ test( 'named export (JSDoc in identifier declaration, same file)', function( t )
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
+	const ast = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [] },
@@ -133,16 +137,19 @@ test( 'named export (JSDoc in identifier declaration, same file)', function( t )
 		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ) ), [
-		{ name: 'functionDeclaration', description: 'My declaration example.', tags: [] },
-		{ name: 'variableDeclaration', description: 'My declaration example.', tags: [] },
-		{ name: 'ClassDeclaration', description: 'My declaration example.', tags: [] },
+	const asts = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifiers-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ), JSON.parse( asts ) ), [
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
 	] );
 	t.end();
 } );
 
 test( 'named export (JSDoc in identifer declaration, module dependency)', function( t ) {
-	// TODO: named-default, namespace, other names
 	t.equal( false, true );
 	t.end();
 } );

From 45eb32e95645b2bbca34e14f55200a56d7d7b8af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 21:40:15 +0100
Subject: [PATCH 062/213] getExportEntries: retrieve module from export
 statement

---
 packages/docgen/src/get-export-entries.js            |  2 +-
 .../docgen/tests/fixtures/named-default-module.js    |  4 ++++
 packages/docgen/tests/fixtures/named-default.js      |  2 +-
 packages/docgen/tests/fixtures/named-default.json    | 12 ++++++------
 packages/docgen/tests/test-get-export-entries.js     |  2 +-
 5 files changed, 13 insertions(+), 9 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-default-module.js

diff --git a/packages/docgen/src/get-export-entries.js b/packages/docgen/src/get-export-entries.js
index be3ac15802f92d..a91ca363cc0673 100644
--- a/packages/docgen/src/get-export-entries.js
+++ b/packages/docgen/src/get-export-entries.js
@@ -55,7 +55,7 @@ module.exports = function( token ) {
 		token.specifiers.forEach( ( specifier ) => name.push( {
 			localName: specifier.local.name,
 			exportName: specifier.local.name,
-			module: null,
+			module: get( token.source, [ 'value' ], null ),
 		} ) );
 		return name;
 	}
diff --git a/packages/docgen/tests/fixtures/named-default-module.js b/packages/docgen/tests/fixtures/named-default-module.js
new file mode 100644
index 00000000000000..92127f1f850593
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default-module.js
@@ -0,0 +1,4 @@
+/**
+ * Module declaration.
+ */
+export default function( ) {}
diff --git a/packages/docgen/tests/fixtures/named-default.js b/packages/docgen/tests/fixtures/named-default.js
index d533cc9693579b..3cca6a9d490692 100644
--- a/packages/docgen/tests/fixtures/named-default.js
+++ b/packages/docgen/tests/fixtures/named-default.js
@@ -1 +1 @@
-export { default } from './module';
+export { default } from './named-default-module';
diff --git a/packages/docgen/tests/fixtures/named-default.json b/packages/docgen/tests/fixtures/named-default.json
index 31d5442cd5265b..ad523e8550146f 100644
--- a/packages/docgen/tests/fixtures/named-default.json
+++ b/packages/docgen/tests/fixtures/named-default.json
@@ -1,10 +1,10 @@
 {
 	"type": "ExportNamedDeclaration",
 	"start": 0,
-	"end": 35,
+	"end": 49,
 	"range": [
 		0,
-		35
+		49
 	],
 	"declaration": null,
 	"specifiers": [
@@ -41,12 +41,12 @@
 	"source": {
 		"type": "Literal",
 		"start": 24,
-		"end": 34,
+		"end": 48,
 		"range": [
 			24,
-			34
+			48
 		],
-		"value": "./module",
-		"raw": "'./module'"
+		"value": "./named-default-module",
+		"raw": "'./named-default-module'"
 	}
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index d53a3bb43d294a..c3f614341a4f89 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -121,7 +121,7 @@ test( 'named export default', function( t ) {
 	t.deepEqual( name, [ {
 		localName: 'default',
 		exportName: 'default',
-		module: null,
+		module: './named-default-module',
 	} ] );
 	t.end();
 } );

From 6f8849e76c5d4e21e51afdb1c111c3df2085819e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 21:53:42 +0100
Subject: [PATCH 063/213] getIR: fix dependency lookup

---
 .../docgen/src/get-intermediate-representation.js    |  4 ++--
 .../tests/fixtures/named-default-module-ir.json      |  1 +
 .../tests/test-get-intermediate-representation.js    | 12 +++++++++++-
 3 files changed, 14 insertions(+), 3 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-default-module-ir.json

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 7f82a7bb616ff7..9290f8261a6ff9 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -26,8 +26,8 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 			doc = getJSDoc( candidates[ 0 ] );
 		}
 	} else if ( doc === undefined && entry.module !== null ) {
-		const irFromDependency = parseDependency( getDependencyPath( token ) );
-		doc = irFromDependency.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+		const ir = parseDependency( getDependencyPath( token ) );
+		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.exportName );
 	}
 	return doc;
 };
diff --git a/packages/docgen/tests/fixtures/named-default-module-ir.json b/packages/docgen/tests/fixtures/named-default-module-ir.json
new file mode 100644
index 00000000000000..9807991c06ccc9
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default-module-ir.json
@@ -0,0 +1 @@
+[{"name":"default","description":"Module declaration.","tags":[]}]
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 8e6a356d557b2a..9a6dd72a007ff1 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -150,6 +150,16 @@ test( 'named export (JSDoc in identifier declaration, same file)', function( t )
 } );
 
 test( 'named export (JSDoc in identifer declaration, module dependency)', function( t ) {
-	t.equal( false, true );
+	const tokens = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default.json' ),
+		'utf-8'
+	);
+	const getCodeFromPath = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokens ), { body: [] }, getCodeFromPath ),
+		[ { name: 'default', description: 'Module declaration.', tags: [] } ] );
 	t.end();
 } );

From 2a72444be55acb58ee43a5271886b377a5c555cb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 21:55:39 +0100
Subject: [PATCH 064/213] Protect against no code provided

---
 packages/docgen/src/get-intermediate-representation.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 9290f8261a6ff9..7333e940496c8d 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -14,7 +14,7 @@ const UNDOCUMENTED = 'Undocumented declaration.';
 
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc = getJSDocFromToken( token );
-	if ( doc === undefined && entry.module === null ) {
+	if ( doc === undefined && entry && entry.module === null ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return ( node.type === 'ClassDeclaration' && node.id.name === entry.localName ) ||
 				( node.type === 'FunctionDeclaration' && node.id.name === entry.localName ) ||
@@ -25,7 +25,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		if ( candidates.length === 1 ) {
 			doc = getJSDoc( candidates[ 0 ] );
 		}
-	} else if ( doc === undefined && entry.module !== null ) {
+	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
 		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.exportName );
 	}

From 27756e89f7e0a439d9299f21dcb83c7639860a92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 22:05:32 +0100
Subject: [PATCH 065/213] Better test names

---
 packages/docgen/package.json                  |  1 +
 packages/docgen/tests/test-engine.js          | 28 +++++++++----------
 .../docgen/tests/test-formatter-markdown.js   |  2 +-
 .../docgen/tests/test-get-export-entries.js   | 28 +++++++++----------
 .../test-get-intermediate-representation.js   | 10 +++----
 5 files changed, 35 insertions(+), 34 deletions(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 830686a1c080ab..20a74e2a44cd9d 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -27,6 +27,7 @@
 	"scripts": {
 		"test": "tape tests/test-*.js | faucet",
 		"test:engine": "tape tests/test-engine.js | faucet",
+		"test:formatter": "tape tests/test-formatter-markdown.js | faucet",
 		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
 		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet"
 	}
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 9f58c5dcc87d50..6504f0fbebfeed 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -8,7 +8,7 @@ const test = require( 'tape' );
  */
 const engine = require( '../src/engine' );
 
-test( 'engine returns IR for many exports at once', ( t ) => {
+test( 'Engine - many exports at once', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * First declaration example.
@@ -42,7 +42,7 @@ test( 'engine returns IR for many exports at once', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (function)', ( t ) => {
+test( 'Engine - named export (function)', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * My declaration example.
@@ -58,7 +58,7 @@ test( 'engine returns IR for named export (function)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (variable)', ( t ) => {
+test( 'Engine - named export (variable)', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * My declaration example.
@@ -74,7 +74,7 @@ test( 'engine returns IR for named export (variable)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (single identifier)', ( t ) => {
+test( 'Engine - named export (single identifier)', ( t ) => {
 	const { ir } = engine( `
 	const myDeclaration = function() {
 		// do nothing
@@ -92,7 +92,7 @@ test( 'engine returns IR for named export (single identifier)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for named export (single identifier) using JSDoc from declaration', ( t ) => {
+test( 'Engine - named export (single identifier) using JSDoc from declaration', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * My declaration example.
@@ -110,7 +110,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 	t.end();
 } );
 
-test( 'engine returns IR for named export (multiple identifiers) using JSDoc from declaration', ( t ) => {
+test( 'Engine - named export (multiple identifiers) using JSDoc from declaration', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * First declaration example.
@@ -138,7 +138,7 @@ test( 'engine returns IR for named export (multiple identifiers) using JSDoc fro
 	t.end();
 } );
 
-test( 'engine returns IR for named export (single identifier) using JSDoc from dependency', ( t ) => {
+test( 'Engine - named export (single identifier) using JSDoc from dependency', ( t ) => {
 	const getDependency = () => `/**
  		 * My declaration example.
  		 */
@@ -157,7 +157,7 @@ test( 'engine returns IR for named export (single identifier) using JSDoc from d
 	t.end();
 } );
 
-test( 'engine returns IR for default export (named function)', ( t ) => {
+test( 'Engine - default export (named function)', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * My declaration example.
@@ -173,7 +173,7 @@ test( 'engine returns IR for default export (named function)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for default export (anonymous function)', ( t ) => {
+test( 'Engine - default export (anonymous function)', ( t ) => {
 	const { ir } = engine( `
 		/**
  		 * My declaration example.
@@ -189,7 +189,7 @@ test( 'engine returns IR for default export (anonymous function)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for default export (identifier)', ( t ) => {
+test( 'Engine - default export (identifier)', ( t ) => {
 	const { ir } = engine( `
 		function myDeclaration() {
 			// do nothing
@@ -207,7 +207,7 @@ test( 'engine returns IR for default export (identifier)', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for default export (identifier) using JSDoc from function', ( t ) => {
+test( 'Engine - default export (identifier) using JSDoc from function', ( t ) => {
 	const { ir } = engine( `
 		/**
 		 * My declaration example.
@@ -225,7 +225,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from functi
 	t.end();
 } );
 
-test( 'engine returns IR for default export (identifier) using JSDoc from variable', ( t ) => {
+test( 'Engine - default export (identifier) using JSDoc from variable', ( t ) => {
 	const { ir } = engine( `
 		/**
 		 * My declaration example.
@@ -243,7 +243,7 @@ test( 'engine returns IR for default export (identifier) using JSDoc from variab
 	t.end();
 } );
 
-test( 'engine returns IR for undocumented export', ( t ) => {
+test( 'Engine - undocumented export', ( t ) => {
 	const { ir } = engine( `
 		const myDeclaration = function() {
 			// do nothing
@@ -258,7 +258,7 @@ test( 'engine returns IR for undocumented export', ( t ) => {
 	t.end();
 } );
 
-test( 'engine returns IR for undefined code', ( t ) => {
+test( 'Engine - undefined code', ( t ) => {
 	const { ir } = engine( undefined );
 	t.deepEqual( ir, [ ] );
 	t.end();
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index 4e05c00f01e9a4..e8933a7b6f9491 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -8,7 +8,7 @@ const test = require( 'tape' );
  */
 const formatter = require( '../src/formatter' );
 
-test( 'formatter returns markdown', ( t ) => {
+test( 'Formatter - returns markdown', ( t ) => {
 	const docs = formatter( [ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ] );
 	t.equal(
 		docs,
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index c3f614341a4f89..6d14a512065147 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -14,7 +14,7 @@ const test = require( 'tape' );
  */
 const getExportEntries = require( '../src/get-export-entries' );
 
-test( 'default export class (anonymous)', function( t ) {
+test( 'Export entries: default class (anonymous)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
@@ -28,7 +28,7 @@ test( 'default export class (anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'default export class (named)', function( t ) {
+test( 'Export entries: default class (named)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-named.json' ),
 		'utf-8'
@@ -42,7 +42,7 @@ test( 'default export class (named)', function( t ) {
 	t.end();
 } );
 
-test( 'default export function (anonymous)', function( t ) {
+test( 'Export entries: default function (anonymous)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
 		'utf-8'
@@ -56,7 +56,7 @@ test( 'default export function (anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'default export function (named)', function( t ) {
+test( 'Export entries: default function (named)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-named.json' ),
 		'utf-8'
@@ -70,7 +70,7 @@ test( 'default export function (named)', function( t ) {
 	t.end();
 } );
 
-test( 'default export identifier', function( t ) {
+test( 'Export entries: default identifier', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
@@ -84,7 +84,7 @@ test( 'default export identifier', function( t ) {
 	t.end();
 } );
 
-test( 'default export variable', function( t ) {
+test( 'Export entries: default variable', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-variable.json' ),
 		'utf-8'
@@ -98,7 +98,7 @@ test( 'default export variable', function( t ) {
 	t.end();
 } );
 
-test( 'named export class', function( t ) {
+test( 'Export entries - named class', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
@@ -112,7 +112,7 @@ test( 'named export class', function( t ) {
 	t.end();
 } );
 
-test( 'named export default', function( t ) {
+test( 'Export entries - named default', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
@@ -126,7 +126,7 @@ test( 'named export default', function( t ) {
 	t.end();
 } );
 
-test( 'named export function', function( t ) {
+test( 'Export entries - named function', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-function.json' ),
 		'utf-8'
@@ -140,7 +140,7 @@ test( 'named export function', function( t ) {
 	t.end();
 } );
 
-test( 'named export identifier', function( t ) {
+test( 'Export entries - named identifier', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
@@ -154,7 +154,7 @@ test( 'named export identifier', function( t ) {
 	t.end();
 } );
 
-test( 'named export identifiers', function( t ) {
+test( 'Export entries - named identifiers', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'
@@ -168,7 +168,7 @@ test( 'named export identifiers', function( t ) {
 	t.end();
 } );
 
-test( 'named export variable', function( t ) {
+test( 'Export entries - named variable', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-variable.json' ),
 		'utf-8'
@@ -182,7 +182,7 @@ test( 'named export variable', function( t ) {
 	t.end();
 } );
 
-test( 'named export variables', function( t ) {
+test( 'Export entries - named variables', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-variables.json' ),
 		'utf-8'
@@ -195,7 +195,7 @@ test( 'named export variables', function( t ) {
 	t.end();
 } );
 
-test( 'namespace export (*)', function( t ) {
+test( 'Export entries - namespace (*)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/namespace.json' ),
 		'utf-8'
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 9a6dd72a007ff1..9f2978e0968236 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -14,7 +14,7 @@ const test = require( 'tape' );
  */
 const getIntermediateRepresentation = require( '../src/get-intermediate-representation' );
 
-test( 'default export (JSDoc in export statement)', function( t ) {
+test( 'IR - default (JSDoc in export statement)', function( t ) {
 	const tokenClassAnonymous = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
@@ -63,7 +63,7 @@ test( 'default export (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'default export (JSDoc in identifier declaration, same file)', function( t ) {
+test( 'IR - default (JSDoc in identifier declaration, same file)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
@@ -80,7 +80,7 @@ test( 'default export (JSDoc in identifier declaration, same file)', function( t
 	t.end();
 } );
 
-test( 'named export (JSDoc in export statement)', function( t ) {
+test( 'IR - named (JSDoc in export statement)', function( t ) {
 	const tokenClass = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
@@ -119,7 +119,7 @@ test( 'named export (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'named export (JSDoc in identifier declaration, same file)', function( t ) {
+test( 'IR - named (JSDoc in identifier declaration, same file)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
@@ -149,7 +149,7 @@ test( 'named export (JSDoc in identifier declaration, same file)', function( t )
 	t.end();
 } );
 
-test( 'named export (JSDoc in identifer declaration, module dependency)', function( t ) {
+test( 'IR - named (JSDoc in identifer declaration, module dependency)', function( t ) {
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'

From e79bb85e5617bff3b2a6ef2a8d043a7b0041bf10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 22:14:45 +0100
Subject: [PATCH 066/213] Implement exported names

---
 packages/docgen/src/get-export-entries.js     |  2 +-
 .../tests/fixtures/named-default-exported.js  |  1 +
 .../fixtures/named-default-exported.json      | 52 +++++++++++++++++++
 .../docgen/tests/test-get-export-entries.js   | 14 +++++
 4 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 packages/docgen/tests/fixtures/named-default-exported.js
 create mode 100644 packages/docgen/tests/fixtures/named-default-exported.json

diff --git a/packages/docgen/src/get-export-entries.js b/packages/docgen/src/get-export-entries.js
index a91ca363cc0673..bdb56f34bcb3ad 100644
--- a/packages/docgen/src/get-export-entries.js
+++ b/packages/docgen/src/get-export-entries.js
@@ -54,7 +54,7 @@ module.exports = function( token ) {
 	if ( token.declaration === null ) {
 		token.specifiers.forEach( ( specifier ) => name.push( {
 			localName: specifier.local.name,
-			exportName: specifier.local.name,
+			exportName: specifier.exported.name,
 			module: get( token.source, [ 'value' ], null ),
 		} ) );
 		return name;
diff --git a/packages/docgen/tests/fixtures/named-default-exported.js b/packages/docgen/tests/fixtures/named-default-exported.js
new file mode 100644
index 00000000000000..7aebc3a91fa1c3
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default-exported.js
@@ -0,0 +1 @@
+export { default as moduleName } from './named-default-module';
diff --git a/packages/docgen/tests/fixtures/named-default-exported.json b/packages/docgen/tests/fixtures/named-default-exported.json
new file mode 100644
index 00000000000000..f684e0f5872e59
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-default-exported.json
@@ -0,0 +1,52 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 0,
+	"end": 63,
+	"range": [
+		0,
+		63
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 9,
+			"end": 30,
+			"range": [
+				9,
+				30
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 16,
+				"range": [
+					9,
+					16
+				],
+				"name": "default"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 20,
+				"end": 30,
+				"range": [
+					20,
+					30
+				],
+				"name": "moduleName"
+			}
+		}
+	],
+	"source": {
+		"type": "Literal",
+		"start": 38,
+		"end": 62,
+		"range": [
+			38,
+			62
+		],
+		"value": "./named-default-module",
+		"raw": "'./named-default-module'"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 6d14a512065147..25648c45b475d1 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -126,6 +126,20 @@ test( 'Export entries - named default', function( t ) {
 	t.end();
 } );
 
+test( 'Export entries - named default (exported)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default-exported.json' ),
+		'utf-8'
+	);
+	const name = getExportEntries( JSON.parse( token ) );
+	t.deepEqual( name, [ {
+		localName: 'default',
+		exportName: 'moduleName',
+		module: './named-default-module',
+	} ] );
+	t.end();
+} );
+
 test( 'Export entries - named function', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-function.json' ),

From 7f73a4ff8b5181dae3bfdf81167364310b3d4f1b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 22:23:41 +0100
Subject: [PATCH 067/213] Fix exported names

---
 .../src/get-intermediate-representation.js      |  2 +-
 .../test-get-intermediate-representation.js     | 17 +++++++++++++----
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 7333e940496c8d..c2c7cb3e0c3580 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -27,7 +27,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
-		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.exportName );
+		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
 	}
 	return doc;
 };
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 9f2978e0968236..ea2ed356aa4821 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -150,16 +150,25 @@ test( 'IR - named (JSDoc in identifier declaration, same file)', function( t ) {
 } );
 
 test( 'IR - named (JSDoc in identifer declaration, module dependency)', function( t ) {
-	const tokens = fs.readFileSync(
+	const tokenDefault = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
 	);
-	const getCodeFromPath = () => JSON.parse( fs.readFileSync(
+	const getModule = () => JSON.parse( fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-module-ir.json' ),
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokens ), { body: [] }, getCodeFromPath ),
-		[ { name: 'default', description: 'Module declaration.', tags: [] } ] );
+		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
+		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
+	);
+	const tokenDefaultExported = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default-exported.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
+		[ { name: 'moduleName', description: 'Module declaration.', tags: [] } ]
+	);
 	t.end();
 } );

From 71d170e465421ffdc32e9ef9d17df05679b52cf7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 22:28:09 +0100
Subject: [PATCH 068/213] Update coverage

---
 packages/docgen/coverage.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index d65358502c629f..8e61318842ede8 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -31,7 +31,7 @@
 - [x] escape-html
 - [ ] eslint-plugin - NODE EXPORT
 - [x] format-library - exports nothing
-- [ ] hooks - multiple named exports
+- [ ] hooks - hooks is defined in other file by importing first
 - [x] html-entities
 - [x] i18n
 - [ ] is-shallow-equal - NODE EXPORT
@@ -51,7 +51,7 @@
 - [x] rich-text
 - [ ] scripts - what shall be documented?
 - [x] shortcode
-- [ ] token-list - `export class`
+- [x] token-list - `export class`
 - [x] url
-- [ ] viewport - `default as`
+- [x] viewport - `default as`
 - [x] wordcount

From f363338a86c63e5c58eb38b18a4aee1b948b4351 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 21 Jan 2019 22:48:09 +0100
Subject: [PATCH 069/213] Add test for namespace export

---
 .../tests/fixtures/namespace-module-ir.json   | 22 +++++++++++++++++++
 .../docgen/tests/fixtures/namespace-module.js | 19 ++++++++++++++++
 packages/docgen/tests/fixtures/namespace.js   |  2 +-
 packages/docgen/tests/fixtures/namespace.json | 12 +++++-----
 .../test-get-intermediate-representation.js   | 20 +++++++++++++++++
 5 files changed, 68 insertions(+), 7 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/namespace-module-ir.json
 create mode 100644 packages/docgen/tests/fixtures/namespace-module.js

diff --git a/packages/docgen/tests/fixtures/namespace-module-ir.json b/packages/docgen/tests/fixtures/namespace-module-ir.json
new file mode 100644
index 00000000000000..4ab6f287339389
--- /dev/null
+++ b/packages/docgen/tests/fixtures/namespace-module-ir.json
@@ -0,0 +1,22 @@
+[
+	{
+		"name": "myVariable",
+		"description": "Named variable.",
+		"tags": []
+	},
+	{
+		"name": "myFunction",
+		"description": "Named function.",
+		"tags": []
+	},
+	{
+		"name": "myClass",
+		"description": "Named class.",
+		"tags": []
+	},
+	{
+		"name": "default",
+		"description": "Default variable declaration.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/namespace-module.js b/packages/docgen/tests/fixtures/namespace-module.js
new file mode 100644
index 00000000000000..1ff51c686236af
--- /dev/null
+++ b/packages/docgen/tests/fixtures/namespace-module.js
@@ -0,0 +1,19 @@
+/**
+ * Named variable.
+ */
+export const myVariable = true;
+
+/**
+ * Named function.
+ */
+export const myFunction = () => {};
+
+/**
+ * Named class.
+ */
+export class MyClass {}
+
+/**
+ * Default variable declaration.
+ */
+export default 42;
diff --git a/packages/docgen/tests/fixtures/namespace.js b/packages/docgen/tests/fixtures/namespace.js
index 20a96c9a596af9..d2705ea5f8e632 100644
--- a/packages/docgen/tests/fixtures/namespace.js
+++ b/packages/docgen/tests/fixtures/namespace.js
@@ -1 +1 @@
-export * from './module';
+export * from './namespace-module';
diff --git a/packages/docgen/tests/fixtures/namespace.json b/packages/docgen/tests/fixtures/namespace.json
index 18c84ba7e42e57..1a2ba4a6e73c69 100644
--- a/packages/docgen/tests/fixtures/namespace.json
+++ b/packages/docgen/tests/fixtures/namespace.json
@@ -1,20 +1,20 @@
 {
 	"type": "ExportAllDeclaration",
 	"start": 0,
-	"end": 25,
+	"end": 35,
 	"range": [
 		0,
-		25
+		35
 	],
 	"source": {
 		"type": "Literal",
 		"start": 14,
-		"end": 24,
+		"end": 34,
 		"range": [
 			14,
-			24
+			34
 		],
-		"value": "./module",
-		"raw": "'./module'"
+		"value": "./namespace-module",
+		"raw": "'./namespace-module'"
 	}
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index ea2ed356aa4821..e2767b884d0963 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -172,3 +172,23 @@ test( 'IR - named (JSDoc in identifer declaration, module dependency)', function
 	);
 	t.end();
 } );
+
+test( 'IR - namespace (JSDoc in identifer declaration, module dependency)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/namespace.json' ),
+		'utf-8'
+	);
+	const getModule = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/namespace-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
+		[
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'MyClass', description: 'Named variable.', tags: [] },
+		]
+	);
+	t.end();
+} );

From 9fbac97fba4c5d4b3e37952716b12b33d776f653 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 10:29:45 +0100
Subject: [PATCH 070/213] Update coverage.md

---
 packages/docgen/coverage.md | 65 ++++++++++++++++++++-----------------
 1 file changed, 35 insertions(+), 30 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 8e61318842ede8..9736541b028318 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -1,55 +1,60 @@
 # Coverage
 
+CJS modules:
+
+- [ ] babel-plugin-makepot - NODE EXPORT
+- [ ] babel-preset-default - NODE EXPORT, not `src/index.js`
+- [ ] browserslist-config - NODE, not `src/index.js`
+- [ ] custom-templated-path-webpack-plugin - NODE EXPORT
+- [ ] docgen - NODE EXPORT, not `src/index.js`
+- [ ] eslint-plugin - NODE EXPORT
+- [ ] is-shallow-equal - NODE EXPORT
+- [ ] jest-preset-default - NODE EXPORT, not `src/index.js`
+- [ ] postcss-themes - NODE export
+- [ ] library-export-default-webpack-plugin - NODE EXPORT
+
+ES6 modules:
+
+- [ ] block-serialization-spec-parser - not `src/index.js`, multiple named exports
+- [ ] blocks - `export *`
+- [ ] components - `export *`, `default as`
+- [ ] compose - directory dependency
+- [ ] data - directory dependency
+- [ ] dom - `export *`
+- [ ] e2e-test-utils - what shall be documented?
+- [ ] e2e-tests - what shall be documented?
+- [ ] edit-post - directory dependency
+- [ ] editor - `export *`, directory dependency
+- [ ] element - `export *`, `default as` is a identifier
+- [ ] hooks - hooks is defined in other file by importing first
+- [ ] notices - REVIEW. Does weird things.
+- [ ] npm-package-json-lint-config - CONFIG file
+- [ ] nux - `default as`, directory dependency
+- [ ] plugins - `export *`, directory dependency
+- [ ] scripts - what shall be documented? not `src/index`
+- [-] keycodes - how to document CONSTANTS?
+- [-] redux-routine - check description with many paragraphs
 - [x] a11y
 - [x] annotations - export nothing
 - [x] api-fetch
 - [x] autop
 - [x] babel-plugin-import-jsx-pragma
-- [ ] babel-plugin-makepot - NODE EXPORT
-- [ ] babel-preset-default - NODE EXPORT, not `src/index.js`
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
-- [ ] block-serialization-spec-parser - not `src/index.js`, multiple named exports
-- [ ] blocks - `export *`
-- [ ] browserslist-config - NODE, not `src/index.js`
-- [ ] components - `export *`, `default as`
-- [ ] compose - directory dependency
 - [x] core-data - export nothing
-- [ ] custom-templated-path-webpack-plugin - NODE EXPORT
-- [ ] data - directory dependency
 - [x] date
-- [ ] deprecated - do not name default export
-- [ ] docgen - not `src/index.js`
-- [ ] dom - `export *`
+- [x] deprecated - do not name default export
 - [x] dom-ready
-- [ ] e2e-tests - what shall be documented?
-- [ ] e2e-test-utils - what shall be documented?
-- [ ] editor - `export *`
-- [ ] edit-post - directory dependency
-- [ ] element - `export *`, `default as`
 - [x] escape-html
-- [ ] eslint-plugin - NODE EXPORT
 - [x] format-library - exports nothing
-- [ ] hooks - hooks is defined in other file by importing first
 - [x] html-entities
 - [x] i18n
-- [ ] is-shallow-equal - NODE EXPORT
 - [x] jest-console - export nothing
-- [ ] jest-preset-default - NODE EXPORT, not `src/index.js`
 - [x] jest-puppeteer-axe - export nothing
-- [-] keycodes - how to document CONSTANTS?
-- [ ] library-export-default-webpack-plugin - NODE EXPORT
 - [x] list-reusable-blocks - export nothing
-- [ ] notices - REVIEW. Does weird things.
-- [ ] npm-package-json-lint-config - CONFIG file
-- [ ] nux - `default as`, directory dependency 
-- [ ] plugins - `export *`
-- [ ] postcss-themes - NODE export
 - [x] priority-queue
-- [-] redux-routine - check description with many paragraphs
 - [x] rich-text
-- [ ] scripts - what shall be documented?
 - [x] shortcode
 - [x] token-list - `export class`
 - [x] url

From b7b2b30df8a8cb13af0bdb31892982c201dc5f5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 11:10:18 +0100
Subject: [PATCH 071/213] Fix export entries test

---
 packages/docgen/tests/test-get-export-entries.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 25648c45b475d1..51c6e223ac0e93 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -218,7 +218,7 @@ test( 'Export entries - namespace (*)', function( t ) {
 	t.deepEqual( name, [ {
 		localName: '*',
 		exportName: null,
-		module: './module',
+		module: './namespace-module',
 	} ] );
 	t.end();
 } );

From f116fbff148ecfb8143c2d926dba7f0c5e185f6b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 11:25:07 +0100
Subject: [PATCH 072/213] IR: add support for namespace exports

---
 .../src/get-intermediate-representation.js    | 31 ++++++++++++++-----
 .../tests/fixtures/namespace-module-ir.json   |  2 +-
 .../test-get-intermediate-representation.js   |  2 +-
 3 files changed, 25 insertions(+), 10 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index c2c7cb3e0c3580..9eb795d0b5c9aa 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -23,11 +23,15 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 				);
 		} );
 		if ( candidates.length === 1 ) {
-			doc = getJSDoc( candidates[ 0 ] );
+			doc = getJSDoc( candidates[ 0 ] ); // TODO: use getJSDocFromToken
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
-		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+		if ( entry.localName === '*' ) {
+			doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== 'default' );
+		} else {
+			doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+		}
 	}
 	return doc;
 };
@@ -50,12 +54,23 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 	const exportEntries = getExportEntries( token );
 	const ir = [];
 	exportEntries.forEach( ( entry ) => {
-		const doc = getJSDoc( token, entry, ast, parseDependency );
-		ir.push( {
-			name: entry.exportName,
-			description: get( doc, [ 'description' ], UNDOCUMENTED ),
-			tags: [],
-		} );
+		if ( entry.localName === '*' ) {
+			const doc = getJSDoc( token, entry, ast, parseDependency );
+			doc.forEach( ( namedExport ) => {
+				ir.push( {
+					name: namedExport.name,
+					description: namedExport.description,
+					tags: namedExport.tags,
+				} );
+			} );
+		} else {
+			const doc = getJSDoc( token, entry, ast, parseDependency );
+			ir.push( {
+				name: entry.exportName,
+				description: get( doc, [ 'description' ], UNDOCUMENTED ),
+				tags: [],
+			} );
+		}
 	} );
 	return ir;
 };
diff --git a/packages/docgen/tests/fixtures/namespace-module-ir.json b/packages/docgen/tests/fixtures/namespace-module-ir.json
index 4ab6f287339389..803944d60e1d7d 100644
--- a/packages/docgen/tests/fixtures/namespace-module-ir.json
+++ b/packages/docgen/tests/fixtures/namespace-module-ir.json
@@ -10,7 +10,7 @@
 		"tags": []
 	},
 	{
-		"name": "myClass",
+		"name": "MyClass",
 		"description": "Named class.",
 		"tags": []
 	},
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index e2767b884d0963..131ecf30a55679 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -187,7 +187,7 @@ test( 'IR - namespace (JSDoc in identifer declaration, module dependency)', func
 		[
 			{ name: 'myVariable', description: 'Named variable.', tags: [] },
 			{ name: 'myFunction', description: 'Named function.', tags: [] },
-			{ name: 'MyClass', description: 'Named variable.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [] },
 		]
 	);
 	t.end();

From 93b90443d44146cebeb20a1cf441385e829c2e4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 11:25:34 +0100
Subject: [PATCH 073/213] Fix method call

---
 packages/docgen/src/get-intermediate-representation.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 9eb795d0b5c9aa..c52d93dcfe8cd0 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -23,7 +23,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 				);
 		} );
 		if ( candidates.length === 1 ) {
-			doc = getJSDoc( candidates[ 0 ] ); // TODO: use getJSDocFromToken
+			doc = getJSDocFromToken( candidates[ 0 ] );
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );

From 73f4b8312ac1c2126c29b653e55096227c1827bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 11:26:51 +0100
Subject: [PATCH 074/213] Extract constants for better encapsulation

---
 packages/docgen/src/get-intermediate-representation.js | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index c52d93dcfe8cd0..d68f9f6e7b382f 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -11,6 +11,8 @@ const getJSDocFromToken = require( './get-jsdoc-from-token' );
 const getDependencyPath = require( './get-dependency-path' );
 
 const UNDOCUMENTED = 'Undocumented declaration.';
+const NAMESPACE_EXPORT = '*';
+const DEFAULT_EXPORT = 'default';
 
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc = getJSDocFromToken( token );
@@ -27,8 +29,8 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
-		if ( entry.localName === '*' ) {
-			doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== 'default' );
+		if ( entry.localName === NAMESPACE_EXPORT ) {
+			doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
 		} else {
 			doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
 		}
@@ -54,7 +56,7 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 	const exportEntries = getExportEntries( token );
 	const ir = [];
 	exportEntries.forEach( ( entry ) => {
-		if ( entry.localName === '*' ) {
+		if ( entry.localName === NAMESPACE_EXPORT ) {
 			const doc = getJSDoc( token, entry, ast, parseDependency );
 			doc.forEach( ( namedExport ) => {
 				ir.push( {

From 2d5ab5c31858a191bbb873e35699aa0c9eb12d07 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 11:43:08 +0100
Subject: [PATCH 075/213] Update coverage

---
 packages/docgen/coverage.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 9736541b028318..2b1ac34ddfdeec 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -15,22 +15,20 @@ CJS modules:
 
 ES6 modules:
 
-- [ ] block-serialization-spec-parser - not `src/index.js`, multiple named exports
-- [ ] blocks - `export *`
-- [ ] components - `export *`, `default as`
+- [ ] block-serialization-spec-parser - not `src/index.js`
+- [ ] blocks - directory dependency
+- [ ] components - directory dependency
 - [ ] compose - directory dependency
 - [ ] data - directory dependency
-- [ ] dom - `export *`
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
 - [ ] edit-post - directory dependency
-- [ ] editor - `export *`, directory dependency
-- [ ] element - `export *`, `default as` is a identifier
-- [ ] hooks - hooks is defined in other file by importing first
-- [ ] notices - REVIEW. Does weird things.
+- [ ] editor - directory dependency
+- [ ] element - `renderToString`
+- [ ] hooks - `import something; ... export something;`
 - [ ] npm-package-json-lint-config - CONFIG file
-- [ ] nux - `default as`, directory dependency
-- [ ] plugins - `export *`, directory dependency
+- [ ] nux - directory dependency
+- [ ] plugins - directory dependency
 - [ ] scripts - what shall be documented? not `src/index`
 - [-] keycodes - how to document CONSTANTS?
 - [-] redux-routine - check description with many paragraphs
@@ -44,7 +42,8 @@ ES6 modules:
 - [x] block-serialization-default-parser
 - [x] core-data - export nothing
 - [x] date
-- [x] deprecated - do not name default export
+- [x] deprecated
+- [x] dom
 - [x] dom-ready
 - [x] escape-html
 - [x] format-library - exports nothing
@@ -53,10 +52,11 @@ ES6 modules:
 - [x] jest-console - export nothing
 - [x] jest-puppeteer-axe - export nothing
 - [x] list-reusable-blocks - export nothing
+- [x] notices - does not export anything
 - [x] priority-queue
 - [x] rich-text
 - [x] shortcode
-- [x] token-list - `export class`
+- [x] token-list
 - [x] url
-- [x] viewport - `default as`
+- [x] viewport
 - [x] wordcount

From 721cfdcba6a818298d4aac54ad716b1aacbbfa86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 12:05:25 +0100
Subject: [PATCH 076/213] Add test for named and default exports

---
 .../named-function-and-default-ast.json       |  1 +
 .../fixtures/named-function-and-default.js    |  6 ++
 .../fixtures/named-function-and-default.json  | 77 +++++++++++++++++++
 .../test-get-intermediate-representation.js   | 20 +++++
 4 files changed, 104 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-function-and-default-ast.json
 create mode 100644 packages/docgen/tests/fixtures/named-function-and-default.js
 create mode 100644 packages/docgen/tests/fixtures/named-function-and-default.json

diff --git a/packages/docgen/tests/fixtures/named-function-and-default-ast.json b/packages/docgen/tests/fixtures/named-function-and-default-ast.json
new file mode 100644
index 00000000000000..7638b5572c8572
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function-and-default-ast.json
@@ -0,0 +1 @@
+{"type":"Program","start":0,"end":119,"range":[41,118],"body":[{"type":"ExportNamedDeclaration","start":41,"end":81,"range":[41,81],"declaration":{"type":"FunctionDeclaration","start":48,"end":81,"range":[48,81],"id":{"type":"Identifier","start":57,"end":76,"range":[57,76],"name":"functionDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":79,"end":81,"range":[79,81],"body":[]}},"specifiers":[],"source":null,"leadingComments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}]},{"type":"ExportDefaultDeclaration","start":83,"end":118,"range":[83,118],"declaration":{"type":"Identifier","start":98,"end":117,"range":[98,117],"name":"functionDeclaration"}}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}]}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-function-and-default.js b/packages/docgen/tests/fixtures/named-function-and-default.js
new file mode 100644
index 00000000000000..bd45a875a5eb69
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function-and-default.js
@@ -0,0 +1,6 @@
+/**
+ * Function declaration example.
+ */
+export function functionDeclaration() {}
+
+export default functionDeclaration;
diff --git a/packages/docgen/tests/fixtures/named-function-and-default.json b/packages/docgen/tests/fixtures/named-function-and-default.json
new file mode 100644
index 00000000000000..9aee275e9fa5a1
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function-and-default.json
@@ -0,0 +1,77 @@
+[
+	{
+		"type": "ExportNamedDeclaration",
+		"start": 41,
+		"end": 81,
+		"range": [
+			41,
+			81
+		],
+		"declaration": {
+			"type": "FunctionDeclaration",
+			"start": 48,
+			"end": 81,
+			"range": [
+				48,
+				81
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 57,
+				"end": 76,
+				"range": [
+					57,
+					76
+				],
+				"name": "functionDeclaration"
+			},
+			"generator": false,
+			"expression": false,
+			"async": false,
+			"params": [],
+			"body": {
+				"type": "BlockStatement",
+				"start": 79,
+				"end": 81,
+				"range": [
+					79,
+					81
+				],
+				"body": []
+			}
+		},
+		"specifiers": [],
+		"source": null,
+		"leadingComments": [
+			{
+				"type": "Block",
+				"value": "*\n * Function declaration example.\n ",
+				"start": 0,
+				"end": 40,
+				"range": [
+					0,
+					40
+				]
+			}
+		]
+	},
+	{
+		"type": "ExportDefaultDeclaration",
+		"start": 83,
+		"end": 118,
+		"range": [
+			83,
+			118
+		],
+		"declaration": {
+			"type": "Identifier",
+			"start": 98,
+			"end": 117,
+			"range": [
+				98,
+				117
+			],
+			"name": "functionDeclaration"
+		}
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 131ecf30a55679..e5f67bd2377c45 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -173,6 +173,26 @@ test( 'IR - named (JSDoc in identifer declaration, module dependency)', function
 	t.end();
 } );
 
+test( 'IR - named and default', function( t ) {
+	const tokens = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-function-and-default.json' ),
+		'utf-8'
+	);
+	const ast = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-function-and-default-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokens )[ 0 ], JSON.parse( ast ) ),
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokens )[ 1 ], JSON.parse( ast ) ),
+		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
+	);
+	t.end();
+} );
+
 test( 'IR - namespace (JSDoc in identifer declaration, module dependency)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/namespace.json' ),

From 12621e97f0c72399fc5fb310c9b2a4680065f1ec Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 12:23:47 +0100
Subject: [PATCH 077/213] Add JSDoc lookup for named inline nodes such as:

export function myFunction
---
 .../src/get-intermediate-representation.js    |   8 +-
 .../named-function-and-default-ast.json       | 100 +++++++++++++++-
 .../tests/fixtures/named-identifier-ast.json  | 112 +++++++++++++++++-
 3 files changed, 215 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index d68f9f6e7b382f..db016c89f50c5b 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -14,15 +14,17 @@ const UNDOCUMENTED = 'Undocumented declaration.';
 const NAMESPACE_EXPORT = '*';
 const DEFAULT_EXPORT = 'default';
 
+const hasVariableWithName = ( node, name ) =>
+	node.declarations.some( ( declaration ) => declaration.id.name === name );
+
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc = getJSDocFromToken( token );
 	if ( doc === undefined && entry && entry.module === null ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return ( node.type === 'ClassDeclaration' && node.id.name === entry.localName ) ||
 				( node.type === 'FunctionDeclaration' && node.id.name === entry.localName ) ||
-				( node.type === 'VariableDeclaration' && ( node.declarations ).some(
-					( declaration ) => declaration.id.name === entry.localName )
-				);
+				( node.type === 'VariableDeclaration' && hasVariableWithName( node, entry.localName ) ) ||
+				( node.type === 'ExportNamedDeclaration' && node.declaration && node.declaration.id.name === entry.localName );
 		} );
 		if ( candidates.length === 1 ) {
 			doc = getJSDocFromToken( candidates[ 0 ] );
diff --git a/packages/docgen/tests/fixtures/named-function-and-default-ast.json b/packages/docgen/tests/fixtures/named-function-and-default-ast.json
index 7638b5572c8572..07f17844d5caf4 100644
--- a/packages/docgen/tests/fixtures/named-function-and-default-ast.json
+++ b/packages/docgen/tests/fixtures/named-function-and-default-ast.json
@@ -1 +1,99 @@
-{"type":"Program","start":0,"end":119,"range":[41,118],"body":[{"type":"ExportNamedDeclaration","start":41,"end":81,"range":[41,81],"declaration":{"type":"FunctionDeclaration","start":48,"end":81,"range":[48,81],"id":{"type":"Identifier","start":57,"end":76,"range":[57,76],"name":"functionDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":79,"end":81,"range":[79,81],"body":[]}},"specifiers":[],"source":null,"leadingComments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}]},{"type":"ExportDefaultDeclaration","start":83,"end":118,"range":[83,118],"declaration":{"type":"Identifier","start":98,"end":117,"range":[98,117],"name":"functionDeclaration"}}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}]}
\ No newline at end of file
+{
+	"type": "Program",
+	"start": 0,
+	"end": 119,
+	"range": [
+		41,
+		118
+	],
+	"body": [
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 41,
+			"end": 81,
+			"range": [
+				41,
+				81
+			],
+			"declaration": {
+				"type": "FunctionDeclaration",
+				"start": 48,
+				"end": 81,
+				"range": [
+					48,
+					81
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 57,
+					"end": 76,
+					"range": [
+						57,
+						76
+					],
+					"name": "functionDeclaration"
+				},
+				"generator": false,
+				"expression": false,
+				"async": false,
+				"params": [],
+				"body": {
+					"type": "BlockStatement",
+					"start": 79,
+					"end": 81,
+					"range": [
+						79,
+						81
+					],
+					"body": []
+				}
+			},
+			"specifiers": [],
+			"source": null,
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Function declaration example.\n ",
+					"start": 0,
+					"end": 40,
+					"range": [
+						0,
+						40
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportDefaultDeclaration",
+			"start": 83,
+			"end": 118,
+			"range": [
+				83,
+				118
+			],
+			"declaration": {
+				"type": "Identifier",
+				"start": 98,
+				"end": 117,
+				"range": [
+					98,
+					117
+				],
+				"name": "functionDeclaration"
+			}
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifier-ast.json b/packages/docgen/tests/fixtures/named-identifier-ast.json
index ec2fa1f02031bc..5a9256cc955d8c 100644
--- a/packages/docgen/tests/fixtures/named-identifier-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifier-ast.json
@@ -1 +1,111 @@
-{"type":"Program","start":0,"end":90,"range":[35,89],"body":[{"type":"FunctionDeclaration","start":35,"end":62,"range":[35,62],"id":{"type":"Identifier","start":44,"end":57,"range":[44,57],"name":"myDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":60,"end":62,"range":[60,62],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * My declaration example.\n ","start":0,"end":34,"range":[0,34]}]},{"type":"ExportNamedDeclaration","start":64,"end":89,"range":[64,89],"declaration":null,"specifiers":[{"type":"ExportSpecifier","start":73,"end":86,"range":[73,86],"local":{"type":"Identifier","start":73,"end":86,"range":[73,86],"name":"myDeclaration"},"exported":{"type":"Identifier","start":73,"end":86,"range":[73,86],"name":"myDeclaration"}}],"source":null}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * My declaration example.\n ","start":0,"end":34,"range":[0,34]}]}
\ No newline at end of file
+{
+	"type": "Program",
+	"start": 0,
+	"end": 90,
+	"range": [
+		35,
+		89
+	],
+	"body": [
+		{
+			"type": "FunctionDeclaration",
+			"start": 35,
+			"end": 62,
+			"range": [
+				35,
+				62
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 44,
+				"end": 57,
+				"range": [
+					44,
+					57
+				],
+				"name": "myDeclaration"
+			},
+			"generator": false,
+			"expression": false,
+			"async": false,
+			"params": [],
+			"body": {
+				"type": "BlockStatement",
+				"start": 60,
+				"end": 62,
+				"range": [
+					60,
+					62
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * My declaration example.\n ",
+					"start": 0,
+					"end": 34,
+					"range": [
+						0,
+						34
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 64,
+			"end": 89,
+			"range": [
+				64,
+				89
+			],
+			"declaration": null,
+			"specifiers": [
+				{
+					"type": "ExportSpecifier",
+					"start": 73,
+					"end": 86,
+					"range": [
+						73,
+						86
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 73,
+						"end": 86,
+						"range": [
+							73,
+							86
+						],
+						"name": "myDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 73,
+						"end": 86,
+						"range": [
+							73,
+							86
+						],
+						"name": "myDeclaration"
+					}
+				}
+			],
+			"source": null
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
+			"range": [
+				0,
+				34
+			]
+		}
+	]
+}
\ No newline at end of file

From 626ad86a2bfd1a77d815f0f01b514b89467ec91e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 12:26:04 +0100
Subject: [PATCH 078/213] Update coverage

---
 packages/docgen/coverage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 2b1ac34ddfdeec..44e2ec8a64239d 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -24,7 +24,6 @@ ES6 modules:
 - [ ] e2e-tests - what shall be documented?
 - [ ] edit-post - directory dependency
 - [ ] editor - directory dependency
-- [ ] element - `renderToString`
 - [ ] hooks - `import something; ... export something;`
 - [ ] npm-package-json-lint-config - CONFIG file
 - [ ] nux - directory dependency
@@ -45,6 +44,7 @@ ES6 modules:
 - [x] deprecated
 - [x] dom
 - [x] dom-ready
+- [x] element
 - [x] escape-html
 - [x] format-library - exports nothing
 - [x] html-entities

From ef09517e273c0cdcdf5ca308935fc5999811610d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 12:35:07 +0100
Subject: [PATCH 079/213] Better test organization

---
 ...ast.json => default-named-export-ast.json} |  0
 ...and-default.js => default-named-export.js} |  0
 ...default.json => default-named-export.json} |  0
 .../docgen/tests/test-get-export-entries.js   | 20 +++++++++
 .../test-get-intermediate-representation.js   | 44 +++++++++----------
 5 files changed, 40 insertions(+), 24 deletions(-)
 rename packages/docgen/tests/fixtures/{named-function-and-default-ast.json => default-named-export-ast.json} (100%)
 rename packages/docgen/tests/fixtures/{named-function-and-default.js => default-named-export.js} (100%)
 rename packages/docgen/tests/fixtures/{named-function-and-default.json => default-named-export.json} (100%)

diff --git a/packages/docgen/tests/fixtures/named-function-and-default-ast.json b/packages/docgen/tests/fixtures/default-named-export-ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function-and-default-ast.json
rename to packages/docgen/tests/fixtures/default-named-export-ast.json
diff --git a/packages/docgen/tests/fixtures/named-function-and-default.js b/packages/docgen/tests/fixtures/default-named-export.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function-and-default.js
rename to packages/docgen/tests/fixtures/default-named-export.js
diff --git a/packages/docgen/tests/fixtures/named-function-and-default.json b/packages/docgen/tests/fixtures/default-named-export.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function-and-default.json
rename to packages/docgen/tests/fixtures/default-named-export.json
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 51c6e223ac0e93..f16eb0b8d981d2 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -84,6 +84,26 @@ test( 'Export entries: default identifier', function( t ) {
 	t.end();
 } );
 
+test( 'Export entries: default named export', function( t ) {
+	const tokens = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-named-export.json' ),
+		'utf-8'
+	);
+	const namedExport = getExportEntries( JSON.parse( tokens )[ 0 ] );
+	t.deepEqual( namedExport, [ {
+		localName: 'functionDeclaration',
+		exportName: 'functionDeclaration',
+		module: null,
+	} ] );
+	const defaultExport = getExportEntries( JSON.parse( tokens )[ 1 ] );
+	t.deepEqual( defaultExport, [ {
+		localName: 'functionDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
+	t.end();
+} );
+
 test( 'Export entries: default variable', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-variable.json' ),
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index e5f67bd2377c45..b0bb9fdf9d6f7d 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -63,7 +63,7 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - default (JSDoc in identifier declaration, same file)', function( t ) {
+test( 'IR - default (JSDoc in same file)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
@@ -77,6 +77,22 @@ test( 'IR - default (JSDoc in identifier declaration, same file)', function( t )
 		description: 'Class declaration example.',
 		tags: [],
 	} ] );
+	const namedExport = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-named-export.json' ),
+		'utf-8'
+	);
+	const namedExportAST = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-named-export-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
+		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
+	);
 	t.end();
 } );
 
@@ -119,7 +135,7 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - named (JSDoc in identifier declaration, same file)', function( t ) {
+test( 'IR - named (JSDoc in same file)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
@@ -149,7 +165,7 @@ test( 'IR - named (JSDoc in identifier declaration, same file)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - named (JSDoc in identifer declaration, module dependency)', function( t ) {
+test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	const tokenDefault = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
@@ -173,27 +189,7 @@ test( 'IR - named (JSDoc in identifer declaration, module dependency)', function
 	t.end();
 } );
 
-test( 'IR - named and default', function( t ) {
-	const tokens = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function-and-default.json' ),
-		'utf-8'
-	);
-	const ast = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function-and-default-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokens )[ 0 ], JSON.parse( ast ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokens )[ 1 ], JSON.parse( ast ) ),
-		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'IR - namespace (JSDoc in identifer declaration, module dependency)', function( t ) {
+test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/namespace.json' ),
 		'utf-8'

From d98b214a7ad076619caf7a217f128ed89f7d6aab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 13:20:01 +0100
Subject: [PATCH 080/213] Implement JSDoc lookup in default identifier from
 import

---
 .../src/get-intermediate-representation.js    | 37 +++++++--
 .../tests/fixtures/default-import-ast.json    | 83 +++++++++++++++++++
 .../fixtures/default-import-module-ir.json    |  7 ++
 .../tests/fixtures/default-import-module.js   |  6 ++
 .../docgen/tests/fixtures/default-import.js   |  3 +
 .../docgen/tests/fixtures/default-import.json | 19 +++++
 .../docgen/tests/test-get-export-entries.js   | 14 ++++
 .../test-get-intermediate-representation.js   | 24 ++++++
 8 files changed, 188 insertions(+), 5 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/default-import-ast.json
 create mode 100644 packages/docgen/tests/fixtures/default-import-module-ir.json
 create mode 100644 packages/docgen/tests/fixtures/default-import-module.js
 create mode 100644 packages/docgen/tests/fixtures/default-import.js
 create mode 100644 packages/docgen/tests/fixtures/default-import.json

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index db016c89f50c5b..760e0c9c00c4e8 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -14,20 +14,47 @@ const UNDOCUMENTED = 'Undocumented declaration.';
 const NAMESPACE_EXPORT = '*';
 const DEFAULT_EXPORT = 'default';
 
+const hasClassWithName = ( node, name ) =>
+	node.type === 'ClassDeclaration' &&
+	node.id.name === name;
+
+const hasFunctionWithName = ( node, name ) =>
+	node.type === 'FunctionDeclaration' &&
+	node.id.name === name;
+
 const hasVariableWithName = ( node, name ) =>
+	node.type === 'VariableDeclaration' &&
 	node.declarations.some( ( declaration ) => declaration.id.name === name );
 
+const hasNamedExportWithName = ( node, name ) =>
+	node.type === 'ExportNamedDeclaration' &&
+	node.declaration &&
+	node.declaration.id.name === name;
+
+const hasImportWithName = ( node, name ) =>
+	node.type === 'ImportDeclaration' &&
+	node.specifiers.some( ( specifier ) => specifier.local.name === name );
+
+const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
+
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc = getJSDocFromToken( token );
 	if ( doc === undefined && entry && entry.module === null ) {
 		const candidates = ast.body.filter( ( node ) => {
-			return ( node.type === 'ClassDeclaration' && node.id.name === entry.localName ) ||
-				( node.type === 'FunctionDeclaration' && node.id.name === entry.localName ) ||
-				( node.type === 'VariableDeclaration' && hasVariableWithName( node, entry.localName ) ) ||
-				( node.type === 'ExportNamedDeclaration' && node.declaration && node.declaration.id.name === entry.localName );
+			return hasClassWithName( node, entry.localName ) ||
+				hasFunctionWithName( node, entry.localName ) ||
+				hasVariableWithName( node, entry.localName ) ||
+				hasNamedExportWithName( node, entry.localName ) ||
+				hasImportWithName( node, entry.localName );
 		} );
-		if ( candidates.length === 1 ) {
+		if ( candidates.length === 1 && ! isImportDeclaration( candidates[ 0 ] ) ) {
 			doc = getJSDocFromToken( candidates[ 0 ] );
+		} else if ( candidates.length === 1 && isImportDeclaration( candidates[ 0 ] ) ) {
+			const importNode = candidates[ 0 ];
+			const ir = parseDependency( getDependencyPath( importNode ) );
+			doc = ir.find( ( exportDeclaration ) => importNode.specifiers.some(
+				( specifier ) => specifier.imported.name === exportDeclaration.name
+			) );
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
diff --git a/packages/docgen/tests/fixtures/default-import-ast.json b/packages/docgen/tests/fixtures/default-import-ast.json
new file mode 100644
index 00000000000000..35b7fb28585a49
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-ast.json
@@ -0,0 +1,83 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 98,
+	"range": [
+		0,
+		97
+	],
+	"body": [
+		{
+			"type": "ImportDeclaration",
+			"start": 0,
+			"end": 60,
+			"range": [
+				0,
+				60
+			],
+			"specifiers": [
+				{
+					"type": "ImportSpecifier",
+					"start": 9,
+					"end": 28,
+					"range": [
+						9,
+						28
+					],
+					"imported": {
+						"type": "Identifier",
+						"start": 9,
+						"end": 28,
+						"range": [
+							9,
+							28
+						],
+						"name": "functionDeclaration"
+					},
+					"local": {
+						"type": "Identifier",
+						"start": 9,
+						"end": 28,
+						"range": [
+							9,
+							28
+						],
+						"name": "functionDeclaration"
+					}
+				}
+			],
+			"source": {
+				"type": "Literal",
+				"start": 36,
+				"end": 59,
+				"range": [
+					36,
+					59
+				],
+				"value": "default-import-module",
+				"raw": "'default-import-module'"
+			}
+		},
+		{
+			"type": "ExportDefaultDeclaration",
+			"start": 62,
+			"end": 97,
+			"range": [
+				62,
+				97
+			],
+			"declaration": {
+				"type": "Identifier",
+				"start": 77,
+				"end": 96,
+				"range": [
+					77,
+					96
+				],
+				"name": "functionDeclaration"
+			}
+		}
+	],
+	"sourceType": "module",
+	"comments": []
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import-module-ir.json b/packages/docgen/tests/fixtures/default-import-module-ir.json
new file mode 100644
index 00000000000000..b2c0a7beccba2f
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-module-ir.json
@@ -0,0 +1,7 @@
+[
+	{
+		"name": "functionDeclaration",
+		"description": "Function declaration.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import-module.js b/packages/docgen/tests/fixtures/default-import-module.js
new file mode 100644
index 00000000000000..7ec5c68c3fbb3d
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-module.js
@@ -0,0 +1,6 @@
+/**
+ * Function declaration.
+ */
+function functionDeclaration() {}
+
+export { functionDeclaration };
diff --git a/packages/docgen/tests/fixtures/default-import.js b/packages/docgen/tests/fixtures/default-import.js
new file mode 100644
index 00000000000000..3fa0b37f673fd5
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import.js
@@ -0,0 +1,3 @@
+import { functionDeclaration } from 'default-import-module';
+
+export default functionDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import.json b/packages/docgen/tests/fixtures/default-import.json
new file mode 100644
index 00000000000000..b08e0a16f78d13
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import.json
@@ -0,0 +1,19 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 62,
+	"end": 97,
+	"range": [
+		62,
+		97
+	],
+	"declaration": {
+		"type": "Identifier",
+		"start": 77,
+		"end": 96,
+		"range": [
+			77,
+			96
+		],
+		"name": "functionDeclaration"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index f16eb0b8d981d2..d84a6679a22116 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -84,6 +84,20 @@ test( 'Export entries: default identifier', function( t ) {
 	t.end();
 } );
 
+test( 'Export entries: default import', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import.json' ),
+		'utf-8'
+	);
+	const name = getExportEntries( JSON.parse( token ) );
+	t.deepEqual( name, [ {
+		localName: 'functionDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
+	t.end();
+} );
+
 test( 'Export entries: default named export', function( t ) {
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-named-export.json' ),
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index b0bb9fdf9d6f7d..2d35d3e8f71ea7 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -96,6 +96,30 @@ test( 'IR - default (JSDoc in same file)', function( t ) {
 	t.end();
 } );
 
+test( 'IR - default (JSDoc in module dependency)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import.json' ),
+		'utf-8'
+	);
+	const ast = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-ast.json' ),
+		'utf-8'
+	);
+	const getModule = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ), getModule ),
+		[ {
+			name: 'default',
+			description: 'Function declaration.',
+			tags: [],
+		} ]
+	);
+	t.end();
+} );
+
 test( 'IR - named (JSDoc in export statement)', function( t ) {
 	const tokenClass = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-class.json' ),

From 2b4019ddd6c18474d5665ddcb4d67eaa738d39d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 13:27:16 +0100
Subject: [PATCH 081/213] Better test organization

---
 ...ast.json => default-import-named-ast.json} | 52 +++++++++----------
 ...on => default-import-named-module-ir.json} |  0
 ...dule.js => default-import-named-module.js} |  0
 .../tests/fixtures/default-import-named.js    |  3 ++
 ...-import.json => default-import-named.json} | 18 +++----
 .../docgen/tests/fixtures/default-import.js   |  3 --
 .../docgen/tests/test-get-export-entries.js   |  6 +--
 .../test-get-intermediate-representation.js   |  6 +--
 8 files changed, 44 insertions(+), 44 deletions(-)
 rename packages/docgen/tests/fixtures/{default-import-ast.json => default-import-named-ast.json} (64%)
 rename packages/docgen/tests/fixtures/{default-import-module-ir.json => default-import-named-module-ir.json} (100%)
 rename packages/docgen/tests/fixtures/{default-import-module.js => default-import-named-module.js} (100%)
 create mode 100644 packages/docgen/tests/fixtures/default-import-named.js
 rename packages/docgen/tests/fixtures/{default-import.json => default-import-named.json} (51%)
 delete mode 100644 packages/docgen/tests/fixtures/default-import.js

diff --git a/packages/docgen/tests/fixtures/default-import-ast.json b/packages/docgen/tests/fixtures/default-import-named-ast.json
similarity index 64%
rename from packages/docgen/tests/fixtures/default-import-ast.json
rename to packages/docgen/tests/fixtures/default-import-named-ast.json
index 35b7fb28585a49..efa7bded38f7e3 100644
--- a/packages/docgen/tests/fixtures/default-import-ast.json
+++ b/packages/docgen/tests/fixtures/default-import-named-ast.json
@@ -1,28 +1,28 @@
 {
 	"type": "Program",
 	"start": 0,
-	"end": 98,
+	"end": 117,
 	"range": [
 		0,
-		97
+		116
 	],
 	"body": [
 		{
 			"type": "ImportDeclaration",
 			"start": 0,
-			"end": 60,
+			"end": 85,
 			"range": [
 				0,
-				60
+				85
 			],
 			"specifiers": [
 				{
 					"type": "ImportSpecifier",
 					"start": 9,
-					"end": 28,
+					"end": 45,
 					"range": [
 						9,
-						28
+						45
 					],
 					"imported": {
 						"type": "Identifier",
@@ -36,45 +36,45 @@
 					},
 					"local": {
 						"type": "Identifier",
-						"start": 9,
-						"end": 28,
+						"start": 32,
+						"end": 45,
 						"range": [
-							9,
-							28
+							32,
+							45
 						],
-						"name": "functionDeclaration"
+						"name": "fnDeclaration"
 					}
 				}
 			],
 			"source": {
 				"type": "Literal",
-				"start": 36,
-				"end": 59,
+				"start": 53,
+				"end": 84,
 				"range": [
-					36,
-					59
+					53,
+					84
 				],
-				"value": "default-import-module",
-				"raw": "'default-import-module'"
+				"value": "./default-import-named-module",
+				"raw": "'./default-import-named-module'"
 			}
 		},
 		{
 			"type": "ExportDefaultDeclaration",
-			"start": 62,
-			"end": 97,
+			"start": 87,
+			"end": 116,
 			"range": [
-				62,
-				97
+				87,
+				116
 			],
 			"declaration": {
 				"type": "Identifier",
-				"start": 77,
-				"end": 96,
+				"start": 102,
+				"end": 115,
 				"range": [
-					77,
-					96
+					102,
+					115
 				],
-				"name": "functionDeclaration"
+				"name": "fnDeclaration"
 			}
 		}
 	],
diff --git a/packages/docgen/tests/fixtures/default-import-module-ir.json b/packages/docgen/tests/fixtures/default-import-named-module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-module-ir.json
rename to packages/docgen/tests/fixtures/default-import-named-module-ir.json
diff --git a/packages/docgen/tests/fixtures/default-import-module.js b/packages/docgen/tests/fixtures/default-import-named-module.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-module.js
rename to packages/docgen/tests/fixtures/default-import-named-module.js
diff --git a/packages/docgen/tests/fixtures/default-import-named.js b/packages/docgen/tests/fixtures/default-import-named.js
new file mode 100644
index 00000000000000..0f9b6032b32e9c
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-named.js
@@ -0,0 +1,3 @@
+import { functionDeclaration as fnDeclaration } from './default-import-named-module';
+
+export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import.json b/packages/docgen/tests/fixtures/default-import-named.json
similarity index 51%
rename from packages/docgen/tests/fixtures/default-import.json
rename to packages/docgen/tests/fixtures/default-import-named.json
index b08e0a16f78d13..6b65941d8de579 100644
--- a/packages/docgen/tests/fixtures/default-import.json
+++ b/packages/docgen/tests/fixtures/default-import-named.json
@@ -1,19 +1,19 @@
 {
 	"type": "ExportDefaultDeclaration",
-	"start": 62,
-	"end": 97,
+	"start": 87,
+	"end": 116,
 	"range": [
-		62,
-		97
+		87,
+		116
 	],
 	"declaration": {
 		"type": "Identifier",
-		"start": 77,
-		"end": 96,
+		"start": 102,
+		"end": 115,
 		"range": [
-			77,
-			96
+			102,
+			115
 		],
-		"name": "functionDeclaration"
+		"name": "fnDeclaration"
 	}
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import.js b/packages/docgen/tests/fixtures/default-import.js
deleted file mode 100644
index 3fa0b37f673fd5..00000000000000
--- a/packages/docgen/tests/fixtures/default-import.js
+++ /dev/null
@@ -1,3 +0,0 @@
-import { functionDeclaration } from 'default-import-module';
-
-export default functionDeclaration;
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index d84a6679a22116..2c09a571f091cc 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -84,14 +84,14 @@ test( 'Export entries: default identifier', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default import', function( t ) {
+test( 'Export entries: default import (named)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import.json' ),
+		path.join( __dirname, './fixtures/default-import-named.json' ),
 		'utf-8'
 	);
 	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [ {
-		localName: 'functionDeclaration',
+		localName: 'fnDeclaration',
 		exportName: 'default',
 		module: null,
 	} ] );
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 2d35d3e8f71ea7..dfd278767dc55c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -98,15 +98,15 @@ test( 'IR - default (JSDoc in same file)', function( t ) {
 
 test( 'IR - default (JSDoc in module dependency)', function( t ) {
 	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import.json' ),
+		path.join( __dirname, './fixtures/default-import-named.json' ),
 		'utf-8'
 	);
 	const ast = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-ast.json' ),
+		path.join( __dirname, './fixtures/default-import-named-ast.json' ),
 		'utf-8'
 	);
 	const getModule = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-module-ir.json' ),
+		path.join( __dirname, './fixtures/default-import-named-module-ir.json' ),
 		'utf-8'
 	) );
 	t.deepEqual(

From a21d8c00545bc56c9e3aee2ac324e1dfe90575f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 14:45:41 +0100
Subject: [PATCH 082/213] getExportEntries: test for _import default from
 module_

---
 .../tests/fixtures/default-import-default.js  |  3 +++
 .../fixtures/default-import-default.json      | 19 +++++++++++++++++++
 .../docgen/tests/test-get-export-entries.js   | 14 ++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/default-import-default.js
 create mode 100644 packages/docgen/tests/fixtures/default-import-default.json

diff --git a/packages/docgen/tests/fixtures/default-import-default.js b/packages/docgen/tests/fixtures/default-import-default.js
new file mode 100644
index 00000000000000..d5bec9984b17b0
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-default.js
@@ -0,0 +1,3 @@
+import fnDeclaration from './default-import-default-module';
+
+export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import-default.json b/packages/docgen/tests/fixtures/default-import-default.json
new file mode 100644
index 00000000000000..6b47c06b1b29fc
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-default.json
@@ -0,0 +1,19 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 62,
+	"end": 91,
+	"range": [
+		62,
+		91
+	],
+	"declaration": {
+		"type": "Identifier",
+		"start": 77,
+		"end": 90,
+		"range": [
+			77,
+			90
+		],
+		"name": "fnDeclaration"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 2c09a571f091cc..5905ac38f2f529 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -98,6 +98,20 @@ test( 'Export entries: default import (named)', function( t ) {
 	t.end();
 } );
 
+test( 'Export entries: default import (default)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default.json' ),
+		'utf-8'
+	);
+	const name = getExportEntries( JSON.parse( token ) );
+	t.deepEqual( name, [ {
+		localName: 'fnDeclaration',
+		exportName: 'default',
+		module: null,
+	} ] );
+	t.end();
+} );
+
 test( 'Export entries: default named export', function( t ) {
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-named-export.json' ),

From a8b7d0d588704b58a455f62fcc599a2dfb24cfcc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 18:06:57 +0100
Subject: [PATCH 083/213] Add support for JSDoc lookup of imported identifiers

Example with default import:

	import myDefault from './module';
	...
	export { myDefault };

Example with named import:

	import { importedName as localName } from './module';
	...
	export { localName };
---
 .../src/get-intermediate-representation.js    | 23 ++++--
 .../fixtures/default-import-default-ast.json  | 73 +++++++++++++++++++
 .../default-import-default-module-ir.json     |  7 ++
 .../fixtures/default-import-default-module.js |  6 ++
 .../test-get-intermediate-representation.js   | 28 ++++++-
 5 files changed, 125 insertions(+), 12 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/default-import-default-ast.json
 create mode 100644 packages/docgen/tests/fixtures/default-import-default-module-ir.json
 create mode 100644 packages/docgen/tests/fixtures/default-import-default-module.js

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 760e0c9c00c4e8..a7210e61569049 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -37,6 +37,13 @@ const hasImportWithName = ( node, name ) =>
 
 const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
 
+const someImportMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
+	if ( specifier.type === 'ImportDefaultSpecifier' ) {
+		return name === 'default';
+	}
+	return name === specifier.imported.name;
+} );
+
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc = getJSDocFromToken( token );
 	if ( doc === undefined && entry && entry.module === null ) {
@@ -47,14 +54,14 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 				hasNamedExportWithName( node, entry.localName ) ||
 				hasImportWithName( node, entry.localName );
 		} );
-		if ( candidates.length === 1 && ! isImportDeclaration( candidates[ 0 ] ) ) {
-			doc = getJSDocFromToken( candidates[ 0 ] );
-		} else if ( candidates.length === 1 && isImportDeclaration( candidates[ 0 ] ) ) {
-			const importNode = candidates[ 0 ];
-			const ir = parseDependency( getDependencyPath( importNode ) );
-			doc = ir.find( ( exportDeclaration ) => importNode.specifiers.some(
-				( specifier ) => specifier.imported.name === exportDeclaration.name
-			) );
+		if ( candidates.length === 1 ) {
+			const node = candidates[ 0 ];
+			if ( isImportDeclaration( node ) ) {
+				const ir = parseDependency( getDependencyPath( node ) );
+				doc = ir.find( ( { name } ) => someImportMatchesName( name, node ) );
+			} else {
+				doc = getJSDocFromToken( node );
+			}
 		}
 	} else if ( doc === undefined && entry && entry.module !== null ) {
 		const ir = parseDependency( getDependencyPath( token ) );
diff --git a/packages/docgen/tests/fixtures/default-import-default-ast.json b/packages/docgen/tests/fixtures/default-import-default-ast.json
new file mode 100644
index 00000000000000..e7ac254cec46f2
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-default-ast.json
@@ -0,0 +1,73 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 92,
+	"range": [
+		0,
+		91
+	],
+	"body": [
+		{
+			"type": "ImportDeclaration",
+			"start": 0,
+			"end": 60,
+			"range": [
+				0,
+				60
+			],
+			"specifiers": [
+				{
+					"type": "ImportDefaultSpecifier",
+					"start": 7,
+					"end": 20,
+					"range": [
+						7,
+						20
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 7,
+						"end": 20,
+						"range": [
+							7,
+							20
+						],
+						"name": "fnDeclaration"
+					}
+				}
+			],
+			"source": {
+				"type": "Literal",
+				"start": 26,
+				"end": 59,
+				"range": [
+					26,
+					59
+				],
+				"value": "./default-import-default-module",
+				"raw": "'./default-import-default-module'"
+			}
+		},
+		{
+			"type": "ExportDefaultDeclaration",
+			"start": 62,
+			"end": 91,
+			"range": [
+				62,
+				91
+			],
+			"declaration": {
+				"type": "Identifier",
+				"start": 77,
+				"end": 90,
+				"range": [
+					77,
+					90
+				],
+				"name": "fnDeclaration"
+			}
+		}
+	],
+	"sourceType": "module",
+	"comments": []
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import-default-module-ir.json b/packages/docgen/tests/fixtures/default-import-default-module-ir.json
new file mode 100644
index 00000000000000..9aaa9dc2213f5c
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-default-module-ir.json
@@ -0,0 +1,7 @@
+[
+	{
+		"name": "default",
+		"description": "Function declaration.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import-default-module.js b/packages/docgen/tests/fixtures/default-import-default-module.js
new file mode 100644
index 00000000000000..4da030a5b9d0a1
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-import-default-module.js
@@ -0,0 +1,6 @@
+/**
+ * Function declaration.
+ */
+function functionDeclaration() {}
+
+export default functionDeclaration;
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index dfd278767dc55c..7444b93b44a95c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -97,20 +97,40 @@ test( 'IR - default (JSDoc in same file)', function( t ) {
 } );
 
 test( 'IR - default (JSDoc in module dependency)', function( t ) {
-	const token = fs.readFileSync(
+	const tokenDefault = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default.json' ),
+		'utf-8'
+	);
+	const astDefault = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default-ast.json' ),
+		'utf-8'
+	);
+	const getModuleDefault = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
+		[ {
+			name: 'default',
+			description: 'Function declaration.',
+			tags: [],
+		} ]
+	);
+	const tokenNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-import-named.json' ),
 		'utf-8'
 	);
-	const ast = fs.readFileSync(
+	const astNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-import-named-ast.json' ),
 		'utf-8'
 	);
-	const getModule = () => JSON.parse( fs.readFileSync(
+	const getModuleNamed = () => JSON.parse( fs.readFileSync(
 		path.join( __dirname, './fixtures/default-import-named-module-ir.json' ),
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ), getModule ),
+		getIntermediateRepresentation( JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
 		[ {
 			name: 'default',
 			description: 'Function declaration.',

From 970fcd72af25ac0103f5909448d0a35749b514b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 18:10:03 +0100
Subject: [PATCH 084/213] Update coverage

---
 packages/docgen/coverage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 44e2ec8a64239d..b8e8a609db1382 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -24,7 +24,6 @@ ES6 modules:
 - [ ] e2e-tests - what shall be documented?
 - [ ] edit-post - directory dependency
 - [ ] editor - directory dependency
-- [ ] hooks - `import something; ... export something;`
 - [ ] npm-package-json-lint-config - CONFIG file
 - [ ] nux - directory dependency
 - [ ] plugins - directory dependency
@@ -47,6 +46,7 @@ ES6 modules:
 - [x] element
 - [x] escape-html
 - [x] format-library - exports nothing
+- [x] hooks
 - [x] html-entities
 - [x] i18n
 - [x] jest-console - export nothing

From 3465afdd3c002eb5c38dc68c5ee095eb212da7b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 22 Jan 2019 18:32:49 +0100
Subject: [PATCH 085/213] Install docgen package

---
 package.json                 | 3 ++-
 packages/docgen/package.json | 4 +++-
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 97fb5c5126d485..f66a86d2fc0b00 100644
--- a/package.json
+++ b/package.json
@@ -66,6 +66,7 @@
 		"@wordpress/babel-preset-default": "file:packages/babel-preset-default",
 		"@wordpress/browserslist-config": "file:packages/browserslist-config",
 		"@wordpress/custom-templated-path-webpack-plugin": "file:packages/custom-templated-path-webpack-plugin",
+		"@wordpress/docgen": "file:packages/docgen",
 		"@wordpress/e2e-test-utils": "file:packages/e2e-test-utils",
 		"@wordpress/e2e-tests": "file:packages/e2e-tests",
 		"@wordpress/eslint-plugin": "file:packages/eslint-plugin",
@@ -161,7 +162,7 @@
 		"dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"",
 		"dev:packages": "node ./bin/packages/watch.js",
 		"docs:build": "node docs/tool",
-		"docs:api": "node packages/docgen/src/cli.js",
+		"docs:api": "docgen",
 		"fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"",
 		"fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json",
 		"fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit",
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 20a74e2a44cd9d..ddd28f0f39b51b 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -16,7 +16,9 @@
 	"bugs": {
 		"url": "https://github.com/WordPress/gutenberg/issues"
 	},
-	"main": "src/index.js",
+	"bin": {
+		"docgen": "./src/cli.js"
+	},
 	"devDependencies": {
 		"faucet": "0.0.1",
 		"tape": "4.9.2"

From 33ee82bc0860c62c30ce6fb0c9fab4b963528593 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 13:19:37 +0100
Subject: [PATCH 086/213] Improve CLI

---
 packages/docgen/coverage.md                   |   4 +-
 packages/docgen/src/cli.js                    | 106 +++++++++++++-----
 packages/docgen/src/engine.js                 |  14 +--
 packages/docgen/src/formatter.js              |  21 ++--
 .../src/get-intermediate-representation.js    |   4 +-
 5 files changed, 102 insertions(+), 47 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index b8e8a609db1382..9bb73000ac92bb 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -18,14 +18,12 @@ ES6 modules:
 - [ ] block-serialization-spec-parser - not `src/index.js`
 - [ ] blocks - directory dependency
 - [ ] components - directory dependency
-- [ ] compose - directory dependency
 - [ ] data - directory dependency
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
 - [ ] edit-post - directory dependency
 - [ ] editor - directory dependency
 - [ ] npm-package-json-lint-config - CONFIG file
-- [ ] nux - directory dependency
 - [ ] plugins - directory dependency
 - [ ] scripts - what shall be documented? not `src/index`
 - [-] keycodes - how to document CONSTANTS?
@@ -38,6 +36,7 @@ ES6 modules:
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
+- [x] compose - directory dependency
 - [x] core-data - export nothing
 - [x] date
 - [x] deprecated
@@ -53,6 +52,7 @@ ES6 modules:
 - [x] jest-puppeteer-axe - export nothing
 - [x] list-reusable-blocks - export nothing
 - [x] notices - does not export anything
+- [x] nux - directory dependency
 - [x] priority-queue
 - [x] rich-text
 - [x] shortcode
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index e9d0a1ae6a8314..298d19f971121f 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -4,40 +4,94 @@
 const fs = require( 'fs' );
 const path = require( 'path' );
 
+/**
+ * External dependencies.
+ */
+const { last } = require( 'lodash' );
+
 /**
  * Internal dependencies.
  */
 const engine = require( './engine' );
 const formatter = require( './formatter' );
 
-const packageName = process.argv[ 2 ];
-if ( packageName === undefined ) {
-	process.stdout.write( '\nUsage: <path-to-docgen> <gutenberg-package-name>\n\n\n' );
+/**
+ * Helpers functions.
+ */
+
+const relativeToAbsolute = ( basePath, relativePath ) => {
+	const target = path.join( path.dirname( basePath ), relativePath );
+	let targetFile = target + '.js';
+	if ( fs.existsSync( targetFile ) ) {
+		return targetFile;
+	}
+	targetFile = path.join( target, 'index.js' );
+	if ( fs.existsSync( targetFile ) ) {
+		return targetFile;
+	}
+	process.stdout.write( '\nRelative path does not exists.' );
+	process.stdout.write( '\n' );
+	process.stdout.write( `\nBase: ${ basePath }` );
+	process.stdout.write( `\nRelative: ${ relativePath }` );
+	process.stdout.write( '\n\n' );
 	process.exit( 1 );
-}
+};
+
+const getIRFromRelativePath = ( basePath ) => ( relativePath ) => {
+	if ( ! relativePath.startsWith( './' ) ) {
+		return [];
+	}
+	const absolutePath = relativeToAbsolute( basePath, relativePath );
+	const result = processFile( absolutePath );
+	return result.ir || undefined;
+};
 
-const root = path.join( __dirname, '../../../' );
-// TODO:
-// - take input file from package.json?
-// - make CLI take input file instead of package?
-const srcDir = path.join( root, `packages/${ packageName }/src/` );
-const input = path.join( srcDir, `index.js` );
-const doc = path.join( root, `packages/${ packageName }/api.md` );
-const ir = path.join( root, `packages/${ packageName }/ir.json` );
-const tokens = path.join( root, `packages/${ packageName }/tokens.json` );
-const ast = path.join( root, `packages/${ packageName }/ast.json` );
-
-const getCodeFromPath = ( file ) => fs.readFileSync( path.join( srcDir, file + '.js' ), 'utf8' );
-
-fs.readFile( input, 'utf8', ( err, code ) => {
-	if ( err ) {
-		process.stdout.write( `\n${ input } does not exists.\n\n\n` );
+const processFile = ( inputFile ) => {
+	try {
+		const data = fs.readFileSync( inputFile, 'utf8' );
+		currentFileStack.push( inputFile );
+		const result = engine( data, getIRFromRelativePath( last( currentFileStack ) ) );
+		currentFileStack.pop( inputFile );
+		return result;
+	} catch ( e ) {
+		process.stdout.write( `\n${ e }` );
+		process.stdout.write( '\n\n' );
 		process.exit( 1 );
 	}
+};
+
+/**
+ * Start up processing.
+ */
+
+// Prepare input
+let initialInputFile = process.argv[ 2 ];
+if ( initialInputFile === undefined ) {
+	process.stdout.write( '\nUsage: <path-to-docgen> <relative-path-to-file>' );
+	process.stdout.write( '\n\n' );
+	process.exit( 1 );
+}
+initialInputFile = path.join( process.cwd(), initialInputFile );
+
+// Process
+const currentFileStack = []; // To keep track of file being processed.
+const result = processFile( initialInputFile );
+
+// Ouput
+const inputDirectory = path.dirname( initialInputFile );
+const doc = path.join( inputDirectory, 'api.md' );
+const ir = path.join( inputDirectory, 'ir.json' );
+const tokens = path.join( inputDirectory, 'tokens.json' );
+const ast = path.join( inputDirectory, 'ast.json' );
+
+if ( result === undefined ) {
+	process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' );
+	process.stdout.write( `\n${ initialInputFile }` );
+	process.stdout.write( '\n\n' );
+	process.exit( 0 );
+}
 
-	const result = engine( code, getCodeFromPath );
-	fs.writeFileSync( doc, formatter( result.ir ) );
-	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
-	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
-	fs.writeFileSync( ast, JSON.stringify( result.ast ) );
-} );
+fs.writeFileSync( doc, formatter( result.ir ) );
+fs.writeFileSync( ir, JSON.stringify( result.ir ) );
+fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
+fs.writeFileSync( ast, JSON.stringify( result.ast ) );
diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 195c5c2d538cde..3ed82da74e99c5 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -26,12 +26,7 @@ const getExportTokens = ( ast ) => ast.body.filter(
 	].some( ( declaration ) => declaration === node.type )
 );
 
-const getIRFromDependency = ( getCodeFromPath ) => ( path ) => {
-	const { ir } = engine( getCodeFromPath( path ) );
-	return ir;
-};
-
-const engine = ( code, getCodeFromPath = () => {} ) => {
+const engine = ( code, getIRFromPath = () => {} ) => {
 	const result = {};
 	result.ast = getAST( code );
 	result.tokens = getExportTokens( result.ast );
@@ -39,7 +34,7 @@ const engine = ( code, getCodeFromPath = () => {} ) => {
 		( token ) => getIntermediateRepresentation(
 			token,
 			result.ast,
-			getIRFromDependency( getCodeFromPath )
+			getIRFromPath
 		)
 	) );
 
@@ -50,8 +45,9 @@ const engine = ( code, getCodeFromPath = () => {} ) => {
  * Function that takes code and returns an intermediate representation.
  *
  * @param {string} code The code to parse.
- * @param {Function} [getCodeFromPath=noop] Callback to retrieve code
- * from a relative path.
+ * @param {Function} [getIRFromPath=noop] Callback to retrieve the
+ * Intermediate Representation from a path relative to the file
+ * being parsed.
  *
  * @return {Object} Intermediate Representation in JSON.
  */
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 8254b995e22db8..f838d2f77d9d98 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -2,14 +2,19 @@ module.exports = function( artifacts ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
 	docs.push( '\n' );
-	artifacts.forEach( ( artifact ) => {
-		docs.push( `## ${ artifact.name }` );
+	if ( artifacts && artifacts.length > 0 ) {
+		artifacts.forEach( ( artifact ) => {
+			docs.push( `## ${ artifact.name }` );
+			docs.push( '\n' );
+			docs.push( '\n' );
+			docs.push( artifact.description.replace( '\n', ' ' ) );
+			docs.push( '\n' );
+			docs.push( '\n' );
+		} );
+		docs.pop(); // remove last \n, we want one blank line at the end of the file.
+	} else {
+		docs.push( 'Nothing to document.' );
 		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( artifact.description.replace( '\n', ' ' ) );
-		docs.push( '\n' );
-		docs.push( '\n' );
-	} );
-	docs.pop(); // remove last \n, we want one blank line at the end of the file.
+	}
 	return docs.join( '' );
 };
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index a7210e61569049..52010d301325b7 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -82,9 +82,9 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
  * if an `ast` and `parseDependency` callback are provided.
  *
  * @param {Object} token Espree export token.
- * @param {Object} [ast] Espree ast of a single file.
+ * @param {Object} [ast] Espree ast of the file being parsed.
  * @param {Function} [parseDependency] Function that takes a path
- * and returns the AST of the dependency file.
+ * and returns the intermediate representation of the dependency file.
  *
  * @return {Object} Intermediate Representation in JSON.
  */

From e30491163370e5816a4c533165ce20d13a4a74e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 13:56:52 +0100
Subject: [PATCH 087/213] Add tests for retrieving JSDoc of destructured
 objects

---
 .../named-identifier-destructuring-ast.json   | 201 ++++++++++++
 .../named-identifier-destructuring.js         |   6 +
 .../named-identifier-destructuring.json       |  42 +++
 .../tests/fixtures/named-identifiers-ast.json | 310 +++++++++++++++++-
 .../docgen/tests/test-get-export-entries.js   |  10 +
 .../test-get-intermediate-representation.js   |  13 +
 6 files changed, 581 insertions(+), 1 deletion(-)
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-destructuring.js
 create mode 100644 packages/docgen/tests/fixtures/named-identifier-destructuring.json

diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json b/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
new file mode 100644
index 00000000000000..bc6f890a7fb83d
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
@@ -0,0 +1,201 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 141,
+	"range": [
+		35,
+		140
+	],
+	"body": [
+		{
+			"type": "VariableDeclaration",
+			"start": 35,
+			"end": 94,
+			"range": [
+				35,
+				94
+			],
+			"declarations": [
+				{
+					"type": "VariableDeclarator",
+					"start": 41,
+					"end": 93,
+					"range": [
+						41,
+						93
+					],
+					"id": {
+						"type": "ObjectPattern",
+						"start": 41,
+						"end": 60,
+						"range": [
+							41,
+							60
+						],
+						"properties": [
+							{
+								"type": "Property",
+								"start": 43,
+								"end": 58,
+								"range": [
+									43,
+									58
+								],
+								"method": false,
+								"shorthand": true,
+								"computed": false,
+								"key": {
+									"type": "Identifier",
+									"start": 43,
+									"end": 58,
+									"range": [
+										43,
+										58
+									],
+									"name": "someDeclaration"
+								},
+								"kind": "init",
+								"value": {
+									"type": "Identifier",
+									"start": 43,
+									"end": 58,
+									"range": [
+										43,
+										58
+									],
+									"name": "someDeclaration"
+								}
+							}
+						]
+					},
+					"init": {
+						"type": "ObjectExpression",
+						"start": 63,
+						"end": 93,
+						"range": [
+							63,
+							93
+						],
+						"properties": [
+							{
+								"type": "Property",
+								"start": 65,
+								"end": 91,
+								"range": [
+									65,
+									91
+								],
+								"method": false,
+								"shorthand": false,
+								"computed": false,
+								"key": {
+									"type": "Identifier",
+									"start": 65,
+									"end": 80,
+									"range": [
+										65,
+										80
+									],
+									"name": "someDeclaration"
+								},
+								"value": {
+									"type": "ArrowFunctionExpression",
+									"start": 82,
+									"end": 91,
+									"range": [
+										82,
+										91
+									],
+									"id": null,
+									"generator": false,
+									"expression": false,
+									"async": false,
+									"params": [],
+									"body": {
+										"type": "BlockStatement",
+										"start": 88,
+										"end": 91,
+										"range": [
+											88,
+											91
+										],
+										"body": []
+									}
+								},
+								"kind": "init"
+							}
+						]
+					}
+				}
+			],
+			"kind": "const",
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * My declaration example.\n ",
+					"start": 0,
+					"end": 34,
+					"range": [
+						0,
+						34
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 96,
+			"end": 140,
+			"range": [
+				96,
+				140
+			],
+			"declaration": null,
+			"specifiers": [
+				{
+					"type": "ExportSpecifier",
+					"start": 105,
+					"end": 137,
+					"range": [
+						105,
+						137
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 105,
+						"end": 120,
+						"range": [
+							105,
+							120
+						],
+						"name": "someDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 124,
+						"end": 137,
+						"range": [
+							124,
+							137
+						],
+						"name": "myDeclaration"
+					}
+				}
+			],
+			"source": null
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
+			"range": [
+				0,
+				34
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring.js b/packages/docgen/tests/fixtures/named-identifier-destructuring.js
new file mode 100644
index 00000000000000..d5e1b5d46160d9
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-destructuring.js
@@ -0,0 +1,6 @@
+/**
+ * My declaration example.
+ */
+const { someDeclaration } = { someDeclaration: () => { } };
+
+export { someDeclaration as myDeclaration };
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring.json b/packages/docgen/tests/fixtures/named-identifier-destructuring.json
new file mode 100644
index 00000000000000..b80334dcb1a568
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifier-destructuring.json
@@ -0,0 +1,42 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 96,
+	"end": 140,
+	"range": [
+		96,
+		140
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 105,
+			"end": 137,
+			"range": [
+				105,
+				137
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 105,
+				"end": 120,
+				"range": [
+					105,
+					120
+				],
+				"name": "someDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 124,
+				"end": 137,
+				"range": [
+					124,
+					137
+				],
+				"name": "myDeclaration"
+			}
+		}
+	],
+	"source": null
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ast.json b/packages/docgen/tests/fixtures/named-identifiers-ast.json
index fa4a4a5ca77768..0fa80b3d38b654 100644
--- a/packages/docgen/tests/fixtures/named-identifiers-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifiers-ast.json
@@ -1 +1,309 @@
-{"type":"Program","start":0,"end":288,"range":[41,287],"body":[{"type":"FunctionDeclaration","start":41,"end":74,"range":[41,74],"id":{"type":"Identifier","start":50,"end":69,"range":[50,69],"name":"functionDeclaration"},"generator":false,"expression":false,"async":false,"params":[],"body":{"type":"BlockStatement","start":72,"end":74,"range":[72,74],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]}],"trailingComments":[{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]}]},{"type":"ClassDeclaration","start":114,"end":139,"range":[114,139],"id":{"type":"Identifier","start":120,"end":136,"range":[120,136],"name":"ClassDeclaration"},"superClass":null,"body":{"type":"ClassBody","start":137,"end":139,"range":[137,139],"body":[]},"leadingComments":[{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]}],"trailingComments":[{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]},{"type":"VariableDeclaration","start":182,"end":215,"range":[182,215],"declarations":[{"type":"VariableDeclarator","start":188,"end":214,"range":[188,214],"id":{"type":"Identifier","start":188,"end":207,"range":[188,207],"name":"variableDeclaration"},"init":{"type":"Literal","start":210,"end":214,"range":[210,214],"value":true,"raw":"true"}}],"kind":"const","leadingComments":[{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]},{"type":"ExportNamedDeclaration","start":217,"end":287,"range":[217,287],"declaration":null,"specifiers":[{"type":"ExportSpecifier","start":226,"end":245,"range":[226,245],"local":{"type":"Identifier","start":226,"end":245,"range":[226,245],"name":"functionDeclaration"},"exported":{"type":"Identifier","start":226,"end":245,"range":[226,245],"name":"functionDeclaration"}},{"type":"ExportSpecifier","start":247,"end":266,"range":[247,266],"local":{"type":"Identifier","start":247,"end":266,"range":[247,266],"name":"variableDeclaration"},"exported":{"type":"Identifier","start":247,"end":266,"range":[247,266],"name":"variableDeclaration"}},{"type":"ExportSpecifier","start":268,"end":284,"range":[268,284],"local":{"type":"Identifier","start":268,"end":284,"range":[268,284],"name":"ClassDeclaration"},"exported":{"type":"Identifier","start":268,"end":284,"range":[268,284],"name":"ClassDeclaration"}}],"source":null}],"sourceType":"module","comments":[{"type":"Block","value":"*\n * Function declaration example.\n ","start":0,"end":40,"range":[0,40]},{"type":"Block","value":"*\n * Class declaration example.\n ","start":76,"end":113,"range":[76,113]},{"type":"Block","value":"*\n * Variable declaration example.\n ","start":141,"end":181,"range":[141,181]}]}
\ No newline at end of file
+{
+	"type": "Program",
+	"start": 0,
+	"end": 288,
+	"range": [
+		41,
+		287
+	],
+	"body": [
+		{
+			"type": "FunctionDeclaration",
+			"start": 41,
+			"end": 74,
+			"range": [
+				41,
+				74
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 50,
+				"end": 69,
+				"range": [
+					50,
+					69
+				],
+				"name": "functionDeclaration"
+			},
+			"generator": false,
+			"expression": false,
+			"async": false,
+			"params": [],
+			"body": {
+				"type": "BlockStatement",
+				"start": 72,
+				"end": 74,
+				"range": [
+					72,
+					74
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Function declaration example.\n ",
+					"start": 0,
+					"end": 40,
+					"range": [
+						0,
+						40
+					]
+				}
+			],
+			"trailingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Class declaration example.\n ",
+					"start": 76,
+					"end": 113,
+					"range": [
+						76,
+						113
+					]
+				}
+			]
+		},
+		{
+			"type": "ClassDeclaration",
+			"start": 114,
+			"end": 139,
+			"range": [
+				114,
+				139
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 120,
+				"end": 136,
+				"range": [
+					120,
+					136
+				],
+				"name": "ClassDeclaration"
+			},
+			"superClass": null,
+			"body": {
+				"type": "ClassBody",
+				"start": 137,
+				"end": 139,
+				"range": [
+					137,
+					139
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Class declaration example.\n ",
+					"start": 76,
+					"end": 113,
+					"range": [
+						76,
+						113
+					]
+				}
+			],
+			"trailingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Variable declaration example.\n ",
+					"start": 141,
+					"end": 181,
+					"range": [
+						141,
+						181
+					]
+				}
+			]
+		},
+		{
+			"type": "VariableDeclaration",
+			"start": 182,
+			"end": 215,
+			"range": [
+				182,
+				215
+			],
+			"declarations": [
+				{
+					"type": "VariableDeclarator",
+					"start": 188,
+					"end": 214,
+					"range": [
+						188,
+						214
+					],
+					"id": {
+						"type": "Identifier",
+						"start": 188,
+						"end": 207,
+						"range": [
+							188,
+							207
+						],
+						"name": "variableDeclaration"
+					},
+					"init": {
+						"type": "Literal",
+						"start": 210,
+						"end": 214,
+						"range": [
+							210,
+							214
+						],
+						"value": true,
+						"raw": "true"
+					}
+				}
+			],
+			"kind": "const",
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Variable declaration example.\n ",
+					"start": 141,
+					"end": 181,
+					"range": [
+						141,
+						181
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 217,
+			"end": 287,
+			"range": [
+				217,
+				287
+			],
+			"declaration": null,
+			"specifiers": [
+				{
+					"type": "ExportSpecifier",
+					"start": 226,
+					"end": 245,
+					"range": [
+						226,
+						245
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 226,
+						"end": 245,
+						"range": [
+							226,
+							245
+						],
+						"name": "functionDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 226,
+						"end": 245,
+						"range": [
+							226,
+							245
+						],
+						"name": "functionDeclaration"
+					}
+				},
+				{
+					"type": "ExportSpecifier",
+					"start": 247,
+					"end": 266,
+					"range": [
+						247,
+						266
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 247,
+						"end": 266,
+						"range": [
+							247,
+							266
+						],
+						"name": "variableDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 247,
+						"end": 266,
+						"range": [
+							247,
+							266
+						],
+						"name": "variableDeclaration"
+					}
+				},
+				{
+					"type": "ExportSpecifier",
+					"start": 268,
+					"end": 284,
+					"range": [
+						268,
+						284
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 268,
+						"end": 284,
+						"range": [
+							268,
+							284
+						],
+						"name": "ClassDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 268,
+						"end": 284,
+						"range": [
+							268,
+							284
+						],
+						"name": "ClassDeclaration"
+					}
+				}
+			],
+			"source": null
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		},
+		{
+			"type": "Block",
+			"value": "*\n * Class declaration example.\n ",
+			"start": 76,
+			"end": 113,
+			"range": [
+				76,
+				113
+			]
+		},
+		{
+			"type": "Block",
+			"value": "*\n * Variable declaration example.\n ",
+			"start": 141,
+			"end": 181,
+			"range": [
+				141,
+				181
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 5905ac38f2f529..334667c923f8b2 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -213,6 +213,16 @@ test( 'Export entries - named identifier', function( t ) {
 		exportName: 'myDeclaration',
 		module: null,
 	} ] );
+	const tokenObject = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
+		'utf-8'
+	);
+	const nameObject = getExportEntries( JSON.parse( tokenObject ) );
+	t.deepEqual( nameObject, [ {
+		localName: 'someDeclaration',
+		exportName: 'myDeclaration',
+		module: null,
+	} ] );
 	t.end();
 } );
 
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 7444b93b44a95c..a26bfbf1742e97 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -193,6 +193,19 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 		description: 'My declaration example.',
 		tags: [] },
 	] );
+	const tokenObject = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
+		'utf-8'
+	);
+	const astObject = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifier-destructuring-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
+		name: 'myDeclaration',
+		description: 'My declaration example.',
+		tags: [] },
+	] );
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'

From c72c15451d5aa6a73fa89a1171d36bc6d3cb6dd7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 13:57:59 +0100
Subject: [PATCH 088/213] Add support for JSDoc lookup of destructured objects

---
 .../src/get-intermediate-representation.js    | 47 +++++++++++++------
 1 file changed, 32 insertions(+), 15 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 52010d301325b7..08c984f0788444 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -24,7 +24,14 @@ const hasFunctionWithName = ( node, name ) =>
 
 const hasVariableWithName = ( node, name ) =>
 	node.type === 'VariableDeclaration' &&
-	node.declarations.some( ( declaration ) => declaration.id.name === name );
+	node.declarations.some( ( declaration ) => {
+		if ( declaration.id.type === 'ObjectPattern' ) {
+			return declaration.id.properties.some(
+				( property ) => property.key.name === name
+			);
+		}
+		return declaration.id.name === name;
+	} );
 
 const hasNamedExportWithName = ( node, name ) =>
 	node.type === 'ExportNamedDeclaration' &&
@@ -45,8 +52,14 @@ const someImportMatchesName = ( name, node ) => node.specifiers.some( ( specifie
 } );
 
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
+	// Use JSDoc in node if present
 	let doc = getJSDocFromToken( token );
-	if ( doc === undefined && entry && entry.module === null ) {
+	if ( doc !== undefined ) {
+		return doc;
+	}
+
+	// Look up JSDoc in same file
+	if ( entry && entry.module === null ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return hasClassWithName( node, entry.localName ) ||
 				hasFunctionWithName( node, entry.localName ) ||
@@ -54,22 +67,26 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 				hasNamedExportWithName( node, entry.localName ) ||
 				hasImportWithName( node, entry.localName );
 		} );
-		if ( candidates.length === 1 ) {
-			const node = candidates[ 0 ];
-			if ( isImportDeclaration( node ) ) {
-				const ir = parseDependency( getDependencyPath( node ) );
-				doc = ir.find( ( { name } ) => someImportMatchesName( name, node ) );
-			} else {
-				doc = getJSDocFromToken( node );
-			}
+		if ( candidates.length !== 1 ) {
+			return doc;
 		}
-	} else if ( doc === undefined && entry && entry.module !== null ) {
-		const ir = parseDependency( getDependencyPath( token ) );
-		if ( entry.localName === NAMESPACE_EXPORT ) {
-			doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
+		const node = candidates[ 0 ];
+		if ( isImportDeclaration( node ) ) {
+			// Actually, look up JSDoc in file dependency
+			const ir = parseDependency( getDependencyPath( node ) );
+			doc = ir.find( ( { name } ) => someImportMatchesName( name, node ) );
 		} else {
-			doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+			doc = getJSDocFromToken( node );
 		}
+		return doc;
+	}
+
+	// Look up JSDoc in file dependency
+	const ir = parseDependency( getDependencyPath( token ) );
+	if ( entry.localName === NAMESPACE_EXPORT ) {
+		doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
+	} else {
+		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
 	}
 	return doc;
 };

From bfc9a3b90c6593f992f6362b5d9b22bea0e2a18b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 14:04:29 +0100
Subject: [PATCH 089/213] Adapt tests to new engine API

---
 packages/docgen/tests/test-engine.js | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 6504f0fbebfeed..557d89a0db3a1f 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -139,13 +139,14 @@ test( 'Engine - named export (multiple identifiers) using JSDoc from declaration
 } );
 
 test( 'Engine - named export (single identifier) using JSDoc from dependency', ( t ) => {
-	const getDependency = () => `/**
+	const dependency = `/**
  		 * My declaration example.
  		 */
 		export const myDeclaration = function() {
 			// do nothing
 		}
 	`;
+	const getDependency = () => engine( dependency ).ir;
 	const { ir } = engine(
 		`export { myDeclaration } from './my-dependency';`,
 		getDependency

From c3bb4e9ebf91a7af04b5cf59a12ca64e76ea8ac8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 18:16:37 +0100
Subject: [PATCH 090/213] Fix JSDoc lookup for named export

---
 .../src/get-intermediate-representation.js    |   8 +-
 .../named-identifiers-and-inline-ast.json     | 291 ++++++++++++++++++
 .../fixtures/named-identifiers-and-inline.js  |  17 +
 .../named-identifiers-and-inline.json         | 150 +++++++++
 .../docgen/tests/test-get-export-entries.js   |  13 +
 .../test-get-intermediate-representation.js   |  15 +
 6 files changed, 491 insertions(+), 3 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
 create mode 100644 packages/docgen/tests/fixtures/named-identifiers-and-inline.js
 create mode 100644 packages/docgen/tests/fixtures/named-identifiers-and-inline.json

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 08c984f0788444..07e2f3054c5880 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -34,9 +34,11 @@ const hasVariableWithName = ( node, name ) =>
 	} );
 
 const hasNamedExportWithName = ( node, name ) =>
-	node.type === 'ExportNamedDeclaration' &&
-	node.declaration &&
-	node.declaration.id.name === name;
+	node.type === 'ExportNamedDeclaration' && (
+		( node.declaration && hasClassWithName( node.declaration, name ) ) ||
+		( node.declaration && hasFunctionWithName( node.declaration, name ) ) ||
+		( node.declaration && hasVariableWithName( node.declaration, name ) )
+	);
 
 const hasImportWithName = ( node, name ) =>
 	node.type === 'ImportDeclaration' &&
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json b/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
new file mode 100644
index 00000000000000..3af45ee2d999a1
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
@@ -0,0 +1,291 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 275,
+	"range": [
+		41,
+		273
+	],
+	"body": [
+		{
+			"type": "FunctionDeclaration",
+			"start": 41,
+			"end": 74,
+			"range": [
+				41,
+				74
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 50,
+				"end": 69,
+				"range": [
+					50,
+					69
+				],
+				"name": "functionDeclaration"
+			},
+			"generator": false,
+			"expression": false,
+			"async": false,
+			"params": [],
+			"body": {
+				"type": "BlockStatement",
+				"start": 72,
+				"end": 74,
+				"range": [
+					72,
+					74
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Function declaration example.\n ",
+					"start": 0,
+					"end": 40,
+					"range": [
+						0,
+						40
+					]
+				}
+			],
+			"trailingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Class declaration example.\n ",
+					"start": 76,
+					"end": 113,
+					"range": [
+						76,
+						113
+					]
+				}
+			]
+		},
+		{
+			"type": "ClassDeclaration",
+			"start": 114,
+			"end": 139,
+			"range": [
+				114,
+				139
+			],
+			"id": {
+				"type": "Identifier",
+				"start": 120,
+				"end": 136,
+				"range": [
+					120,
+					136
+				],
+				"name": "ClassDeclaration"
+			},
+			"superClass": null,
+			"body": {
+				"type": "ClassBody",
+				"start": 137,
+				"end": 139,
+				"range": [
+					137,
+					139
+				],
+				"body": []
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Class declaration example.\n ",
+					"start": 76,
+					"end": 113,
+					"range": [
+						76,
+						113
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 141,
+			"end": 190,
+			"range": [
+				141,
+				190
+			],
+			"declaration": null,
+			"specifiers": [
+				{
+					"type": "ExportSpecifier",
+					"start": 150,
+					"end": 169,
+					"range": [
+						150,
+						169
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 150,
+						"end": 169,
+						"range": [
+							150,
+							169
+						],
+						"name": "functionDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 150,
+						"end": 169,
+						"range": [
+							150,
+							169
+						],
+						"name": "functionDeclaration"
+					}
+				},
+				{
+					"type": "ExportSpecifier",
+					"start": 171,
+					"end": 187,
+					"range": [
+						171,
+						187
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 171,
+						"end": 187,
+						"range": [
+							171,
+							187
+						],
+						"name": "ClassDeclaration"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 171,
+						"end": 187,
+						"range": [
+							171,
+							187
+						],
+						"name": "ClassDeclaration"
+					}
+				}
+			],
+			"source": null,
+			"trailingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Variable declaration example.\n ",
+					"start": 192,
+					"end": 232,
+					"range": [
+						192,
+						232
+					]
+				}
+			]
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 233,
+			"end": 273,
+			"range": [
+				233,
+				273
+			],
+			"declaration": {
+				"type": "VariableDeclaration",
+				"start": 240,
+				"end": 273,
+				"range": [
+					240,
+					273
+				],
+				"declarations": [
+					{
+						"type": "VariableDeclarator",
+						"start": 246,
+						"end": 272,
+						"range": [
+							246,
+							272
+						],
+						"id": {
+							"type": "Identifier",
+							"start": 246,
+							"end": 265,
+							"range": [
+								246,
+								265
+							],
+							"name": "variableDeclaration"
+						},
+						"init": {
+							"type": "Literal",
+							"start": 268,
+							"end": 272,
+							"range": [
+								268,
+								272
+							],
+							"value": true,
+							"raw": "true"
+						}
+					}
+				],
+				"kind": "const"
+			},
+			"specifiers": [],
+			"source": null,
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Variable declaration example.\n ",
+					"start": 192,
+					"end": 232,
+					"range": [
+						192,
+						232
+					]
+				}
+			]
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		},
+		{
+			"type": "Block",
+			"value": "*\n * Class declaration example.\n ",
+			"start": 76,
+			"end": 113,
+			"range": [
+				76,
+				113
+			]
+		},
+		{
+			"type": "Block",
+			"value": "*\n * Variable declaration example.\n ",
+			"start": 192,
+			"end": 232,
+			"range": [
+				192,
+				232
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline.js b/packages/docgen/tests/fixtures/named-identifiers-and-inline.js
new file mode 100644
index 00000000000000..10b836d597856f
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifiers-and-inline.js
@@ -0,0 +1,17 @@
+/**
+ * Function declaration example.
+ */
+function functionDeclaration() {}
+
+/**
+ * Class declaration example.
+ */
+class ClassDeclaration {}
+
+export { functionDeclaration, ClassDeclaration };
+
+/**
+ * Variable declaration example.
+ */
+export const variableDeclaration = true;
+
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline.json b/packages/docgen/tests/fixtures/named-identifiers-and-inline.json
new file mode 100644
index 00000000000000..01addf4b90b0f0
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifiers-and-inline.json
@@ -0,0 +1,150 @@
+[
+	{
+		"type": "ExportNamedDeclaration",
+		"start": 141,
+		"end": 190,
+		"range": [
+			141,
+			190
+		],
+		"declaration": null,
+		"specifiers": [
+			{
+				"type": "ExportSpecifier",
+				"start": 150,
+				"end": 169,
+				"range": [
+					150,
+					169
+				],
+				"local": {
+					"type": "Identifier",
+					"start": 150,
+					"end": 169,
+					"range": [
+						150,
+						169
+					],
+					"name": "functionDeclaration"
+				},
+				"exported": {
+					"type": "Identifier",
+					"start": 150,
+					"end": 169,
+					"range": [
+						150,
+						169
+					],
+					"name": "functionDeclaration"
+				}
+			},
+			{
+				"type": "ExportSpecifier",
+				"start": 171,
+				"end": 187,
+				"range": [
+					171,
+					187
+				],
+				"local": {
+					"type": "Identifier",
+					"start": 171,
+					"end": 187,
+					"range": [
+						171,
+						187
+					],
+					"name": "ClassDeclaration"
+				},
+				"exported": {
+					"type": "Identifier",
+					"start": 171,
+					"end": 187,
+					"range": [
+						171,
+						187
+					],
+					"name": "ClassDeclaration"
+				}
+			}
+		],
+		"source": null,
+		"trailingComments": [
+			{
+				"type": "Block",
+				"value": "*\n * Variable declaration example.\n ",
+				"start": 192,
+				"end": 232,
+				"range": [
+					192,
+					232
+				]
+			}
+		]
+	},
+	{
+		"type": "ExportNamedDeclaration",
+		"start": 233,
+		"end": 273,
+		"range": [
+			233,
+			273
+		],
+		"declaration": {
+			"type": "VariableDeclaration",
+			"start": 240,
+			"end": 273,
+			"range": [
+				240,
+				273
+			],
+			"declarations": [
+				{
+					"type": "VariableDeclarator",
+					"start": 246,
+					"end": 272,
+					"range": [
+						246,
+						272
+					],
+					"id": {
+						"type": "Identifier",
+						"start": 246,
+						"end": 265,
+						"range": [
+							246,
+							265
+						],
+						"name": "variableDeclaration"
+					},
+					"init": {
+						"type": "Literal",
+						"start": 268,
+						"end": 272,
+						"range": [
+							268,
+							272
+						],
+						"value": true,
+						"raw": "true"
+					}
+				}
+			],
+			"kind": "const"
+		},
+		"specifiers": [],
+		"source": null,
+		"leadingComments": [
+			{
+				"type": "Block",
+				"value": "*\n * Variable declaration example.\n ",
+				"start": 192,
+				"end": 232,
+				"range": [
+					192,
+					232
+				]
+			}
+		]
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 334667c923f8b2..85bfc8f5b744e1 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -237,6 +237,19 @@ test( 'Export entries - named identifiers', function( t ) {
 		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
 		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null },
 	] );
+	const tokenIdentifiersAndInline = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
+		'utf-8'
+	);
+	const name0 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 0 ] );
+	t.deepEqual( name0, [
+		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null },
+		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null },
+	] );
+	const name1 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 1 ] );
+	t.deepEqual( name1, [
+		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
+	] );
 	t.end();
 } );
 
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index a26bfbf1742e97..47e31e0f7e96b6 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -219,6 +219,21 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
 		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
 	] );
+	const foo = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
+		'utf-8'
+	);
+	const bar = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-identifiers-and-inline-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+	] );
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+	] );
 	t.end();
 } );
 

From 3826642f1a700d4edf472ad467cd715c5a181a8a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 18:30:47 +0100
Subject: [PATCH 091/213] Update coverage

---
 packages/docgen/coverage.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 9bb73000ac92bb..06658bd18960fe 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -15,16 +15,12 @@ CJS modules:
 
 ES6 modules:
 
-- [ ] block-serialization-spec-parser - not `src/index.js`
-- [ ] blocks - directory dependency
-- [ ] components - directory dependency
-- [ ] data - directory dependency
+- [ ] components - directory dependency, BUG
+- [ ] data - directory dependency, BUG
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
-- [ ] edit-post - directory dependency
-- [ ] editor - directory dependency
+- [ ] editor - directory dependency, BUG
 - [ ] npm-package-json-lint-config - CONFIG file
-- [ ] plugins - directory dependency
 - [ ] scripts - what shall be documented? not `src/index`
 - [-] keycodes - how to document CONSTANTS?
 - [-] redux-routine - check description with many paragraphs
@@ -36,12 +32,15 @@ ES6 modules:
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
+- [x] block-serialization-spec-parser - not `src/index.js`
+- [x] blocks - directory dependency
 - [x] compose - directory dependency
 - [x] core-data - export nothing
 - [x] date
 - [x] deprecated
 - [x] dom
 - [x] dom-ready
+- [x] edit-post - directory dependency
 - [x] element
 - [x] escape-html
 - [x] format-library - exports nothing
@@ -53,6 +52,7 @@ ES6 modules:
 - [x] list-reusable-blocks - export nothing
 - [x] notices - does not export anything
 - [x] nux - directory dependency
+- [x] plugins
 - [x] priority-queue
 - [x] rich-text
 - [x] shortcode

From a592ad7888c846ca952c616f9581031c8e7d1b91 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 18:37:00 +0100
Subject: [PATCH 092/213] Remove docgen from package.json

---
 package.json | 2 --
 1 file changed, 2 deletions(-)

diff --git a/package.json b/package.json
index f66a86d2fc0b00..eb1b308d87f2a1 100644
--- a/package.json
+++ b/package.json
@@ -66,7 +66,6 @@
 		"@wordpress/babel-preset-default": "file:packages/babel-preset-default",
 		"@wordpress/browserslist-config": "file:packages/browserslist-config",
 		"@wordpress/custom-templated-path-webpack-plugin": "file:packages/custom-templated-path-webpack-plugin",
-		"@wordpress/docgen": "file:packages/docgen",
 		"@wordpress/e2e-test-utils": "file:packages/e2e-test-utils",
 		"@wordpress/e2e-tests": "file:packages/e2e-tests",
 		"@wordpress/eslint-plugin": "file:packages/eslint-plugin",
@@ -162,7 +161,6 @@
 		"dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"",
 		"dev:packages": "node ./bin/packages/watch.js",
 		"docs:build": "node docs/tool",
-		"docs:api": "docgen",
 		"fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"",
 		"fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json",
 		"fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit",

From 12acf303f444c6bd9bc49d1f5506f97794497d58 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 23 Jan 2019 18:38:38 +0100
Subject: [PATCH 093/213] Better README

---
 packages/docgen/README.md | 10 +---------
 1 file changed, 1 insertion(+), 9 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index ac08fc04e67a17..aab4fbb79987a7 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -1,11 +1,3 @@
 # `docgen`
 
-> TODO: description
-
-## Usage
-
-```
-const docgen = require('docgen');
-
-// TODO: DEMONSTRATE API
-```
+Autogenerate public API documentation from exports and JSDoc comments.

From 34fc21180c8b111027adb497eb49266d6d4a9eae Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 10:36:21 +0100
Subject: [PATCH 094/213] Update coverage

---
 packages/docgen/coverage.md | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 06658bd18960fe..eb29fc33fd8b2a 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -2,16 +2,16 @@
 
 CJS modules:
 
-- [ ] babel-plugin-makepot - NODE EXPORT
-- [ ] babel-preset-default - NODE EXPORT, not `src/index.js`
-- [ ] browserslist-config - NODE, not `src/index.js`
-- [ ] custom-templated-path-webpack-plugin - NODE EXPORT
-- [ ] docgen - NODE EXPORT, not `src/index.js`
-- [ ] eslint-plugin - NODE EXPORT
-- [ ] is-shallow-equal - NODE EXPORT
-- [ ] jest-preset-default - NODE EXPORT, not `src/index.js`
-- [ ] postcss-themes - NODE export
-- [ ] library-export-default-webpack-plugin - NODE EXPORT
+- [ ] babel-plugin-makepot
+- [ ] babel-preset-default
+- [ ] browserslist-config
+- [ ] custom-templated-path-webpack-plugin
+- [ ] docgen
+- [ ] eslint-plugin
+- [ ] is-shallow-equal
+- [ ] jest-preset-default
+- [ ] library-export-default-webpack-plugin
+- [ ] postcss-themes
 
 ES6 modules:
 
@@ -21,7 +21,7 @@ ES6 modules:
 - [ ] e2e-tests - what shall be documented?
 - [ ] editor - directory dependency, BUG
 - [ ] npm-package-json-lint-config - CONFIG file
-- [ ] scripts - what shall be documented? not `src/index`
+- [ ] scripts - what shall be documented?
 - [-] keycodes - how to document CONSTANTS?
 - [-] redux-routine - check description with many paragraphs
 - [x] a11y
@@ -32,7 +32,7 @@ ES6 modules:
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
-- [x] block-serialization-spec-parser - not `src/index.js`
+- [x] block-serialization-spec-parser
 - [x] blocks - directory dependency
 - [x] compose - directory dependency
 - [x] core-data - export nothing

From 26c51caa697244446f3af8f0635072eed0aaf8f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:00:54 +0100
Subject: [PATCH 095/213] Ignore comments in namespace exports

---
 .../src/get-intermediate-representation.js    | 13 ++++----
 .../tests/fixtures/namespace-commented.js     |  4 +++
 .../tests/fixtures/namespace-commented.json   | 32 +++++++++++++++++++
 .../test-get-intermediate-representation.js   | 12 +++++++
 4 files changed, 55 insertions(+), 6 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/namespace-commented.js
 create mode 100644 packages/docgen/tests/fixtures/namespace-commented.json

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 07e2f3054c5880..77877bb74b342d 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -54,10 +54,12 @@ const someImportMatchesName = ( name, node ) => node.specifiers.some( ( specifie
 } );
 
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
-	// Use JSDoc in node if present
-	let doc = getJSDocFromToken( token );
-	if ( doc !== undefined ) {
-		return doc;
+	let doc;
+	if ( entry.localName !== NAMESPACE_EXPORT ) {
+		doc = getJSDocFromToken( token );
+		if ( ( doc !== undefined ) ) {
+			return doc;
+		}
 	}
 
 	// Look up JSDoc in same file
@@ -111,8 +113,8 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 	const exportEntries = getExportEntries( token );
 	const ir = [];
 	exportEntries.forEach( ( entry ) => {
+		const doc = getJSDoc( token, entry, ast, parseDependency );
 		if ( entry.localName === NAMESPACE_EXPORT ) {
-			const doc = getJSDoc( token, entry, ast, parseDependency );
 			doc.forEach( ( namedExport ) => {
 				ir.push( {
 					name: namedExport.name,
@@ -121,7 +123,6 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 				} );
 			} );
 		} else {
-			const doc = getJSDoc( token, entry, ast, parseDependency );
 			ir.push( {
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
diff --git a/packages/docgen/tests/fixtures/namespace-commented.js b/packages/docgen/tests/fixtures/namespace-commented.js
new file mode 100644
index 00000000000000..5008b26d090aa5
--- /dev/null
+++ b/packages/docgen/tests/fixtures/namespace-commented.js
@@ -0,0 +1,4 @@
+/**
+ * This comment should be ignored.
+ */
+export * from './namespace-module';
diff --git a/packages/docgen/tests/fixtures/namespace-commented.json b/packages/docgen/tests/fixtures/namespace-commented.json
new file mode 100644
index 00000000000000..0448308fd91a41
--- /dev/null
+++ b/packages/docgen/tests/fixtures/namespace-commented.json
@@ -0,0 +1,32 @@
+{
+	"type": "ExportAllDeclaration",
+	"start": 43,
+	"end": 78,
+	"range": [
+		43,
+		78
+	],
+	"source": {
+		"type": "Literal",
+		"start": 57,
+		"end": 77,
+		"range": [
+			57,
+			77
+		],
+		"value": "./namespace-module",
+		"raw": "'./namespace-module'"
+	},
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * This comment should be ignored.\n ",
+			"start": 0,
+			"end": 42,
+			"range": [
+				0,
+				42
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 47e31e0f7e96b6..a8941d55f884ef 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -278,5 +278,17 @@ test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
 			{ name: 'MyClass', description: 'Named class.', tags: [] },
 		]
 	);
+	const tokenCommented = fs.readFileSync(
+		path.join( __dirname, './fixtures/namespace-commented.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
+		[
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [] },
+		]
+	);
 	t.end();
 } );

From 9d4cc08c821e30abd0d643bc8fa487648e73dbcd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:02:00 +0100
Subject: [PATCH 096/213] Update coverage

---
 packages/docgen/coverage.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index eb29fc33fd8b2a..1fc0f8f747fa4f 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -15,11 +15,10 @@ CJS modules:
 
 ES6 modules:
 
-- [ ] components - directory dependency, BUG
-- [ ] data - directory dependency, BUG
+- [ ] data - BUG
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
-- [ ] editor - directory dependency, BUG
+- [ ] editor - BUG
 - [ ] npm-package-json-lint-config - CONFIG file
 - [ ] scripts - what shall be documented?
 - [-] keycodes - how to document CONSTANTS?
@@ -34,6 +33,7 @@ ES6 modules:
 - [x] block-serialization-default-parser
 - [x] block-serialization-spec-parser
 - [x] blocks - directory dependency
+- [x] components
 - [x] compose - directory dependency
 - [x] core-data - export nothing
 - [x] date

From c632bec85bd9539b084605aca5ff3de25ef391b4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:13:45 +0100
Subject: [PATCH 097/213] CLI generates output by adding suffixes to input

---
 packages/docgen/src/cli.js | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 298d19f971121f..e57a3ef391a19b 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -78,11 +78,14 @@ const currentFileStack = []; // To keep track of file being processed.
 const result = processFile( initialInputFile );
 
 // Ouput
-const inputDirectory = path.dirname( initialInputFile );
-const doc = path.join( inputDirectory, 'api.md' );
-const ir = path.join( inputDirectory, 'ir.json' );
-const tokens = path.join( inputDirectory, 'tokens.json' );
-const ast = path.join( inputDirectory, 'ast.json' );
+const inputBase = path.join(
+	path.dirname( initialInputFile ),
+	path.basename( initialInputFile, path.extname( initialInputFile ) )
+);
+const doc = inputBase + '-api.md';
+const ir = inputBase + '-ir.json';
+const tokens = inputBase + '-exports.json';
+const ast = inputBase + '-ast.json';
 
 if ( result === undefined ) {
 	process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' );

From 002f204fa70ba9b87942dabb884989efca60008e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:26:20 +0100
Subject: [PATCH 098/213] Add test for export imported namespaces

---
 .../tests/fixtures/named-import-namespace.js  |  3 ++
 .../fixtures/named-import-namespace.json      | 42 +++++++++++++++++++
 .../docgen/tests/test-get-export-entries.js   | 12 ++++++
 3 files changed, 57 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace.js
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace.json

diff --git a/packages/docgen/tests/fixtures/named-import-namespace.js b/packages/docgen/tests/fixtures/named-import-namespace.js
new file mode 100644
index 00000000000000..1105e523d639e7
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace.js
@@ -0,0 +1,3 @@
+import * as variables from './named-variables';
+
+export { variables };
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.json b/packages/docgen/tests/fixtures/named-import-namespace.json
new file mode 100644
index 00000000000000..cae097bff1f3a4
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace.json
@@ -0,0 +1,42 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 49,
+	"end": 70,
+	"range": [
+		49,
+		70
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 58,
+			"end": 67,
+			"range": [
+				58,
+				67
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 58,
+				"end": 67,
+				"range": [
+					58,
+					67
+				],
+				"name": "variables"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 58,
+				"end": 67,
+				"range": [
+					58,
+					67
+				],
+				"name": "variables"
+			}
+		}
+	],
+	"source": null
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index 85bfc8f5b744e1..cf00049d6a018c 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -253,6 +253,18 @@ test( 'Export entries - named identifiers', function( t ) {
 	t.end();
 } );
 
+test( 'Export entries - named import namespace', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-namespace.json' ),
+		'utf-8'
+	);
+	const name = getExportEntries( JSON.parse( token ) );
+	t.deepEqual( name, [
+		{ localName: 'variables', exportName: 'variables', module: null },
+	] );
+	t.end();
+} );
+
 test( 'Export entries - named variable', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-variable.json' ),

From 15a753f5a9d6edeb9f4fedac3b65c154dc340623 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:42:15 +0100
Subject: [PATCH 099/213] Add test for export imported namespaces

---
 .../tests/test-get-intermediate-representation.js    | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index a8941d55f884ef..d09ecd80091da2 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -258,6 +258,18 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
 		[ { name: 'moduleName', description: 'Module declaration.', tags: [] } ]
 	);
+	const tokenImportNamespace = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-namespace.json' ),
+		'utf-8'
+	);
+	const getModuleImportNamespace = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/named-variables.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), { body: [] }, getModuleImportNamespace ),
+		[ { name: 'variables', description: 'Undocumented declaration.', tags: [] } ]
+	);
 	t.end();
 } );
 

From 5768a6f56cd8753a8239dd788c326c85455d85bf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:48:53 +0100
Subject: [PATCH 100/213] Add named-import-namespace AST

---
 .../fixtures/named-import-namespace-ast.json  | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace-ast.json

diff --git a/packages/docgen/tests/fixtures/named-import-namespace-ast.json b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
new file mode 100644
index 00000000000000..7e197ddd20144a
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
@@ -0,0 +1,96 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 71,
+	"range": [
+		0,
+		70
+	],
+	"body": [
+		{
+			"type": "ImportDeclaration",
+			"start": 0,
+			"end": 47,
+			"range": [
+				0,
+				47
+			],
+			"specifiers": [
+				{
+					"type": "ImportNamespaceSpecifier",
+					"start": 7,
+					"end": 21,
+					"range": [
+						7,
+						21
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 12,
+						"end": 21,
+						"range": [
+							12,
+							21
+						],
+						"name": "variables"
+					}
+				}
+			],
+			"source": {
+				"type": "Literal",
+				"start": 27,
+				"end": 46,
+				"range": [
+					27,
+					46
+				],
+				"value": "./named-variables",
+				"raw": "'./named-variables'"
+			}
+		},
+		{
+			"type": "ExportNamedDeclaration",
+			"start": 49,
+			"end": 70,
+			"range": [
+				49,
+				70
+			],
+			"declaration": null,
+			"specifiers": [
+				{
+					"type": "ExportSpecifier",
+					"start": 58,
+					"end": 67,
+					"range": [
+						58,
+						67
+					],
+					"local": {
+						"type": "Identifier",
+						"start": 58,
+						"end": 67,
+						"range": [
+							58,
+							67
+						],
+						"name": "variables"
+					},
+					"exported": {
+						"type": "Identifier",
+						"start": 58,
+						"end": 67,
+						"range": [
+							58,
+							67
+						],
+						"name": "variables"
+					}
+				}
+			],
+			"source": null
+		}
+	],
+	"sourceType": "module",
+	"comments": []
+}
\ No newline at end of file

From 10d0a0badfd6dbd91b8c5039f1a0e44b7ad2b62b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 11:59:15 +0100
Subject: [PATCH 101/213] Extract method

---
 .../src/get-intermediate-representation.js    | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 77877bb74b342d..cafdcc12fe0ab9 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -53,6 +53,17 @@ const someImportMatchesName = ( name, node ) => node.specifiers.some( ( specifie
 	return name === specifier.imported.name;
 } );
 
+const getJSDocFromDependency = ( token, entry, parseDependency ) => {
+	let doc;
+	const ir = parseDependency( getDependencyPath( token ) );
+	if ( entry.localName === NAMESPACE_EXPORT ) {
+		doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
+	} else {
+		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+	}
+	return doc;
+};
+
 const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	let doc;
 	if ( entry.localName !== NAMESPACE_EXPORT ) {
@@ -85,14 +96,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		return doc;
 	}
 
-	// Look up JSDoc in file dependency
-	const ir = parseDependency( getDependencyPath( token ) );
-	if ( entry.localName === NAMESPACE_EXPORT ) {
-		doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
-	} else {
-		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
-	}
-	return doc;
+	return getJSDocFromDependency( token, entry, parseDependency );
 };
 
 /**

From e2ef4b0c3cc85544a4151b52326454faa9d7ea89 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 12:38:25 +0100
Subject: [PATCH 102/213] IR - add breaking test

---
 .../tests/fixtures/named-function-ir.json     |  7 +++
 .../tests/fixtures/named-import-named.js      |  1 +
 .../tests/fixtures/named-import-named.json    | 52 +++++++++++++++++++
 .../test-get-intermediate-representation.js   | 12 +++++
 4 files changed, 72 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/named-function-ir.json
 create mode 100644 packages/docgen/tests/fixtures/named-import-named.js
 create mode 100644 packages/docgen/tests/fixtures/named-import-named.json

diff --git a/packages/docgen/tests/fixtures/named-function-ir.json b/packages/docgen/tests/fixtures/named-function-ir.json
new file mode 100644
index 00000000000000..a9d9ab4175c9c5
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-function-ir.json
@@ -0,0 +1,7 @@
+[
+	{
+		"name": "myDeclaration",
+		"description": "My declaration example.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-import-named.js b/packages/docgen/tests/fixtures/named-import-named.js
new file mode 100644
index 00000000000000..e04aa137083124
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-named.js
@@ -0,0 +1 @@
+export { myDeclaration } from './named-function';
diff --git a/packages/docgen/tests/fixtures/named-import-named.json b/packages/docgen/tests/fixtures/named-import-named.json
new file mode 100644
index 00000000000000..da3c4029553368
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-named.json
@@ -0,0 +1,52 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 0,
+	"end": 49,
+	"range": [
+		0,
+		49
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 9,
+			"end": 22,
+			"range": [
+				9,
+				22
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 22,
+				"range": [
+					9,
+					22
+				],
+				"name": "myDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 22,
+				"range": [
+					9,
+					22
+				],
+				"name": "myDeclaration"
+			}
+		}
+	],
+	"source": {
+		"type": "Literal",
+		"start": 30,
+		"end": 48,
+		"range": [
+			30,
+			48
+		],
+		"value": "./named-function",
+		"raw": "'./named-function'"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index d09ecd80091da2..1b3e6eada1e200 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -250,6 +250,18 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
 		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
 	);
+	const tokenImportNamed = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-named.json' ),
+		'utf-8'
+	);
+	const getModuleImportNamed = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/named-function-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
+		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
+	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),
 		'utf-8'

From 8ff0e4577d4a425777bc4eecd5ed8d2df289a47b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 12:56:30 +0100
Subject: [PATCH 103/213] Fix bug on export redirection

---
 .../docgen/src/get-intermediate-representation.js   | 13 ++++++-------
 .../tests/fixtures/named-default-module-ir.json     |  8 +++++++-
 .../tests/test-get-intermediate-representation.js   |  2 +-
 3 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index cafdcc12fe0ab9..5b67716b8733c0 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -46,9 +46,11 @@ const hasImportWithName = ( node, name ) =>
 
 const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
 
-const someImportMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
+const someSpecifierMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
 	if ( specifier.type === 'ImportDefaultSpecifier' ) {
 		return name === 'default';
+	} else if ( specifier.type === 'ExportSpecifier' ) {
+		return name === specifier.local.name;
 	}
 	return name === specifier.imported.name;
 } );
@@ -57,9 +59,9 @@ const getJSDocFromDependency = ( token, entry, parseDependency ) => {
 	let doc;
 	const ir = parseDependency( getDependencyPath( token ) );
 	if ( entry.localName === NAMESPACE_EXPORT ) {
-		doc = ir.filter( ( exportDeclaration ) => exportDeclaration.name !== DEFAULT_EXPORT );
+		doc = ir.filter( ( { name } ) => name !== DEFAULT_EXPORT );
 	} else {
-		doc = ir.find( ( exportDeclaration ) => exportDeclaration.name === entry.localName );
+		doc = ir.find( ( { name } ) => someSpecifierMatchesName( name, token ) );
 	}
 	return doc;
 };
@@ -73,7 +75,6 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		}
 	}
 
-	// Look up JSDoc in same file
 	if ( entry && entry.module === null ) {
 		const candidates = ast.body.filter( ( node ) => {
 			return hasClassWithName( node, entry.localName ) ||
@@ -87,9 +88,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 		}
 		const node = candidates[ 0 ];
 		if ( isImportDeclaration( node ) ) {
-			// Actually, look up JSDoc in file dependency
-			const ir = parseDependency( getDependencyPath( node ) );
-			doc = ir.find( ( { name } ) => someImportMatchesName( name, node ) );
+			doc = getJSDocFromDependency( node, entry, parseDependency );
 		} else {
 			doc = getJSDocFromToken( node );
 		}
diff --git a/packages/docgen/tests/fixtures/named-default-module-ir.json b/packages/docgen/tests/fixtures/named-default-module-ir.json
index 9807991c06ccc9..a4d2e308dd7006 100644
--- a/packages/docgen/tests/fixtures/named-default-module-ir.json
+++ b/packages/docgen/tests/fixtures/named-default-module-ir.json
@@ -1 +1,7 @@
-[{"name":"default","description":"Module declaration.","tags":[]}]
\ No newline at end of file
+[
+	{
+		"name": "default",
+		"description": "Module declaration.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 1b3e6eada1e200..0578bc4728c412 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -260,7 +260,7 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
-		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),

From 2ac38a60b84d413619486baccf49c99afeedad3e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 13:59:56 +0100
Subject: [PATCH 104/213] Add support for import namespace

---
 .../src/get-intermediate-representation.js    |  5 +-
 .../fixtures/default-function-named-ast.json  | 78 +++++++++++++++++++
 .../fixtures/default-function-named-ir.json   |  7 ++
 .../fixtures/named-import-namespace-ast.json  | 48 ++++++------
 .../named-import-namespace-module-ir.json     |  1 +
 .../fixtures/named-import-namespace-module.js |  1 +
 .../named-import-namespace-module.json        | 52 +++++++++++++
 .../tests/fixtures/named-import-namespace.js  |  2 +-
 .../fixtures/named-import-namespace.json      | 32 ++++----
 .../test-get-intermediate-representation.js   | 22 ++++--
 10 files changed, 201 insertions(+), 47 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/default-function-named-ast.json
 create mode 100644 packages/docgen/tests/fixtures/default-function-named-ir.json
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace-module-ir.json
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace-module.js
 create mode 100644 packages/docgen/tests/fixtures/named-import-namespace-module.json

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 5b67716b8733c0..915a1c82f4a648 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -49,7 +49,10 @@ const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
 const someSpecifierMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
 	if ( specifier.type === 'ImportDefaultSpecifier' ) {
 		return name === 'default';
-	} else if ( specifier.type === 'ExportSpecifier' ) {
+	} else if (
+		specifier.type === 'ExportSpecifier' ||
+		specifier.type === 'ImportNamespaceSpecifier'
+	) {
 		return name === specifier.local.name;
 	}
 	return name === specifier.imported.name;
diff --git a/packages/docgen/tests/fixtures/default-function-named-ast.json b/packages/docgen/tests/fixtures/default-function-named-ast.json
new file mode 100644
index 00000000000000..d641342db98640
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-named-ast.json
@@ -0,0 +1,78 @@
+{
+	"type": "Program",
+	"start": 0,
+	"end": 84,
+	"range": [
+		41,
+		83
+	],
+	"body": [
+		{
+			"type": "ExportDefaultDeclaration",
+			"start": 41,
+			"end": 83,
+			"range": [
+				41,
+				83
+			],
+			"declaration": {
+				"type": "FunctionDeclaration",
+				"start": 56,
+				"end": 83,
+				"range": [
+					56,
+					83
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 65,
+					"end": 78,
+					"range": [
+						65,
+						78
+					],
+					"name": "myDeclaration"
+				},
+				"generator": false,
+				"expression": false,
+				"async": false,
+				"params": [],
+				"body": {
+					"type": "BlockStatement",
+					"start": 81,
+					"end": 83,
+					"range": [
+						81,
+						83
+					],
+					"body": []
+				}
+			},
+			"leadingComments": [
+				{
+					"type": "Block",
+					"value": "*\n * Function declaration example.\n ",
+					"start": 0,
+					"end": 40,
+					"range": [
+						0,
+						40
+					]
+				}
+			]
+		}
+	],
+	"sourceType": "module",
+	"comments": [
+		{
+			"type": "Block",
+			"value": "*\n * Function declaration example.\n ",
+			"start": 0,
+			"end": 40,
+			"range": [
+				0,
+				40
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-function-named-ir.json b/packages/docgen/tests/fixtures/default-function-named-ir.json
new file mode 100644
index 00000000000000..526885397806c0
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-function-named-ir.json
@@ -0,0 +1,7 @@
+[
+	{
+		"name": "default",
+		"description": "Function declaration example.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-ast.json b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
index 7e197ddd20144a..decd724de3af07 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace-ast.json
+++ b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
@@ -1,19 +1,19 @@
 {
 	"type": "Program",
 	"start": 0,
-	"end": 71,
+	"end": 85,
 	"range": [
 		0,
-		70
+		84
 	],
 	"body": [
 		{
 			"type": "ImportDeclaration",
 			"start": 0,
-			"end": 47,
+			"end": 61,
 			"range": [
 				0,
-				47
+				61
 			],
 			"specifiers": [
 				{
@@ -39,50 +39,50 @@
 			"source": {
 				"type": "Literal",
 				"start": 27,
-				"end": 46,
+				"end": 60,
 				"range": [
 					27,
-					46
+					60
 				],
-				"value": "./named-variables",
-				"raw": "'./named-variables'"
+				"value": "./named-import-namespace-module",
+				"raw": "'./named-import-namespace-module'"
 			}
 		},
 		{
 			"type": "ExportNamedDeclaration",
-			"start": 49,
-			"end": 70,
+			"start": 63,
+			"end": 84,
 			"range": [
-				49,
-				70
+				63,
+				84
 			],
 			"declaration": null,
 			"specifiers": [
 				{
 					"type": "ExportSpecifier",
-					"start": 58,
-					"end": 67,
+					"start": 72,
+					"end": 81,
 					"range": [
-						58,
-						67
+						72,
+						81
 					],
 					"local": {
 						"type": "Identifier",
-						"start": 58,
-						"end": 67,
+						"start": 72,
+						"end": 81,
 						"range": [
-							58,
-							67
+							72,
+							81
 						],
 						"name": "variables"
 					},
 					"exported": {
 						"type": "Identifier",
-						"start": 58,
-						"end": 67,
+						"start": 72,
+						"end": 81,
 						"range": [
-							58,
-							67
+							72,
+							81
 						],
 						"name": "variables"
 					}
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module-ir.json b/packages/docgen/tests/fixtures/named-import-namespace-module-ir.json
new file mode 100644
index 00000000000000..6488f6035d0179
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace-module-ir.json
@@ -0,0 +1 @@
+[{"name":"controls","description":"Function declaration example.","tags":[]}]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module.js b/packages/docgen/tests/fixtures/named-import-namespace-module.js
new file mode 100644
index 00000000000000..5c29fce8528403
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace-module.js
@@ -0,0 +1 @@
+export { default as controls } from './default-function-named';
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module.json b/packages/docgen/tests/fixtures/named-import-namespace-module.json
new file mode 100644
index 00000000000000..dba6c3a8856810
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-import-namespace-module.json
@@ -0,0 +1,52 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 0,
+	"end": 63,
+	"range": [
+		0,
+		63
+	],
+	"declaration": null,
+	"specifiers": [
+		{
+			"type": "ExportSpecifier",
+			"start": 9,
+			"end": 28,
+			"range": [
+				9,
+				28
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 9,
+				"end": 16,
+				"range": [
+					9,
+					16
+				],
+				"name": "default"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 20,
+				"end": 28,
+				"range": [
+					20,
+					28
+				],
+				"name": "controls"
+			}
+		}
+	],
+	"source": {
+		"type": "Literal",
+		"start": 36,
+		"end": 62,
+		"range": [
+			36,
+			62
+		],
+		"value": "./default-function-named",
+		"raw": "'./default-function-named'"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.js b/packages/docgen/tests/fixtures/named-import-namespace.js
index 1105e523d639e7..987e272ae1964b 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace.js
+++ b/packages/docgen/tests/fixtures/named-import-namespace.js
@@ -1,3 +1,3 @@
-import * as variables from './named-variables';
+import * as variables from './named-import-namespace-module';
 
 export { variables };
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.json b/packages/docgen/tests/fixtures/named-import-namespace.json
index cae097bff1f3a4..044a07d8735adb 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace.json
+++ b/packages/docgen/tests/fixtures/named-import-namespace.json
@@ -1,38 +1,38 @@
 {
 	"type": "ExportNamedDeclaration",
-	"start": 49,
-	"end": 70,
+	"start": 63,
+	"end": 84,
 	"range": [
-		49,
-		70
+		63,
+		84
 	],
 	"declaration": null,
 	"specifiers": [
 		{
 			"type": "ExportSpecifier",
-			"start": 58,
-			"end": 67,
+			"start": 72,
+			"end": 81,
 			"range": [
-				58,
-				67
+				72,
+				81
 			],
 			"local": {
 				"type": "Identifier",
-				"start": 58,
-				"end": 67,
+				"start": 72,
+				"end": 81,
 				"range": [
-					58,
-					67
+					72,
+					81
 				],
 				"name": "variables"
 			},
 			"exported": {
 				"type": "Identifier",
-				"start": 58,
-				"end": 67,
+				"start": 72,
+				"end": 81,
 				"range": [
-					58,
-					67
+					72,
+					81
 				],
 				"name": "variables"
 			}
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 0578bc4728c412..f58d4095b62bf4 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -274,12 +274,24 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 		path.join( __dirname, './fixtures/named-import-namespace.json' ),
 		'utf-8'
 	);
-	const getModuleImportNamespace = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variables.json' ),
-		'utf-8'
-	) );
+	const astImportNamespace = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-namespace-ast.json' ),
+		'utf-8'
+	);
+	const getModuleImportNamespace = ( filePath ) => {
+		if ( filePath === './named-import-namespace-module' ) {
+			return JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/named-import-namespace-module-ir.json' ),
+				'utf-8'
+			) );
+		}
+		return JSON.parse( fs.readFileSync(
+			path.join( __dirname, './fixtures/default-function-ir.json' ),
+			'utf-8'
+		) );
+	};
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), { body: [] }, getModuleImportNamespace ),
+		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
 		[ { name: 'variables', description: 'Undocumented declaration.', tags: [] } ]
 	);
 	t.end();

From ba1e68ff9ed859ac3553fc19ede81a0ed2f28293 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 14:02:16 +0100
Subject: [PATCH 105/213] Update coverage

---
 packages/docgen/coverage.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 1fc0f8f747fa4f..839a7b28d0a4ef 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -15,10 +15,9 @@ CJS modules:
 
 ES6 modules:
 
-- [ ] data - BUG
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
-- [ ] editor - BUG
+- [ ] editor - BUG, relative path doesnt exists
 - [ ] npm-package-json-lint-config - CONFIG file
 - [ ] scripts - what shall be documented?
 - [-] keycodes - how to document CONSTANTS?
@@ -36,6 +35,7 @@ ES6 modules:
 - [x] components
 - [x] compose - directory dependency
 - [x] core-data - export nothing
+- [x] data
 - [x] date
 - [x] deprecated
 - [x] dom

From 90258c9df884f34945ee5072dec88bc1b1b7b540 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 14:04:53 +0100
Subject: [PATCH 106/213] Respect the dependency extension if any

---
 packages/docgen/src/cli.js | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index e57a3ef391a19b..e56a8c997e68f2 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -21,6 +21,9 @@ const formatter = require( './formatter' );
 
 const relativeToAbsolute = ( basePath, relativePath ) => {
 	const target = path.join( path.dirname( basePath ), relativePath );
+	if ( path.extname( target ) === '.js' ) {
+		return target;
+	}
 	let targetFile = target + '.js';
 	if ( fs.existsSync( targetFile ) ) {
 		return targetFile;

From 961501019f77666461b7fe100eef02ce6876a3b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 14:10:07 +0100
Subject: [PATCH 107/213] Update coverage

---
 packages/docgen/coverage.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 839a7b28d0a4ef..1f0120b0f56797 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -17,7 +17,6 @@ ES6 modules:
 
 - [ ] e2e-test-utils - what shall be documented?
 - [ ] e2e-tests - what shall be documented?
-- [ ] editor - BUG, relative path doesnt exists
 - [ ] npm-package-json-lint-config - CONFIG file
 - [ ] scripts - what shall be documented?
 - [-] keycodes - how to document CONSTANTS?
@@ -41,6 +40,7 @@ ES6 modules:
 - [x] dom
 - [x] dom-ready
 - [x] edit-post - directory dependency
+- [x] editor
 - [x] element
 - [x] escape-html
 - [x] format-library - exports nothing

From a49bfcdf3eb23faba789cf5752c87c4fb52ca9ad Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 14:28:13 +0100
Subject: [PATCH 108/213] Add test for undocumented declaration (no comments)

---
 .../default-undocumented-nocomments.js        |  3 +++
 .../default-undocumented-nocomments.json      | 19 +++++++++++++++++++
 .../test-get-intermediate-representation.js   | 13 +++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 packages/docgen/tests/fixtures/default-undocumented-nocomments.js
 create mode 100644 packages/docgen/tests/fixtures/default-undocumented-nocomments.json

diff --git a/packages/docgen/tests/fixtures/default-undocumented-nocomments.js b/packages/docgen/tests/fixtures/default-undocumented-nocomments.js
new file mode 100644
index 00000000000000..e82c517463fd04
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-undocumented-nocomments.js
@@ -0,0 +1,3 @@
+const myDeclaration = function() {};
+
+export default myDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-undocumented-nocomments.json b/packages/docgen/tests/fixtures/default-undocumented-nocomments.json
new file mode 100644
index 00000000000000..887cf3f9f0a948
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-undocumented-nocomments.json
@@ -0,0 +1,19 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 38,
+	"end": 67,
+	"range": [
+		38,
+		67
+	],
+	"declaration": {
+		"type": "Identifier",
+		"start": 53,
+		"end": 66,
+		"range": [
+			53,
+			66
+		],
+		"name": "myDeclaration"
+	}
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index f58d4095b62bf4..3f16b0c3ed618b 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -14,6 +14,19 @@ const test = require( 'tape' );
  */
 const getIntermediateRepresentation = require( '../src/get-intermediate-representation' );
 
+test( 'IR - undocumented', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-undocumented-nocomments.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
+		name: 'default',
+		description: 'Undocumented declaration.',
+		tags: [],
+	} ] );
+	t.end();
+} );
+
 test( 'IR - default (JSDoc in export statement)', function( t ) {
 	const tokenClassAnonymous = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),

From f68a3d20ceac803a79fae29b14c1813d99daa05b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 14:42:50 +0100
Subject: [PATCH 109/213] Add test for undocumented declaration (// comment)

---
 packages/docgen/src/get-jsdoc-from-token.js   |  2 +-
 .../fixtures/default-undocumented-oneliner.js |  2 +
 .../default-undocumented-oneliner.json        | 45 +++++++++++++++++++
 .../test-get-intermediate-representation.js   |  9 ++++
 4 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 packages/docgen/tests/fixtures/default-undocumented-oneliner.js
 create mode 100644 packages/docgen/tests/fixtures/default-undocumented-oneliner.json

diff --git a/packages/docgen/src/get-jsdoc-from-token.js b/packages/docgen/src/get-jsdoc-from-token.js
index 477fd176d54ea1..1c4bb9885c0b93 100644
--- a/packages/docgen/src/get-jsdoc-from-token.js
+++ b/packages/docgen/src/get-jsdoc-from-token.js
@@ -11,7 +11,7 @@ const getLeadingComments = require( './get-leading-comments' );
 module.exports = function( token ) {
 	let jsdoc;
 	const comments = getLeadingComments( token );
-	if ( comments ) {
+	if ( comments && comments.startsWith( '*\n' ) ) {
 		jsdoc = doctrine.parse( comments, { unwrap: true, recoverable: true } );
 	}
 	return jsdoc;
diff --git a/packages/docgen/tests/fixtures/default-undocumented-oneliner.js b/packages/docgen/tests/fixtures/default-undocumented-oneliner.js
new file mode 100644
index 00000000000000..11e8966dd62d1c
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-undocumented-oneliner.js
@@ -0,0 +1,2 @@
+// This comment should be ignored
+export default function() { }
diff --git a/packages/docgen/tests/fixtures/default-undocumented-oneliner.json b/packages/docgen/tests/fixtures/default-undocumented-oneliner.json
new file mode 100644
index 00000000000000..800319a816bfd8
--- /dev/null
+++ b/packages/docgen/tests/fixtures/default-undocumented-oneliner.json
@@ -0,0 +1,45 @@
+{
+	"type": "ExportDefaultDeclaration",
+	"start": 34,
+	"end": 63,
+	"range": [
+		34,
+		63
+	],
+	"declaration": {
+		"type": "FunctionDeclaration",
+		"start": 49,
+		"end": 63,
+		"range": [
+			49,
+			63
+		],
+		"id": null,
+		"generator": false,
+		"expression": false,
+		"async": false,
+		"params": [],
+		"body": {
+			"type": "BlockStatement",
+			"start": 60,
+			"end": 63,
+			"range": [
+				60,
+				63
+			],
+			"body": []
+		}
+	},
+	"leadingComments": [
+		{
+			"type": "Line",
+			"value": " This comment should be ignored",
+			"start": 0,
+			"end": 33,
+			"range": [
+				0,
+				33
+			]
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 3f16b0c3ed618b..e9e228aa2a935c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -24,6 +24,15 @@ test( 'IR - undocumented', function( t ) {
 		description: 'Undocumented declaration.',
 		tags: [],
 	} ] );
+	const tokenOneliner = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-undocumented-oneliner.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenOneliner ) ), [ {
+		name: 'default',
+		description: 'Undocumented declaration.',
+		tags: [],
+	} ] );
 	t.end();
 } );
 

From 2cb4014c44e4f12d5095ca80a6bcef7375c2957a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 17:21:41 +0100
Subject: [PATCH 110/213] Update README

---
 packages/docgen/README.md | 105 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 104 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index aab4fbb79987a7..4c4dd313a8ee00 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -1,3 +1,106 @@
 # `docgen`
 
-Autogenerate public API documentation from exports and JSDoc comments.
+`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements in the file with their corresponding JSDoc comments in human-readable format.
+
+Some characteristics:
+
+* If the export statement doesn't contain any JSDoc, it'll look up for JSDoc up to the declaration.
+* It can resolve relative dependencies, either files or directories. For example, `import default from './dependency'` will find `dependency.js` or `dependency/index.js`
+
+## Usage
+
+`node src/cli.js <entry-point.js>`
+
+This command will generate a file named `entry-point-api.md` containing all the exports and its JSDoc comments.
+
+## Examples
+
+### Default export
+
+Entry point:
+
+```js
+/**
+ * Adds two numbers.
+ */
+export default function addition( term1, term2 ) {
+	// Implementation would go here.
+}
+```
+
+Output:
+
+```markdown
+
+# API
+
+## default
+
+Adds two numbers.
+```
+
+### Named export
+
+Entry point:
+
+```js
+/**
+ * Adds two numbers.
+ */
+function addition( term1, term2 ) {
+	// Implementation would go here.
+}
+
+export { count };
+```
+
+Output:
+
+```markdown
+
+# API
+
+## count
+
+Adds two numbers.
+```
+
+### Namespace export
+
+Let `count.js` be:
+
+```js
+/**
+ * Substracts two numbers.
+ */
+export function substraction( term1, term2 ) {
+	// Implementation would go here.
+}
+
+/**
+ * Adds two numbers.
+ */
+export function addition( term1, term2 ) {
+	// Implementation would go here.
+}
+```
+
+And the entry point:
+
+```js
+export * from './count';
+```
+
+Output would be:
+
+```markdown
+# API
+
+## addition
+
+Adds two numbers.
+
+## substraction
+
+Substracts two numbers.
+```
\ No newline at end of file

From dbac1dcb0d239c15f2c95c24355277d90473af06 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 17:25:03 +0100
Subject: [PATCH 111/213] Add a debug mode

---
 packages/docgen/src/cli.js | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index e56a8c997e68f2..17832996d6f7b2 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -70,12 +70,14 @@ const processFile = ( inputFile ) => {
 // Prepare input
 let initialInputFile = process.argv[ 2 ];
 if ( initialInputFile === undefined ) {
-	process.stdout.write( '\nUsage: <path-to-docgen> <relative-path-to-file>' );
+	process.stdout.write( '\nUsage: <path-to-docgen> <relative-path-to-entry-point.js>' );
 	process.stdout.write( '\n\n' );
 	process.exit( 1 );
 }
 initialInputFile = path.join( process.cwd(), initialInputFile );
 
+const debugMode = process.argv[ 3 ] === '--debug' ? true : false;
+
 // Process
 const currentFileStack = []; // To keep track of file being processed.
 const result = processFile( initialInputFile );
@@ -98,6 +100,8 @@ if ( result === undefined ) {
 }
 
 fs.writeFileSync( doc, formatter( result.ir ) );
-fs.writeFileSync( ir, JSON.stringify( result.ir ) );
-fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
-fs.writeFileSync( ast, JSON.stringify( result.ast ) );
+if ( debugMode ) {
+	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
+	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
+	fs.writeFileSync( ast, JSON.stringify( result.ast ) );
+}

From 6a83ff8d60511994933b69caf86a4aa66d05e6eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 17:59:48 +0100
Subject: [PATCH 112/213] Update coverage

---
 packages/docgen/coverage.md | 58 ++++++++++++++++++-------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 1f0120b0f56797..caebb57bfcf601 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -1,28 +1,25 @@
 # Coverage
 
-CJS modules:
+Packages outside of scope:
 
-- [ ] babel-plugin-makepot
-- [ ] babel-preset-default
-- [ ] browserslist-config
-- [ ] custom-templated-path-webpack-plugin
-- [ ] docgen
-- [ ] eslint-plugin
-- [ ] is-shallow-equal
-- [ ] jest-preset-default
-- [ ] library-export-default-webpack-plugin
-- [ ] postcss-themes
+- babel-plugin-makepot. CommonJS module. Babel plugin.
+- babel-preset-default. CommonJS module. Babel preset.
+- browserslist-config. CommonJS module. Config.
+- custom-templated-path-webpack-plugin. CommonJS module. Webpack plugin.
+- docgen. CommonJS module.
+- e2e-tests. Do not export anything.
+- eslint-plugin. CommonJS module. ESLint plugin.
+- is-shallow-equal. CommonJS module.
+- jest-preset-default. CommonJS module. Jest preset.
+- library-export-default-webpack-plugin. CommonJS. Webpack plugin.
+- npm-package-json-lint-config. CommonJS. Config.
+- postcss-themes. CommonJS module.
+- scripts. CommonJS module.
 
-ES6 modules:
+DONE:
 
-- [ ] e2e-test-utils - what shall be documented?
-- [ ] e2e-tests - what shall be documented?
-- [ ] npm-package-json-lint-config - CONFIG file
-- [ ] scripts - what shall be documented?
-- [-] keycodes - how to document CONSTANTS?
-- [-] redux-routine - check description with many paragraphs
 - [x] a11y
-- [x] annotations - export nothing
+- [x] annotations
 - [x] api-fetch
 - [x] autop
 - [x] babel-plugin-import-jsx-pragma
@@ -30,30 +27,33 @@ ES6 modules:
 - [x] block-library
 - [x] block-serialization-default-parser
 - [x] block-serialization-spec-parser
-- [x] blocks - directory dependency
+- [x] blocks
 - [x] components
-- [x] compose - directory dependency
-- [x] core-data - export nothing
+- [x] compose
+- [x] core-data
 - [x] data
 - [x] date
 - [x] deprecated
 - [x] dom
 - [x] dom-ready
-- [x] edit-post - directory dependency
+- [x] e2e-test-utils
+- [x] edit-post
 - [x] editor
 - [x] element
 - [x] escape-html
-- [x] format-library - exports nothing
+- [x] format-library
 - [x] hooks
 - [x] html-entities
 - [x] i18n
-- [x] jest-console - export nothing
-- [x] jest-puppeteer-axe - export nothing
-- [x] list-reusable-blocks - export nothing
-- [x] notices - does not export anything
-- [x] nux - directory dependency
+- [x] jest-console
+- [x] jest-puppeteer-axe
+- [x] keycodes
+- [x] list-reusable-blocks
+- [x] notices
+- [x] nux
 - [x] plugins
 - [x] priority-queue
+- [x] redux-routine
 - [x] rich-text
 - [x] shortcode
 - [x] token-list

From fce4ad81a869a69e5eeb79a6d67bc2572e481725 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 18:13:24 +0100
Subject: [PATCH 113/213] Better example

---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 4c4dd313a8ee00..acc66163b620ba 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -67,7 +67,7 @@ Adds two numbers.
 
 ### Namespace export
 
-Let `count.js` be:
+Let `count/index.js` be:
 
 ```js
 /**

From 86c4350fb4bf3ada09643671a4544a2c40b04c08 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 24 Jan 2019 18:47:29 +0100
Subject: [PATCH 114/213] Better README.md

---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index acc66163b620ba..021b91ea840943 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -1,6 +1,6 @@
 # `docgen`
 
-`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements in the file with their corresponding JSDoc comments in human-readable format.
+`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements and their corresponding JSDoc comments in human-readable format.
 
 Some characteristics:
 

From a81b7a6a0ad3f03074bcc7da75fbfe7b838e8c44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 29 Jan 2019 19:37:06 +0100
Subject: [PATCH 115/213] Add params tags to IR and formatter

---
 packages/docgen/src/formatter.js              | 20 +++++++++++++++++++
 .../src/get-intermediate-representation.js    |  8 +++++++-
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index f838d2f77d9d98..0fcdbaf3b4b20c 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,3 +1,18 @@
+const formatParams = ( params, docs ) => {
+	if ( params.length > 0 ) {
+		docs.push( '\n' );
+		docs.push( '*Parameters*' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( ...params.map(
+			( param ) => {
+				return ` * ${ param.name }: ${ param.description }\n`;
+			} )
+		);
+	}
+	docs.push( '\n' );
+};
+
 module.exports = function( artifacts ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
@@ -9,6 +24,11 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( artifact.description.replace( '\n', ' ' ) );
 			docs.push( '\n' );
+			formatParams( artifact.params, docs );
+			docs.push( '\n' );
+			docs.push( artifact.return.map(
+				( r ) => r.description
+			) );
 			docs.push( '\n' );
 		} );
 		docs.pop(); // remove last \n, we want one blank line at the end of the file.
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 915a1c82f4a648..ce24595da13fd3 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -101,6 +101,8 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	return getJSDocFromDependency( token, entry, parseDependency );
 };
 
+const getTagsByName = ( tags, tagName ) => tags.filter( ( tag ) => tag.title === tagName );
+
 /**
  * Takes a export token and returns an intermediate representation in JSON.
  *
@@ -125,6 +127,8 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 				ir.push( {
 					name: namedExport.name,
 					description: namedExport.description,
+					params: getTagsByName( namedExport.tags, 'param' ),
+					return: getTagsByName( namedExport.tags, 'return' ),
 					tags: namedExport.tags,
 				} );
 			} );
@@ -132,7 +136,9 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 			ir.push( {
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
-				tags: [],
+				params: getTagsByName( doc.tags, 'param' ),
+				return: getTagsByName( doc.tags, 'return' ),
+				tags: doc.tags,
 			} );
 		}
 	} );

From 49ede6f8ba5f06ff732aa3917ef0d375e2b746fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 30 Jan 2019 12:10:42 +0100
Subject: [PATCH 116/213] Formatter: show return tag output

---
 packages/docgen/src/formatter.js | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 0fcdbaf3b4b20c..06665bc184c4bd 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,16 +1,24 @@
 const formatParams = ( params, docs ) => {
 	if ( params.length > 0 ) {
-		docs.push( '\n' );
 		docs.push( '*Parameters*' );
 		docs.push( '\n' );
-		docs.push( '\n' );
 		docs.push( ...params.map(
 			( param ) => {
-				return ` * ${ param.name }: ${ param.description }\n`;
+				return `\n * ${ param.name }: ${ param.description }`;
 			} )
 		);
+		docs.push( '\n' );
+	}
+};
+
+const formatOutput = ( output, docs ) => {
+	if ( output.length === 1 ) {
+		docs.push( '*Output*' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( output[ 0 ].description.replace( '\n', ' ' ) );
+		docs.push( '\n' );
 	}
-	docs.push( '\n' );
 };
 
 module.exports = function( artifacts ) {
@@ -24,11 +32,10 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( artifact.description.replace( '\n', ' ' ) );
 			docs.push( '\n' );
+			docs.push( '\n' );
 			formatParams( artifact.params, docs );
 			docs.push( '\n' );
-			docs.push( artifact.return.map(
-				( r ) => r.description
-			) );
+			formatOutput( artifact.return, docs );
 			docs.push( '\n' );
 		} );
 		docs.pop(); // remove last \n, we want one blank line at the end of the file.

From 52bd077d74474b4e618cd72a6c7788972b04d7f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 30 Jan 2019 12:39:22 +0100
Subject: [PATCH 117/213] Adapt engine tests to new API

---
 .../src/get-intermediate-representation.js    |  6 ++--
 packages/docgen/tests/test-engine.js          | 32 +++++++++----------
 2 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index ce24595da13fd3..9e9c7a84affade 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -136,9 +136,9 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 			ir.push( {
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
-				params: getTagsByName( doc.tags, 'param' ),
-				return: getTagsByName( doc.tags, 'return' ),
-				tags: doc.tags,
+				params: getTagsByName( get( doc, [ 'tags' ], [] ), 'param' ),
+				return: getTagsByName( get( doc, [ 'tags' ], [] ), 'return' ),
+				tags: get( doc, [ 'tags' ], [] ),
 			} );
 		}
 	} );
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 557d89a0db3a1f..0ee4a0de6da27a 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -34,9 +34,9 @@ test( 'Engine - many exports at once', ( t ) => {
 	t.deepEqual(
 		ir,
 		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
-			{ name: 'default', description: 'Default declaration example.', tags: [] },
+			{ name: 'firstDeclaration', description: 'First declaration example.', params: [], return: [], tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', params: [], return: [], tags: [] },
+			{ name: 'default', description: 'Default declaration example.', params: [], return: [], tags: [] },
 		]
 	);
 	t.end();
@@ -53,7 +53,7 @@ test( 'Engine - named export (function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -69,7 +69,7 @@ test( 'Engine - named export (variable)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -87,7 +87,7 @@ test( 'Engine - named export (single identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -105,7 +105,7 @@ test( 'Engine - named export (single identifier) using JSDoc from declaration',
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -131,8 +131,8 @@ test( 'Engine - named export (multiple identifiers) using JSDoc from declaration
 	t.deepEqual(
 		ir,
 		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
+			{ name: 'firstDeclaration', description: 'First declaration example.', params: [], return: [], tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', params: [], return: [], tags: [] },
 		]
 	);
 	t.end();
@@ -153,7 +153,7 @@ test( 'Engine - named export (single identifier) using JSDoc from dependency', (
 	);
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -169,7 +169,7 @@ test( 'Engine - default export (named function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -185,7 +185,7 @@ test( 'Engine - default export (anonymous function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -203,7 +203,7 @@ test( 'Engine - default export (identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -221,7 +221,7 @@ test( 'Engine - default export (identifier) using JSDoc from function', ( t ) =>
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -239,7 +239,7 @@ test( 'Engine - default export (identifier) using JSDoc from variable', ( t ) =>
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -254,7 +254,7 @@ test( 'Engine - undocumented export', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'Undocumented declaration.', tags: [] } ]
+		[ { name: 'default', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );

From 31bdfa7630b24257ca68168973fd04bf8feb6d36 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 30 Jan 2019 12:41:36 +0100
Subject: [PATCH 118/213] Adapt formatter tests to new API

---
 packages/docgen/src/formatter.js                 | 4 ++--
 packages/docgen/tests/test-formatter-markdown.js | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 06665bc184c4bd..527d2e64611d0f 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,5 +1,5 @@
 const formatParams = ( params, docs ) => {
-	if ( params.length > 0 ) {
+	if ( params && params.length > 0 ) {
 		docs.push( '*Parameters*' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
@@ -12,7 +12,7 @@ const formatParams = ( params, docs ) => {
 };
 
 const formatOutput = ( output, docs ) => {
-	if ( output.length === 1 ) {
+	if ( output && output.length === 1 ) {
 		docs.push( '*Output*' );
 		docs.push( '\n' );
 		docs.push( '\n' );
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index e8933a7b6f9491..ed113790dafba5 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -12,7 +12,7 @@ test( 'Formatter - returns markdown', ( t ) => {
 	const docs = formatter( [ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ] );
 	t.equal(
 		docs,
-		'# API\n\n## myDeclaration\n\nMy declaration example.\n'
+		'# API\n\n## myDeclaration\n\nMy declaration example.\n\n\n'
 	);
 	t.end();
 } );

From 27ac53471c4cd5289dc5dffee0b9aed3387b189e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 30 Jan 2019 12:48:54 +0100
Subject: [PATCH 119/213] Adapt IR tests to new API

---
 .../test-get-intermediate-representation.js   | 70 +++++++++++++------
 1 file changed, 50 insertions(+), 20 deletions(-)

diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index e9e228aa2a935c..878169e1feb1de 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -22,6 +22,8 @@ test( 'IR - undocumented', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
 		name: 'default',
 		description: 'Undocumented declaration.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenOneliner = fs.readFileSync(
@@ -31,6 +33,8 @@ test( 'IR - undocumented', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenOneliner ) ), [ {
 		name: 'default',
 		description: 'Undocumented declaration.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	t.end();
@@ -44,6 +48,8 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassAnonymous ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenClassNamed = fs.readFileSync(
@@ -53,6 +59,8 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassNamed ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenFnAnonymous = fs.readFileSync(
@@ -62,6 +70,8 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnAnonymous ) ), [ {
 		name: 'default',
 		description: 'Function declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenFnNamed = fs.readFileSync(
@@ -71,6 +81,8 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnNamed ) ), [ {
 		name: 'default',
 		description: 'Function declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenVariable = fs.readFileSync(
@@ -80,6 +92,8 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
 		name: 'default',
 		description: 'Variable declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	t.end();
@@ -97,6 +111,8 @@ test( 'IR - default (JSDoc in same file)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const namedExport = fs.readFileSync(
@@ -109,11 +125,11 @@ test( 'IR - default (JSDoc in same file)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -136,6 +152,8 @@ test( 'IR - default (JSDoc in module dependency)', function( t ) {
 		[ {
 			name: 'default',
 			description: 'Function declaration.',
+			params: [],
+			return: [],
 			tags: [],
 		} ]
 	);
@@ -156,6 +174,8 @@ test( 'IR - default (JSDoc in module dependency)', function( t ) {
 		[ {
 			name: 'default',
 			description: 'Function declaration.',
+			params: [],
+			return: [],
 			tags: [],
 		} ]
 	);
@@ -170,6 +190,8 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClass ) ), [ {
 		name: 'MyDeclaration',
 		description: 'My declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenFn = fs.readFileSync(
@@ -179,6 +201,8 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFn ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenVariable = fs.readFileSync(
@@ -188,6 +212,8 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
+		params: [],
+		return: [],
 		tags: [],
 	} ] );
 	const tokenVariables = fs.readFileSync(
@@ -195,8 +221,8 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariables ) ), [
-		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [] },
-		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'firstDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] },
+		{ name: 'secondDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] },
 	] );
 	t.end();
 } );
@@ -213,6 +239,8 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
+		params: [],
+		return: [],
 		tags: [] },
 	] );
 	const tokenObject = fs.readFileSync(
@@ -226,6 +254,8 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
+		params: [],
+		return: [],
 		tags: [] },
 	] );
 	const tokens = fs.readFileSync(
@@ -237,9 +267,9 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ), JSON.parse( asts ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
 	] );
 	const foo = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
@@ -250,11 +280,11 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
 	] );
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
 	] );
 	t.end();
 } );
@@ -270,7 +300,7 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
+		[ { name: 'default', description: 'Module declaration.', params: [], return: [], tags: [] } ]
 	);
 	const tokenImportNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-import-named.json' ),
@@ -282,7 +312,7 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),
@@ -290,7 +320,7 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { name: 'moduleName', description: 'Module declaration.', tags: [] } ]
+		[ { name: 'moduleName', description: 'Module declaration.', params: [], return: [], tags: [] } ]
 	);
 	const tokenImportNamespace = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-import-namespace.json' ),
@@ -314,7 +344,7 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 	};
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { name: 'variables', description: 'Undocumented declaration.', tags: [] } ]
+		[ { name: 'variables', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
 	);
 	t.end();
 } );
@@ -331,9 +361,9 @@ test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
-			{ name: 'MyClass', description: 'Named class.', tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', params: [], return: [], tags: [] },
+			{ name: 'myFunction', description: 'Named function.', params: [], return: [], tags: [] },
+			{ name: 'MyClass', description: 'Named class.', params: [], return: [], tags: [] },
 		]
 	);
 	const tokenCommented = fs.readFileSync(
@@ -343,9 +373,9 @@ test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
-			{ name: 'MyClass', description: 'Named class.', tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', params: [], return: [], tags: [] },
+			{ name: 'myFunction', description: 'Named function.', params: [], return: [], tags: [] },
+			{ name: 'MyClass', description: 'Named class.', params: [], return: [], tags: [] },
 		]
 	);
 	t.end();

From 23ee5494854738ba76e3b2201e11fd34fe974f46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 30 Jan 2019 14:24:18 +0100
Subject: [PATCH 120/213] Update fixtures and test data to uncover some bug

---
 .../tests/fixtures/named-identifiers-ir.json  |  23 ++++
 .../tests/fixtures/named-import-named.js      |   6 +-
 .../tests/fixtures/named-import-named.json    | 102 ++++++++++++++----
 .../test-get-intermediate-representation.js   |   8 +-
 4 files changed, 114 insertions(+), 25 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/named-identifiers-ir.json

diff --git a/packages/docgen/tests/fixtures/named-identifiers-ir.json b/packages/docgen/tests/fixtures/named-identifiers-ir.json
new file mode 100644
index 00000000000000..961dc6650583e4
--- /dev/null
+++ b/packages/docgen/tests/fixtures/named-identifiers-ir.json
@@ -0,0 +1,23 @@
+[
+	{
+		"name": "functionDeclaration",
+		"description": "Function declaration example.",
+		"params": [],
+		"return": [],
+		"tags": []
+	},
+	{
+		"name": "variableDeclaration",
+		"description": "Variable declaration example.",
+		"params": [],
+		"return": [],
+		"tags": []
+	},
+	{
+		"name": "ClassDeclaration",
+		"description": "Class declaration example.",
+		"params": [],
+		"return": [],
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-import-named.js b/packages/docgen/tests/fixtures/named-import-named.js
index e04aa137083124..68e9b4499792c7 100644
--- a/packages/docgen/tests/fixtures/named-import-named.js
+++ b/packages/docgen/tests/fixtures/named-import-named.js
@@ -1 +1,5 @@
-export { myDeclaration } from './named-function';
+export {
+	functionDeclaration,
+	variableDeclaration,
+	ClassDeclaration,
+} from './named-identifiers';
diff --git a/packages/docgen/tests/fixtures/named-import-named.json b/packages/docgen/tests/fixtures/named-import-named.json
index da3c4029553368..e042900ea14a3e 100644
--- a/packages/docgen/tests/fixtures/named-import-named.json
+++ b/packages/docgen/tests/fixtures/named-import-named.json
@@ -1,52 +1,110 @@
 {
 	"type": "ExportNamedDeclaration",
 	"start": 0,
-	"end": 49,
+	"end": 101,
 	"range": [
 		0,
-		49
+		101
 	],
 	"declaration": null,
 	"specifiers": [
 		{
 			"type": "ExportSpecifier",
-			"start": 9,
-			"end": 22,
+			"start": 10,
+			"end": 29,
 			"range": [
-				9,
-				22
+				10,
+				29
 			],
 			"local": {
 				"type": "Identifier",
-				"start": 9,
-				"end": 22,
+				"start": 10,
+				"end": 29,
 				"range": [
-					9,
-					22
+					10,
+					29
 				],
-				"name": "myDeclaration"
+				"name": "functionDeclaration"
 			},
 			"exported": {
 				"type": "Identifier",
-				"start": 9,
-				"end": 22,
+				"start": 10,
+				"end": 29,
 				"range": [
-					9,
-					22
+					10,
+					29
 				],
-				"name": "myDeclaration"
+				"name": "functionDeclaration"
+			}
+		},
+		{
+			"type": "ExportSpecifier",
+			"start": 32,
+			"end": 51,
+			"range": [
+				32,
+				51
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 32,
+				"end": 51,
+				"range": [
+					32,
+					51
+				],
+				"name": "variableDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 32,
+				"end": 51,
+				"range": [
+					32,
+					51
+				],
+				"name": "variableDeclaration"
+			}
+		},
+		{
+			"type": "ExportSpecifier",
+			"start": 54,
+			"end": 70,
+			"range": [
+				54,
+				70
+			],
+			"local": {
+				"type": "Identifier",
+				"start": 54,
+				"end": 70,
+				"range": [
+					54,
+					70
+				],
+				"name": "ClassDeclaration"
+			},
+			"exported": {
+				"type": "Identifier",
+				"start": 54,
+				"end": 70,
+				"range": [
+					54,
+					70
+				],
+				"name": "ClassDeclaration"
 			}
 		}
 	],
 	"source": {
 		"type": "Literal",
-		"start": 30,
-		"end": 48,
+		"start": 79,
+		"end": 100,
 		"range": [
-			30,
-			48
+			79,
+			100
 		],
-		"value": "./named-function",
-		"raw": "'./named-function'"
+		"value": "./named-identifiers",
+		"raw": "'./named-identifiers'"
 	}
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 878169e1feb1de..e481408f75e505 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -307,12 +307,16 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 		'utf-8'
 	);
 	const getModuleImportNamed = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function-ir.json' ),
+		path.join( __dirname, './fixtures/named-identifiers-ir.json' ),
 		'utf-8'
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[
+			{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
+			{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
+			{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
+		]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),

From 174dbb0dc20399f1893555883f9d51ef06cdaa93 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 1 Feb 2019 12:33:09 +0100
Subject: [PATCH 121/213] Reorder tests

---
 .../test-get-intermediate-representation.js   | 262 +++++++++---------
 1 file changed, 138 insertions(+), 124 deletions(-)

diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index e481408f75e505..5c9fd21261b23c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -40,7 +40,7 @@ test( 'IR - undocumented', function( t ) {
 	t.end();
 } );
 
-test( 'IR - default (JSDoc in export statement)', function( t ) {
+test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	const tokenClassAnonymous = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
@@ -99,90 +99,7 @@ test( 'IR - default (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - default (JSDoc in same file)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier.json' ),
-		'utf-8'
-	);
-	const ast = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
-		name: 'default',
-		description: 'Class declaration example.',
-		params: [],
-		return: [],
-		tags: [],
-	} ] );
-	const namedExport = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-named-export.json' ),
-		'utf-8'
-	);
-	const namedExportAST = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-named-export-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'default', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'IR - default (JSDoc in module dependency)', function( t ) {
-	const tokenDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default.json' ),
-		'utf-8'
-	);
-	const astDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default-ast.json' ),
-		'utf-8'
-	);
-	const getModuleDefault = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
-		[ {
-			name: 'default',
-			description: 'Function declaration.',
-			params: [],
-			return: [],
-			tags: [],
-		} ]
-	);
-	const tokenNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named.json' ),
-		'utf-8'
-	);
-	const astNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named-ast.json' ),
-		'utf-8'
-	);
-	const getModuleNamed = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
-		[ {
-			name: 'default',
-			description: 'Function declaration.',
-			params: [],
-			return: [],
-			tags: [],
-		} ]
-	);
-	t.end();
-} );
-
-test( 'IR - named (JSDoc in export statement)', function( t ) {
+test( 'IR - JSDoc in export statement (named export)', function( t ) {
 	const tokenClass = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
@@ -227,7 +144,47 @@ test( 'IR - named (JSDoc in export statement)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - named (JSDoc in same file)', function( t ) {
+test( 'IR - JSDoc in export statement (namespace export)', function( t ) {
+	t.equals( true, false );
+	t.end();
+} );
+
+test( 'IR - JSDoc in same file (default export)', function( t ) {
+	const token = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-identifier.json' ),
+		'utf-8'
+	);
+	const ast = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-identifier-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
+		name: 'default',
+		description: 'Class declaration example.',
+		params: [],
+		return: [],
+		tags: [],
+	} ] );
+	const namedExport = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-named-export.json' ),
+		'utf-8'
+	);
+	const namedExportAST = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-named-export-ast.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
+		[ { name: 'default', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
+	);
+	t.end();
+} );
+
+test( 'IR - JSDoc in same file (named export)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier.json' ),
 		'utf-8'
@@ -289,19 +246,7 @@ test( 'IR - named (JSDoc in same file)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - named (JSDoc in module dependency)', function( t ) {
-	const tokenDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default.json' ),
-		'utf-8'
-	);
-	const getModule = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { name: 'default', description: 'Module declaration.', params: [], return: [], tags: [] } ]
-	);
+test( 'IR - JSDoc in module dependency (named export)', function( t ) {
 	const tokenImportNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-import-named.json' ),
 		'utf-8'
@@ -318,42 +263,35 @@ test( 'IR - named (JSDoc in module dependency)', function( t ) {
 			{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
 		]
 	);
-	const tokenDefaultExported = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default-exported.json' ),
+	t.end();
+} );
+
+test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
+	const tokenDefault = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default.json' ),
 		'utf-8'
 	);
-	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { name: 'moduleName', description: 'Module declaration.', params: [], return: [], tags: [] } ]
-	);
-	const tokenImportNamespace = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-namespace.json' ),
+	const getModule = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default-module-ir.json' ),
 		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
+		[ { name: 'default', description: 'Module declaration.', params: [], return: [], tags: [] } ]
 	);
-	const astImportNamespace = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-namespace-ast.json' ),
+	const tokenDefaultExported = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-default-exported.json' ),
 		'utf-8'
 	);
-	const getModuleImportNamespace = ( filePath ) => {
-		if ( filePath === './named-import-namespace-module' ) {
-			return JSON.parse( fs.readFileSync(
-				path.join( __dirname, './fixtures/named-import-namespace-module-ir.json' ),
-				'utf-8'
-			) );
-		}
-		return JSON.parse( fs.readFileSync(
-			path.join( __dirname, './fixtures/default-function-ir.json' ),
-			'utf-8'
-		) );
-	};
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { name: 'variables', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
+		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
+		[ { name: 'moduleName', description: 'Module declaration.', params: [], return: [], tags: [] } ]
 	);
+
 	t.end();
 } );
 
-test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
+test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/namespace.json' ),
 		'utf-8'
@@ -384,3 +322,79 @@ test( 'IR - namespace (JSDoc in module dependency)', function( t ) {
 	);
 	t.end();
 } );
+
+test( 'IR - JSDoc in module dependency through import (default export)', function( t ) {
+	const tokenDefault = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default.json' ),
+		'utf-8'
+	);
+	const astDefault = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default-ast.json' ),
+		'utf-8'
+	);
+	const getModuleDefault = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-default-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
+		[ {
+			name: 'default',
+			description: 'Function declaration.',
+			params: [],
+			return: [],
+			tags: [],
+		} ]
+	);
+	const tokenNamed = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-named.json' ),
+		'utf-8'
+	);
+	const astNamed = fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-named-ast.json' ),
+		'utf-8'
+	);
+	const getModuleNamed = () => JSON.parse( fs.readFileSync(
+		path.join( __dirname, './fixtures/default-import-named-module-ir.json' ),
+		'utf-8'
+	) );
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
+		[ {
+			name: 'default',
+			description: 'Function declaration.',
+			params: [],
+			return: [],
+			tags: [],
+		} ]
+	);
+	t.end();
+} );
+
+test( 'IR - JSDoc in module dependency through import (named export)', function( t ) {
+	const tokenImportNamespace = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-namespace.json' ),
+		'utf-8'
+	);
+	const astImportNamespace = fs.readFileSync(
+		path.join( __dirname, './fixtures/named-import-namespace-ast.json' ),
+		'utf-8'
+	);
+	const getModuleImportNamespace = ( filePath ) => {
+		if ( filePath === './named-import-namespace-module' ) {
+			return JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/named-import-namespace-module-ir.json' ),
+				'utf-8'
+			) );
+		}
+		return JSON.parse( fs.readFileSync(
+			path.join( __dirname, './fixtures/default-function-ir.json' ),
+			'utf-8'
+		) );
+	};
+	t.deepEqual(
+		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
+		[ { name: 'variables', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
+	);
+	t.end();
+} );

From 18257d089d44f4f5dc9d09ea6d965ed0a76d8bd5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 1 Feb 2019 13:36:18 +0100
Subject: [PATCH 122/213] Fix bug on retrieving JSDoc from module dep

---
 .../src/get-intermediate-representation.js    | 41 +++++++++++++------
 .../test-get-intermediate-representation.js   |  5 ---
 2 files changed, 29 insertions(+), 17 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 9e9c7a84affade..47be635cdb5db6 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -46,17 +46,34 @@ const hasImportWithName = ( node, name ) =>
 
 const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
 
-const someSpecifierMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
-	if ( specifier.type === 'ImportDefaultSpecifier' ) {
-		return name === 'default';
-	} else if (
-		specifier.type === 'ExportSpecifier' ||
-		specifier.type === 'ImportNamespaceSpecifier'
-	) {
-		return name === specifier.local.name;
-	}
-	return name === specifier.imported.name;
-} );
+// const someSpecifierMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
+// 	if ( specifier.type === 'ImportDefaultSpecifier' ) {
+// 		return name === 'default';
+// 	} else if (
+// 		specifier.type === 'ExportSpecifier' ||
+// 		specifier.type === 'ImportNamespaceSpecifier'
+// 	) {
+// 		return name === specifier.local.name;
+// 	}
+// 	return name === specifier.imported.name;
+// } );
+
+const someImportMatchesName = ( name, token ) => {
+	let matches = false;
+	token.specifiers.forEach( ( specifier ) => {
+		if ( ( specifier.type === 'ImportDefaultSpecifier' ) && ( name === 'default' ) ) {
+			matches = true;
+		}
+		if ( ( specifier.type === 'ImportSpecifier' ) && ( name === specifier.imported.name ) ) {
+			matches = true;
+		}
+	} );
+	return matches;
+};
+
+const someEntryMatchesName = ( name, entry, token ) =>
+	( token.type === 'ExportNamedDeclaration' && entry.localName === name ) ||
+	( token.type === 'ImportDeclaration' && someImportMatchesName( name, token ) );
 
 const getJSDocFromDependency = ( token, entry, parseDependency ) => {
 	let doc;
@@ -64,7 +81,7 @@ const getJSDocFromDependency = ( token, entry, parseDependency ) => {
 	if ( entry.localName === NAMESPACE_EXPORT ) {
 		doc = ir.filter( ( { name } ) => name !== DEFAULT_EXPORT );
 	} else {
-		doc = ir.find( ( { name } ) => someSpecifierMatchesName( name, token ) );
+		doc = ir.find( ( { name } ) => someEntryMatchesName( name, entry, token ) );
 	}
 	return doc;
 };
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 5c9fd21261b23c..20b9a31f8d049c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -144,11 +144,6 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 	t.end();
 } );
 
-test( 'IR - JSDoc in export statement (namespace export)', function( t ) {
-	t.equals( true, false );
-	t.end();
-} );
-
 test( 'IR - JSDoc in same file (default export)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),

From 3bf4732239c5a5fb0ec3b0bc5e9fb2720c0d9e16 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 13:23:48 +0100
Subject: [PATCH 123/213] Markdown: clean spaces in descriptions

---
 packages/docgen/src/formatter.js | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 527d2e64611d0f..ed7bc9a8c1e20d 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -4,19 +4,26 @@ const formatParams = ( params, docs ) => {
 		docs.push( '\n' );
 		docs.push( ...params.map(
 			( param ) => {
-				return `\n * ${ param.name }: ${ param.description }`;
+				return `\n * ${ param.name }: ${ cleanSpaces( param.description ) }`;
 			} )
 		);
 		docs.push( '\n' );
 	}
 };
 
+const cleanSpaces = ( paragraph ) =>
+	paragraph.split( '\n' ).map(
+		( sentence ) => sentence.trim()
+	).reduce(
+		( acc, current ) => acc + ' ' + current, ''
+	);
+
 const formatOutput = ( output, docs ) => {
 	if ( output && output.length === 1 ) {
 		docs.push( '*Output*' );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( output[ 0 ].description.replace( '\n', ' ' ) );
+		docs.push( cleanSpaces( output[ 0 ].description ) );
 		docs.push( '\n' );
 	}
 };
@@ -30,7 +37,7 @@ module.exports = function( artifacts ) {
 			docs.push( `## ${ artifact.name }` );
 			docs.push( '\n' );
 			docs.push( '\n' );
-			docs.push( artifact.description.replace( '\n', ' ' ) );
+			docs.push( cleanSpaces( artifact.description ) );
 			docs.push( '\n' );
 			docs.push( '\n' );
 			formatParams( artifact.params, docs );

From 7816de22e826b29feac5692048e2462059488ddb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 13:49:49 +0100
Subject: [PATCH 124/213] Add support for nullable types

---
 packages/docgen/src/formatter.js | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index ed7bc9a8c1e20d..f39be1df7cf9e3 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,12 +1,18 @@
+const getType = ( param ) => {
+	if ( param.type.type === 'NullableType' ) {
+		return param.type.expression.name;
+	}
+
+	return param.type.name;
+};
+
 const formatParams = ( params, docs ) => {
 	if ( params && params.length > 0 ) {
 		docs.push( '*Parameters*' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
-			( param ) => {
-				return `\n * ${ param.name }: ${ cleanSpaces( param.description ) }`;
-			} )
-		);
+			( param ) => `\n * ${ param.name } (${ getType( param ) }): ${ cleanSpaces( param.description ) }`
+		) );
 		docs.push( '\n' );
 	}
 };

From a0bdec95573ec093d49da5736f24649ea4477581 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 14:28:37 +0100
Subject: [PATCH 125/213] Extract getParamType and add tests

---
 packages/docgen/package.json                  |  3 +-
 packages/docgen/src/formatter.js              | 13 +++---
 .../docgen/src/get-param-type-as-string.js    | 13 ++++++
 .../tests/test-get-param-type-as-string.js    | 41 +++++++++++++++++++
 4 files changed, 61 insertions(+), 9 deletions(-)
 create mode 100644 packages/docgen/src/get-param-type-as-string.js
 create mode 100644 packages/docgen/tests/test-get-param-type-as-string.js

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index ddd28f0f39b51b..92ead305839647 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -31,6 +31,7 @@
 		"test:engine": "tape tests/test-engine.js | faucet",
 		"test:formatter": "tape tests/test-formatter-markdown.js | faucet",
 		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
-		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet"
+		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet",
+		"test:get-param-type-as-string": "tape tests/test-get-param-type-as-string.js | faucet"
 	}
 }
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index f39be1df7cf9e3..7440b18c2221b4 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,17 +1,14 @@
-const getType = ( param ) => {
-	if ( param.type.type === 'NullableType' ) {
-		return param.type.expression.name;
-	}
-
-	return param.type.name;
-};
+/**
+ * Internal dependencies
+ */
+const getParamType = require( './get-param-type-as-string' );
 
 const formatParams = ( params, docs ) => {
 	if ( params && params.length > 0 ) {
 		docs.push( '*Parameters*' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
-			( param ) => `\n * ${ param.name } (${ getType( param ) }): ${ cleanSpaces( param.description ) }`
+			( param ) => `\n * ${ param.name } (${ getParamType( param ) }): ${ cleanSpaces( param.description ) }`
 		) );
 		docs.push( '\n' );
 	}
diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
new file mode 100644
index 00000000000000..e3c924a799c8a9
--- /dev/null
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -0,0 +1,13 @@
+const getType = function( param ) {
+	if ( param.type.type === 'NullableType' ) {
+		return getType( param.type.expression );
+	} else if ( param.type.type === 'NameExpression' ) {
+		return getType( param.type );
+	}
+
+	return param.name;
+};
+
+module.exports = function( param ) {
+	return getType( param );
+};
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
new file mode 100644
index 00000000000000..c48e96aeff0bfd
--- /dev/null
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -0,0 +1,41 @@
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+/**
+ * Internal dependencies.
+ */
+const getParamType = require( '../src/get-param-type-as-string' );
+
+test( 'getParamType from NameExpression', ( t ) => {
+	const type = getParamType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'NameExpression',
+			name: 'Array',
+		},
+		name: 'paramName',
+	} );
+	t.equal( type, 'Array' );
+	t.end();
+} );
+
+test( 'getParamType from NullableType', ( t ) => {
+	const type = getParamType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'NullableType',
+			expression: {
+				type: 'NameExpression',
+				name: 'string',
+			},
+			prefix: true,
+		},
+		name: 'paramName',
+	} );
+	t.equal( type, 'string' );
+	t.end();
+} );

From c2f814bde90023aa13ab8e0227cc59d791f3723e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 14:33:16 +0100
Subject: [PATCH 126/213] getParamType: add support for RestType

---
 .../docgen/src/get-param-type-as-string.js    |  2 +-
 .../tests/test-get-param-type-as-string.js    | 19 +++++++++++++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index e3c924a799c8a9..b38621beba436c 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -1,5 +1,5 @@
 const getType = function( param ) {
-	if ( param.type.type === 'NullableType' ) {
+	if ( param.type.expression ) {
 		return getType( param.type.expression );
 	} else if ( param.type.type === 'NameExpression' ) {
 		return getType( param.type );
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
index c48e96aeff0bfd..1ab9ac889d0ead 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -39,3 +39,22 @@ test( 'getParamType from NullableType', ( t ) => {
 	t.equal( type, 'string' );
 	t.end();
 } );
+
+test( 'getParamType from RestType', ( t ) => {
+	const type = getParamType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'RestType',
+			expression: {
+				type: 'NameExpression',
+				name: 'Function',
+			},
+			prefix: true,
+		},
+		name: 'paramName',
+	} );
+	t.equal( type, 'Function' );
+	t.end();
+} );
+

From 72b1adc740c6e7e1ca79097330a807fdc188a810 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 14:58:36 +0100
Subject: [PATCH 127/213] getParamType: add support for unions

---
 .../docgen/src/get-param-type-as-string.js    |  9 ++++++---
 .../tests/test-get-param-type-as-string.js    | 20 ++++++++++++++++++-
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index b38621beba436c..a80c54b4e24bc3 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -1,8 +1,11 @@
 const getType = function( param ) {
-	if ( param.type.expression ) {
-		return getType( param.type.expression );
-	} else if ( param.type.type === 'NameExpression' ) {
+	if ( param.type.type ) {
 		return getType( param.type );
+	} else if ( param.expression ) {
+		return getType( param.expression );
+	} else if ( param.elements ) {
+		const types = param.elements.map( ( element ) => getType( element ) );
+		return types.join( ', ' );
 	}
 
 	return param.name;
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
index 1ab9ac889d0ead..d4832d94403d78 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -50,7 +50,6 @@ test( 'getParamType from RestType', ( t ) => {
 				type: 'NameExpression',
 				name: 'Function',
 			},
-			prefix: true,
 		},
 		name: 'paramName',
 	} );
@@ -58,3 +57,22 @@ test( 'getParamType from RestType', ( t ) => {
 	t.end();
 } );
 
+test( 'getParamType from RestType with UnionType', ( t ) => {
+	const type = getParamType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'RestType',
+			expression: {
+				type: 'UnionType',
+				elements: [
+					{ type: 'NameExpression', name: 'Object' },
+					{ type: 'NameExpression', name: 'string' },
+				],
+			},
+		},
+		name: 'paramName',
+	} );
+	t.equal( type, 'Object, string' );
+	t.end();
+} );

From 2b3fe94a9f161c11c33005d1ea6c3a7232c252f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:16:43 +0100
Subject: [PATCH 128/213] Markdown tweaks: better formatting, adding output
 type

---
 packages/docgen/src/formatter.js | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 7440b18c2221b4..d945735714f4c1 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -5,10 +5,10 @@ const getParamType = require( './get-param-type-as-string' );
 
 const formatParams = ( params, docs ) => {
 	if ( params && params.length > 0 ) {
-		docs.push( '*Parameters*' );
+		docs.push( '**Parameters**' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
-			( param ) => `\n * ${ param.name } (${ getParamType( param ) }): ${ cleanSpaces( param.description ) }`
+			( param ) => `\n- **${ param.name }** \`(${ getParamType( param ) })\`: ${ cleanSpaces( param.description ) }`
 		) );
 		docs.push( '\n' );
 	}
@@ -18,15 +18,16 @@ const cleanSpaces = ( paragraph ) =>
 	paragraph.split( '\n' ).map(
 		( sentence ) => sentence.trim()
 	).reduce(
-		( acc, current ) => acc + ' ' + current, ''
-	);
+		( acc, current ) => acc + ' ' + current,
+		''
+	).trim();
 
 const formatOutput = ( output, docs ) => {
 	if ( output && output.length === 1 ) {
-		docs.push( '*Output*' );
+		docs.push( '**Returns**' );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( cleanSpaces( output[ 0 ].description ) );
+		docs.push( `\`${ getParamType( output[ 0 ] ) }\` ${ cleanSpaces( output[ 0 ].description ) }` );
 		docs.push( '\n' );
 	}
 };

From 3de973dc08e8badcbf8399393616ce8b8e20cd54 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:28:46 +0100
Subject: [PATCH 129/213] Markdown: sort output by symbol name

---
 packages/docgen/src/formatter.js | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index d945735714f4c1..ccc32ab2549d71 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -36,6 +36,17 @@ module.exports = function( artifacts ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
 	docs.push( '\n' );
+	artifacts.sort( ( first, second ) => {
+		const firstName = first.name.toUpperCase();
+		const secondName = second.name.toUpperCase();
+		if ( firstName < secondName ) {
+			return -1;
+		}
+		if ( firstName > secondName ) {
+			return 1;
+		}
+		return 0;
+	} );
 	if ( artifacts && artifacts.length > 0 ) {
 		artifacts.forEach( ( artifact ) => {
 			docs.push( `## ${ artifact.name }` );

From ad3e48bf3023d27eb61ba152c16b0b886317c300 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:32:22 +0100
Subject: [PATCH 130/213] Markdown: improve spacing

---
 packages/docgen/src/formatter.js | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index ccc32ab2549d71..2542d6b756d101 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -5,12 +5,13 @@ const getParamType = require( './get-param-type-as-string' );
 
 const formatParams = ( params, docs ) => {
 	if ( params && params.length > 0 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
 		docs.push( '**Parameters**' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
 			( param ) => `\n- **${ param.name }** \`(${ getParamType( param ) })\`: ${ cleanSpaces( param.description ) }`
 		) );
-		docs.push( '\n' );
 	}
 };
 
@@ -24,11 +25,12 @@ const cleanSpaces = ( paragraph ) =>
 
 const formatOutput = ( output, docs ) => {
 	if ( output && output.length === 1 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
 		docs.push( '**Returns**' );
 		docs.push( '\n' );
 		docs.push( '\n' );
 		docs.push( `\`${ getParamType( output[ 0 ] ) }\` ${ cleanSpaces( output[ 0 ].description ) }` );
-		docs.push( '\n' );
 	}
 };
 
@@ -53,12 +55,10 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( '\n' );
 			docs.push( cleanSpaces( artifact.description ) );
-			docs.push( '\n' );
-			docs.push( '\n' );
 			formatParams( artifact.params, docs );
-			docs.push( '\n' );
 			formatOutput( artifact.return, docs );
 			docs.push( '\n' );
+			docs.push( '\n' );
 		} );
 		docs.pop(); // remove last \n, we want one blank line at the end of the file.
 	} else {

From 39fd98f90f0416c5e51c4991bb22c2f05b786ee3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:35:15 +0100
Subject: [PATCH 131/213] Use | symbols for type unions

---
 packages/docgen/src/get-param-type-as-string.js        | 2 +-
 packages/docgen/tests/test-get-param-type-as-string.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index a80c54b4e24bc3..22919bb1528f75 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -5,7 +5,7 @@ const getType = function( param ) {
 		return getType( param.expression );
 	} else if ( param.elements ) {
 		const types = param.elements.map( ( element ) => getType( element ) );
-		return types.join( ', ' );
+		return types.join( ' | ' );
 	}
 
 	return param.name;
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
index d4832d94403d78..f3ab07cbe329af 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -73,6 +73,6 @@ test( 'getParamType from RestType with UnionType', ( t ) => {
 		},
 		name: 'paramName',
 	} );
-	t.equal( type, 'Object, string' );
+	t.equal( type, 'Object | string' );
 	t.end();
 } );

From 88ed5bfad4607f59db8c6ac1e50fbd6c92cc8309 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:39:09 +0100
Subject: [PATCH 132/213] Use ... symbols for rest tipes

---
 packages/docgen/src/get-param-type-as-string.js        | 5 ++++-
 packages/docgen/tests/test-get-param-type-as-string.js | 4 ++--
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index 22919bb1528f75..1a0d414b16fe90 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -2,10 +2,13 @@ const getType = function( param ) {
 	if ( param.type.type ) {
 		return getType( param.type );
 	} else if ( param.expression ) {
+		if ( param.type === 'RestType' ) {
+			return `...${ getType( param.expression ) }`;
+		}
 		return getType( param.expression );
 	} else if ( param.elements ) {
 		const types = param.elements.map( ( element ) => getType( element ) );
-		return types.join( ' | ' );
+		return `(${ types.join( ' | ' ) })`;
 	}
 
 	return param.name;
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
index f3ab07cbe329af..dd194d9650f390 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -53,7 +53,7 @@ test( 'getParamType from RestType', ( t ) => {
 		},
 		name: 'paramName',
 	} );
-	t.equal( type, 'Function' );
+	t.equal( type, '...Function' );
 	t.end();
 } );
 
@@ -73,6 +73,6 @@ test( 'getParamType from RestType with UnionType', ( t ) => {
 		},
 		name: 'paramName',
 	} );
-	t.equal( type, 'Object | string' );
+	t.equal( type, '...(Object | string)' );
 	t.end();
 } );

From c2dc8e234dd48b9c534d0ee4c116fc53b019762d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:41:29 +0100
Subject: [PATCH 133/213] Markdown: update to consider uniont and rest types

---
 packages/docgen/src/formatter.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 2542d6b756d101..b6a02881a09eac 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -10,7 +10,7 @@ const formatParams = ( params, docs ) => {
 		docs.push( '**Parameters**' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
-			( param ) => `\n- **${ param.name }** \`(${ getParamType( param ) })\`: ${ cleanSpaces( param.description ) }`
+			( param ) => `\n- **${ param.name }** \`${ getParamType( param ) }\`: ${ cleanSpaces( param.description ) }`
 		) );
 	}
 };

From 09763d7241eb3e8279ec744755964649e63d42dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:45:58 +0100
Subject: [PATCH 134/213] getParamType: add support for nullable params

---
 packages/docgen/src/get-param-type-as-string.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index 1a0d414b16fe90..5166eb8a61530f 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -4,6 +4,8 @@ const getType = function( param ) {
 	} else if ( param.expression ) {
 		if ( param.type === 'RestType' ) {
 			return `...${ getType( param.expression ) }`;
+		} else if ( param.type === 'NullableType' ) {
+			return `?${ getType( param.expression ) }`;
 		}
 		return getType( param.expression );
 	} else if ( param.elements ) {

From 28f06f469e669f93e0b957fdd3dd68b0aedb1ca4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:55:26 +0100
Subject: [PATCH 135/213] Markdown: add example tag to output

---
 packages/docgen/src/formatter.js | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index b6a02881a09eac..429a884d8df1c9 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -23,6 +23,17 @@ const cleanSpaces = ( paragraph ) =>
 		''
 	).trim();
 
+const formatExample = ( example, docs ) => {
+	if ( example && example.length === 1 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( '**Example**' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( example[ 0 ].description );
+	}
+};
+
 const formatOutput = ( output, docs ) => {
 	if ( output && output.length === 1 ) {
 		docs.push( '\n' );
@@ -55,6 +66,7 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( '\n' );
 			docs.push( cleanSpaces( artifact.description ) );
+			formatExample( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
 			formatParams( artifact.params, docs );
 			formatOutput( artifact.return, docs );
 			docs.push( '\n' );

From 78db25b51c03f6be54ae345bac772df843b5be29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 17:57:48 +0100
Subject: [PATCH 136/213] Update tests to API changes

---
 packages/docgen/tests/test-formatter-markdown.js       | 2 +-
 packages/docgen/tests/test-get-param-type-as-string.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index ed113790dafba5..e8933a7b6f9491 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -12,7 +12,7 @@ test( 'Formatter - returns markdown', ( t ) => {
 	const docs = formatter( [ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ] );
 	t.equal(
 		docs,
-		'# API\n\n## myDeclaration\n\nMy declaration example.\n\n\n'
+		'# API\n\n## myDeclaration\n\nMy declaration example.\n'
 	);
 	t.end();
 } );
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-param-type-as-string.js
index dd194d9650f390..08f5712a5a4a8c 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-param-type-as-string.js
@@ -36,7 +36,7 @@ test( 'getParamType from NullableType', ( t ) => {
 		},
 		name: 'paramName',
 	} );
-	t.equal( type, 'string' );
+	t.equal( type, '?string' );
 	t.end();
 } );
 

From a89f9e55857af43f7a0f8e0d97b9b185b091705e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 18:10:51 +0100
Subject: [PATCH 137/213] Prevent bug when paragraph is null

---
 packages/docgen/src/formatter.js | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 429a884d8df1c9..84a3df05366de6 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -16,12 +16,14 @@ const formatParams = ( params, docs ) => {
 };
 
 const cleanSpaces = ( paragraph ) =>
-	paragraph.split( '\n' ).map(
-		( sentence ) => sentence.trim()
-	).reduce(
-		( acc, current ) => acc + ' ' + current,
-		''
-	).trim();
+	paragraph ?
+		paragraph.split( '\n' ).map(
+			( sentence ) => sentence.trim()
+		).reduce(
+			( acc, current ) => acc + ' ' + current,
+			''
+		).trim() :
+		'';
 
 const formatExample = ( example, docs ) => {
 	if ( example && example.length === 1 ) {

From 796ad3f7f36e6a7e8b5a55afb5566948739ba592 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Feb 2019 19:47:20 +0100
Subject: [PATCH 138/213] Update coverage

---
 packages/docgen/coverage.md | 58 +++++++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 18 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index caebb57bfcf601..af5d5ebf52e92a 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -16,47 +16,69 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
+TO REVIEW:
+
+- [ ] dom-ready
+- [ ] e2e-test-utils
+- [ ] edit-post
+- [ ] editor
+
+TODO:
+
+- [ ] autop
+  - [ ] description contains HTML
+- [ ] babel-plugin-import-jsx-pragma - missing `@see` tag
+- [ ] blocks
+  - [ ] `getBlockSupport`, `isValidIcon`, `parseWithAttributeSchema` have `*` as param.type
+  - [ ] `getPhrasingContentSchema` misses `@see` tag
+  - [ ] `pastHandler` has optional params
+  - [ ] `setCategories` has `Object []` as a param type
+  - [ ] `unstable__*` should this be docummented?
+- [ ] date
+  - [ ] `format`, `date` have a null param.type
+- [ ] deprecated - missing `@type` tag
+- [ ] dom - missing `@see` tag in `caretRangeFromPoint`
+- [ ] element
+  - [ ] missing `@see` tag
+  - [ ] `isEmptyElement` has `*` as param.type
+- [ ] escape-html - missing `@link` tag `escapeAttribute`
+- [ ] i18n - missing `@see` tag
+- [ ] keycodes - has constants, missing `@type` tag
+- [ ] rich-text
+  - [ ] `concat` type param is `{...[object]}`
+  - [ ] `indentListItems` has param.description = null
+  - [ ] `LINE_SEPARATOR` is a constant
+  - [ ] `toHTMLString` a param is an object (create table?)
+  - [ ] `unstableToDom` is this supposed to go undocumented?
+- [ ] shortcode
+  - [ ] `string` has param.description = null
+  - [ ] description contains numbered list that is flattened
+- [ ] token-list - missing `@link` tag
+- [ ] viewport - missing `@see` tag
+
 DONE:
 
 - [x] a11y
 - [x] annotations
 - [x] api-fetch
-- [x] autop
-- [x] babel-plugin-import-jsx-pragma
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
 - [x] block-serialization-spec-parser
-- [x] blocks
 - [x] components
 - [x] compose
 - [x] core-data
 - [x] data
-- [x] date
-- [x] deprecated
-- [x] dom
-- [x] dom-ready
-- [x] e2e-test-utils
-- [x] edit-post
-- [x] editor
-- [x] element
-- [x] escape-html
 - [x] format-library
 - [x] hooks
 - [x] html-entities
-- [x] i18n
 - [x] jest-console
 - [x] jest-puppeteer-axe
-- [x] keycodes
 - [x] list-reusable-blocks
 - [x] notices
 - [x] nux
 - [x] plugins
 - [x] priority-queue
 - [x] redux-routine
-- [x] rich-text
-- [x] shortcode
-- [x] token-list
 - [x] url
-- [x] viewport
 - [x] wordcount

From 3e3810f7dcdea70051dd1af29bfe4d13f165f628 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:09:56 +0100
Subject: [PATCH 139/213] Update coverage

---
 packages/docgen/coverage.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index af5d5ebf52e92a..e1ec49c11cfb57 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -16,13 +16,6 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
-TO REVIEW:
-
-- [ ] dom-ready
-- [ ] e2e-test-utils
-- [ ] edit-post
-- [ ] editor
-
 TODO:
 
 - [ ] autop
@@ -38,6 +31,11 @@ TODO:
   - [ ] `format`, `date` have a null param.type
 - [ ] deprecated - missing `@type` tag
 - [ ] dom - missing `@see` tag in `caretRangeFromPoint`
+- [ ] e2e-test-utils
+  - [ ] `mockOrTransform` contains undefined as a param.type
+  - [ ] `setUpResponseMocking` has long description mixed with example
+- [ ] editor
+  - [ ] `userMentionsCompleter` - missing `@type` tag
 - [ ] element
   - [ ] missing `@see` tag
   - [ ] `isEmptyElement` has `*` as param.type
@@ -69,6 +67,8 @@ DONE:
 - [x] compose
 - [x] core-data
 - [x] data
+- [x] dom-ready
+- [x] edit-post
 - [x] format-library
 - [x] hooks
 - [x] html-entities

From 5f2cf4a41c0cd1c2aae6b228ef01a4deda9fffc6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:18:44 +0100
Subject: [PATCH 140/213] Add support for see tag

---
 packages/docgen/coverage.md      | 24 +++++++----------
 packages/docgen/src/formatter.js | 44 ++++++++++++++++++++------------
 2 files changed, 37 insertions(+), 31 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index e1ec49c11cfb57..493822878c814a 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -18,29 +18,21 @@ Packages outside of scope:
 
 TODO:
 
-- [ ] autop
-  - [ ] description contains HTML
-- [ ] babel-plugin-import-jsx-pragma - missing `@see` tag
+- [ ] autop - description contains HTML
 - [ ] blocks
   - [ ] `getBlockSupport`, `isValidIcon`, `parseWithAttributeSchema` have `*` as param.type
-  - [ ] `getPhrasingContentSchema` misses `@see` tag
   - [ ] `pastHandler` has optional params
   - [ ] `setCategories` has `Object []` as a param type
   - [ ] `unstable__*` should this be docummented?
-- [ ] date
-  - [ ] `format`, `date` have a null param.type
+- [ ] date - `format`, `date` have a null param.type
 - [ ] deprecated - missing `@type` tag
-- [ ] dom - missing `@see` tag in `caretRangeFromPoint`
 - [ ] e2e-test-utils
   - [ ] `mockOrTransform` contains undefined as a param.type
   - [ ] `setUpResponseMocking` has long description mixed with example
-- [ ] editor
-  - [ ] `userMentionsCompleter` - missing `@type` tag
-- [ ] element
-  - [ ] missing `@see` tag
-  - [ ] `isEmptyElement` has `*` as param.type
+- [ ] editor - `userMentionsCompleter` - missing `@type` tag
+- [ ] element - `isEmptyElement` has `*` as param.type
 - [ ] escape-html - missing `@link` tag `escapeAttribute`
-- [ ] i18n - missing `@see` tag
+- [ ] i18n - `sprintf` has `string[]` as a param type
 - [ ] keycodes - has constants, missing `@type` tag
 - [ ] rich-text
   - [ ] `concat` type param is `{...[object]}`
@@ -52,13 +44,13 @@ TODO:
   - [ ] `string` has param.description = null
   - [ ] description contains numbered list that is flattened
 - [ ] token-list - missing `@link` tag
-- [ ] viewport - missing `@see` tag
 
 DONE:
 
 - [x] a11y
 - [x] annotations
 - [x] api-fetch
+- [x] babel-plugin-import-jsx-pragma
 - [x] blob
 - [x] block-library
 - [x] block-serialization-default-parser
@@ -67,6 +59,7 @@ DONE:
 - [x] compose
 - [x] core-data
 - [x] data
+- [x] dom
 - [x] dom-ready
 - [x] edit-post
 - [x] format-library
@@ -81,4 +74,5 @@ DONE:
 - [x] priority-queue
 - [x] redux-routine
 - [x] url
-- [x] wordcount
+- [x] viewport
+- [x] wordcount
\ No newline at end of file
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 84a3df05366de6..6e0904d55598d1 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -3,7 +3,17 @@
  */
 const getParamType = require( './get-param-type-as-string' );
 
-const formatParams = ( params, docs ) => {
+const cleanSpaces = ( paragraph ) =>
+	paragraph ?
+		paragraph.split( '\n' ).map(
+			( sentence ) => sentence.trim()
+		).reduce(
+			( acc, current ) => acc + ' ' + current,
+			''
+		).trim() :
+		'';
+
+const formatParamTags = ( params, docs ) => {
 	if ( params && params.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
@@ -15,17 +25,7 @@ const formatParams = ( params, docs ) => {
 	}
 };
 
-const cleanSpaces = ( paragraph ) =>
-	paragraph ?
-		paragraph.split( '\n' ).map(
-			( sentence ) => sentence.trim()
-		).reduce(
-			( acc, current ) => acc + ' ' + current,
-			''
-		).trim() :
-		'';
-
-const formatExample = ( example, docs ) => {
+const formatExampleTag = ( example, docs ) => {
 	if ( example && example.length === 1 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
@@ -36,7 +36,7 @@ const formatExample = ( example, docs ) => {
 	}
 };
 
-const formatOutput = ( output, docs ) => {
+const formatReturnTag = ( output, docs ) => {
 	if ( output && output.length === 1 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
@@ -47,6 +47,17 @@ const formatOutput = ( output, docs ) => {
 	}
 };
 
+const formatSeeTag = ( tag, docs ) => {
+	if ( tag && tag.length === 1 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( '**Related**' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( `- ${ tag[ 0 ].description }` );
+	}
+};
+
 module.exports = function( artifacts ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
@@ -68,9 +79,10 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( '\n' );
 			docs.push( cleanSpaces( artifact.description ) );
-			formatExample( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
-			formatParams( artifact.params, docs );
-			formatOutput( artifact.return, docs );
+			formatSeeTag( artifact.tags.filter( ( tag ) => tag.title === 'see' ), docs );
+			formatExampleTag( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
+			formatParamTags( artifact.params, docs );
+			formatReturnTag( artifact.return, docs );
 			docs.push( '\n' );
 			docs.push( '\n' );
 		} );

From ca2fde94e624e894d7d5995b03e045493c8c4290 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:39:43 +0100
Subject: [PATCH 141/213] Add support for link tag

---
 packages/docgen/coverage.md      |  4 ++--
 packages/docgen/src/formatter.js | 13 +++++++++----
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 493822878c814a..188e6e7c969eec 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -31,7 +31,6 @@ TODO:
   - [ ] `setUpResponseMocking` has long description mixed with example
 - [ ] editor - `userMentionsCompleter` - missing `@type` tag
 - [ ] element - `isEmptyElement` has `*` as param.type
-- [ ] escape-html - missing `@link` tag `escapeAttribute`
 - [ ] i18n - `sprintf` has `string[]` as a param type
 - [ ] keycodes - has constants, missing `@type` tag
 - [ ] rich-text
@@ -43,7 +42,6 @@ TODO:
 - [ ] shortcode
   - [ ] `string` has param.description = null
   - [ ] description contains numbered list that is flattened
-- [ ] token-list - missing `@link` tag
 
 DONE:
 
@@ -62,6 +60,7 @@ DONE:
 - [x] dom
 - [x] dom-ready
 - [x] edit-post
+- [x] escape-html
 - [x] format-library
 - [x] hooks
 - [x] html-entities
@@ -73,6 +72,7 @@ DONE:
 - [x] plugins
 - [x] priority-queue
 - [x] redux-routine
+- [x] token-list
 - [x] url
 - [x] viewport
 - [x] wordcount
\ No newline at end of file
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 6e0904d55598d1..ef75c96c757fb2 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -47,14 +47,16 @@ const formatReturnTag = ( output, docs ) => {
 	}
 };
 
-const formatSeeTag = ( tag, docs ) => {
-	if ( tag && tag.length === 1 ) {
+const formatSeeAndLinkTags = ( tags, docs ) => {
+	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
 		docs.push( '**Related**' );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( `- ${ tag[ 0 ].description }` );
+		docs.push( ...tags.map(
+			( tag ) => `\n- ${ tag.description }`
+		) );
 	}
 };
 
@@ -79,7 +81,10 @@ module.exports = function( artifacts ) {
 			docs.push( '\n' );
 			docs.push( '\n' );
 			docs.push( cleanSpaces( artifact.description ) );
-			formatSeeTag( artifact.tags.filter( ( tag ) => tag.title === 'see' ), docs );
+			formatSeeAndLinkTags(
+				artifact.tags.filter( ( tag ) => ( tag.title === 'see' ) || ( tag.title === 'link' ) ),
+				docs
+			);
 			formatExampleTag( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
 			formatParamTags( artifact.params, docs );
 			formatReturnTag( artifact.return, docs );

From 2a2743a5ad1b964eded5381b5f331c52ef68636f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:47:49 +0100
Subject: [PATCH 142/213] Allow having several examples for one symbol

---
 packages/docgen/src/formatter.js | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index ef75c96c757fb2..78313436720861 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -25,14 +25,16 @@ const formatParamTags = ( params, docs ) => {
 	}
 };
 
-const formatExampleTag = ( example, docs ) => {
-	if ( example && example.length === 1 ) {
+const formatExampleTag = ( tags, docs ) => {
+	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( '**Example**' );
+		docs.push( '**Usage**' );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( example[ 0 ].description );
+		docs.push( ...tags.map(
+			( tag ) => `${ tag.description }`
+		).join( '\n\n' ) );
 	}
 };
 

From 5f600346fd00969827efb378a57fea68d1f8b2d8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:49:49 +0100
Subject: [PATCH 143/213] Less space between types: (object|string)

---
 packages/docgen/src/get-param-type-as-string.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-param-type-as-string.js
index 5166eb8a61530f..18d923f243a144 100644
--- a/packages/docgen/src/get-param-type-as-string.js
+++ b/packages/docgen/src/get-param-type-as-string.js
@@ -10,7 +10,7 @@ const getType = function( param ) {
 		return getType( param.expression );
 	} else if ( param.elements ) {
 		const types = param.elements.map( ( element ) => getType( element ) );
-		return `(${ types.join( ' | ' ) })`;
+		return `(${ types.join( '|' ) })`;
 	}
 
 	return param.name;

From dbae6fe2cbdb73d405791da0be7c8e40df7d992a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 14:54:55 +0100
Subject: [PATCH 144/213] Keep description format as it is

---
 packages/docgen/src/formatter.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 78313436720861..b20f6549764c14 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -82,7 +82,7 @@ module.exports = function( artifacts ) {
 			docs.push( `## ${ artifact.name }` );
 			docs.push( '\n' );
 			docs.push( '\n' );
-			docs.push( cleanSpaces( artifact.description ) );
+			docs.push( artifact.description );
 			formatSeeAndLinkTags(
 				artifact.tags.filter( ( tag ) => ( tag.title === 'see' ) || ( tag.title === 'link' ) ),
 				docs

From b76e0014be1ef57601f423c5d2b2ebd6d87a29a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 16:43:15 +0100
Subject: [PATCH 145/213] Add support for type tag

---
 packages/docgen/coverage.md      | 48 ++++++++++++++++----------------
 packages/docgen/src/formatter.js | 22 +++++++++++----
 2 files changed, 41 insertions(+), 29 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 188e6e7c969eec..3d6a0a198146c4 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -16,32 +16,29 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
+WIP:
+
+
+
 TODO:
 
-- [ ] autop - description contains HTML
-- [ ] blocks
-  - [ ] `getBlockSupport`, `isValidIcon`, `parseWithAttributeSchema` have `*` as param.type
-  - [ ] `pastHandler` has optional params
-  - [ ] `setCategories` has `Object []` as a param type
-  - [ ] `unstable__*` should this be docummented?
-- [ ] date - `format`, `date` have a null param.type
-- [ ] deprecated - missing `@type` tag
-- [ ] e2e-test-utils
-  - [ ] `mockOrTransform` contains undefined as a param.type
-  - [ ] `setUpResponseMocking` has long description mixed with example
-- [ ] editor - `userMentionsCompleter` - missing `@type` tag
-- [ ] element - `isEmptyElement` has `*` as param.type
-- [ ] i18n - `sprintf` has `string[]` as a param type
-- [ ] keycodes - has constants, missing `@type` tag
-- [ ] rich-text
-  - [ ] `concat` type param is `{...[object]}`
-  - [ ] `indentListItems` has param.description = null
-  - [ ] `LINE_SEPARATOR` is a constant
-  - [ ] `toHTMLString` a param is an object (create table?)
-  - [ ] `unstableToDom` is this supposed to go undocumented?
-- [ ] shortcode
-  - [ ] `string` has param.description = null
-  - [ ] description contains numbered list that is flattened
+- [ ] autop `description` contains HTML
+- [ ] blocks `getBlockSupport`, `isValidIcon`, `parseWithAttributeSchema` have `*` as `@param`.type
+- [ ] blocks `pastHandler` has optional `@param`
+- [ ] blocks `setCategories` has `Object []` as a `@param` type
+- [ ] blocks `unstable__*` should this be docummented?
+- [ ] date `format`, `date` have a null `@param`.type
+- [ ] e2e-test-utils `mockOrTransform` contains undefined as a `@param`.type
+- [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
+- [ ] element `isEmptyElement` has `*` as `@param`.type
+- [ ] keycodes `CONSTANTS`
+- [ ] i18n `sprintf` has `string[]` as a `@param` type
+- [ ] rich-text `concat` type `@param` is `{...[object]}`
+- [ ] rich-text `indentListItems` has `@param`.description = null
+- [ ] rich-text `LINE_SEPARATOR` is a constant
+- [ ] rich-text `toHTMLString` `@param` is an object (create table?)
+- [ ] rich-text `unstableToDom` is this supposed to go undocumented?
+- [ ] shortcode `string` has `@param`.description = null
 
 DONE:
 
@@ -57,15 +54,18 @@ DONE:
 - [x] compose
 - [x] core-data
 - [x] data
+- [x] deprecated
 - [x] dom
 - [x] dom-ready
 - [x] edit-post
+- [x] editor
 - [x] escape-html
 - [x] format-library
 - [x] hooks
 - [x] html-entities
 - [x] jest-console
 - [x] jest-puppeteer-axe
+- [x] keycodes
 - [x] list-reusable-blocks
 - [x] notices
 - [x] nux
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index b20f6549764c14..b59b92c069e35b 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-const getParamType = require( './get-param-type-as-string' );
+const getType = require( './get-param-type-as-string' );
 
 const cleanSpaces = ( paragraph ) =>
 	paragraph ?
@@ -20,7 +20,7 @@ const formatParamTags = ( params, docs ) => {
 		docs.push( '**Parameters**' );
 		docs.push( '\n' );
 		docs.push( ...params.map(
-			( param ) => `\n- **${ param.name }** \`${ getParamType( param ) }\`: ${ cleanSpaces( param.description ) }`
+			( param ) => `\n- **${ param.name }** \`${ getType( param ) }\`: ${ cleanSpaces( param.description ) }`
 		) );
 	}
 };
@@ -38,14 +38,25 @@ const formatExampleTag = ( tags, docs ) => {
 	}
 };
 
-const formatReturnTag = ( output, docs ) => {
-	if ( output && output.length === 1 ) {
+const formatReturnTag = ( tag, docs ) => {
+	if ( tag && tag.length === 1 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
 		docs.push( '**Returns**' );
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( `\`${ getParamType( output[ 0 ] ) }\` ${ cleanSpaces( output[ 0 ].description ) }` );
+		docs.push( `\`${ getType( tag[ 0 ] ) }\` ${ cleanSpaces( tag[ 0 ].description ) }` );
+	}
+};
+
+const formatTypeTag = ( tag, docs ) => {
+	if ( tag && tag.length === 1 ) {
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( '**Type**' );
+		docs.push( '\n' );
+		docs.push( '\n' );
+		docs.push( `\`${ getType( tag[ 0 ] ) }\` ${ cleanSpaces( tag[ 0 ].description ) }` );
 	}
 };
 
@@ -88,6 +99,7 @@ module.exports = function( artifacts ) {
 				docs
 			);
 			formatExampleTag( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
+			formatTypeTag( artifact.tags.filter( ( tag ) => tag.title === 'type' ), docs );
 			formatParamTags( artifact.params, docs );
 			formatReturnTag( artifact.return, docs );
 			docs.push( '\n' );

From 9d3dcc236e40715079b061ce5ad3f65bac2d8f7b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 16:51:13 +0100
Subject: [PATCH 146/213] Rename get-param-type-as-string to get-type-as-string

---
 packages/docgen/package.json                           |  2 +-
 packages/docgen/src/formatter.js                       |  2 +-
 ...t-param-type-as-string.js => get-type-as-string.js} |  0
 ...am-type-as-string.js => test-get-type-as-string.js} | 10 +++++-----
 4 files changed, 7 insertions(+), 7 deletions(-)
 rename packages/docgen/src/{get-param-type-as-string.js => get-type-as-string.js} (100%)
 rename packages/docgen/tests/{test-get-param-type-as-string.js => test-get-type-as-string.js} (87%)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 92ead305839647..c13a62fe92a6c2 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -32,6 +32,6 @@
 		"test:formatter": "tape tests/test-formatter-markdown.js | faucet",
 		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
 		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet",
-		"test:get-param-type-as-string": "tape tests/test-get-param-type-as-string.js | faucet"
+		"test:get-type-as-string": "tape tests/test-get-type-as-string.js | faucet"
 	}
 }
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index b59b92c069e35b..711901e814b532 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-const getType = require( './get-param-type-as-string' );
+const getType = require( './get-type-as-string' );
 
 const cleanSpaces = ( paragraph ) =>
 	paragraph ?
diff --git a/packages/docgen/src/get-param-type-as-string.js b/packages/docgen/src/get-type-as-string.js
similarity index 100%
rename from packages/docgen/src/get-param-type-as-string.js
rename to packages/docgen/src/get-type-as-string.js
diff --git a/packages/docgen/tests/test-get-param-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
similarity index 87%
rename from packages/docgen/tests/test-get-param-type-as-string.js
rename to packages/docgen/tests/test-get-type-as-string.js
index 08f5712a5a4a8c..e5d350e287cdd6 100644
--- a/packages/docgen/tests/test-get-param-type-as-string.js
+++ b/packages/docgen/tests/test-get-type-as-string.js
@@ -6,10 +6,10 @@ const test = require( 'tape' );
 /**
  * Internal dependencies.
  */
-const getParamType = require( '../src/get-param-type-as-string' );
+const getType = require( '../src/get-type-as-string' );
 
 test( 'getParamType from NameExpression', ( t ) => {
-	const type = getParamType( {
+	const type = getType( {
 		title: 'param',
 		description: 'description',
 		type: {
@@ -23,7 +23,7 @@ test( 'getParamType from NameExpression', ( t ) => {
 } );
 
 test( 'getParamType from NullableType', ( t ) => {
-	const type = getParamType( {
+	const type = getType( {
 		title: 'param',
 		description: 'description',
 		type: {
@@ -41,7 +41,7 @@ test( 'getParamType from NullableType', ( t ) => {
 } );
 
 test( 'getParamType from RestType', ( t ) => {
-	const type = getParamType( {
+	const type = getType( {
 		title: 'param',
 		description: 'description',
 		type: {
@@ -58,7 +58,7 @@ test( 'getParamType from RestType', ( t ) => {
 } );
 
 test( 'getParamType from RestType with UnionType', ( t ) => {
-	const type = getParamType( {
+	const type = getType( {
 		title: 'param',
 		description: 'description',
 		type: {

From c1493200452fd201049afab9d18ce6c8ae5e54c4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 16:51:41 +0100
Subject: [PATCH 147/213] Adapt test to API changes

---
 packages/docgen/tests/test-get-type-as-string.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/tests/test-get-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
index e5d350e287cdd6..78eb72796246fb 100644
--- a/packages/docgen/tests/test-get-type-as-string.js
+++ b/packages/docgen/tests/test-get-type-as-string.js
@@ -73,6 +73,6 @@ test( 'getParamType from RestType with UnionType', ( t ) => {
 		},
 		name: 'paramName',
 	} );
-	t.equal( type, '...(Object | string)' );
+	t.equal( type, '...(Object|string)' );
 	t.end();
 } );

From 88004d91246e1562f97b41fe74c7d51b54479621 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 16:55:17 +0100
Subject: [PATCH 148/213] Add support for * type

---
 packages/docgen/coverage.md                   |  5 +----
 packages/docgen/src/get-type-as-string.js     |  2 ++
 .../docgen/tests/test-get-type-as-string.js   | 21 +++++++++++++++----
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 3d6a0a198146c4..10b5abc664ed95 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -18,19 +18,15 @@ Packages outside of scope:
 
 WIP:
 
-
-
 TODO:
 
 - [ ] autop `description` contains HTML
-- [ ] blocks `getBlockSupport`, `isValidIcon`, `parseWithAttributeSchema` have `*` as `@param`.type
 - [ ] blocks `pastHandler` has optional `@param`
 - [ ] blocks `setCategories` has `Object []` as a `@param` type
 - [ ] blocks `unstable__*` should this be docummented?
 - [ ] date `format`, `date` have a null `@param`.type
 - [ ] e2e-test-utils `mockOrTransform` contains undefined as a `@param`.type
 - [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
-- [ ] element `isEmptyElement` has `*` as `@param`.type
 - [ ] keycodes `CONSTANTS`
 - [ ] i18n `sprintf` has `string[]` as a `@param` type
 - [ ] rich-text `concat` type `@param` is `{...[object]}`
@@ -59,6 +55,7 @@ DONE:
 - [x] dom-ready
 - [x] edit-post
 - [x] editor
+- [x] element
 - [x] escape-html
 - [x] format-library
 - [x] hooks
diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js
index 18d923f243a144..4873dc85ab40c1 100644
--- a/packages/docgen/src/get-type-as-string.js
+++ b/packages/docgen/src/get-type-as-string.js
@@ -11,6 +11,8 @@ const getType = function( param ) {
 	} else if ( param.elements ) {
 		const types = param.elements.map( ( element ) => getType( element ) );
 		return `(${ types.join( '|' ) })`;
+	} else if ( param.type === 'AllLiteral' ) {
+		return '*';
 	}
 
 	return param.name;
diff --git a/packages/docgen/tests/test-get-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
index 78eb72796246fb..c9ebfc9a8425db 100644
--- a/packages/docgen/tests/test-get-type-as-string.js
+++ b/packages/docgen/tests/test-get-type-as-string.js
@@ -8,7 +8,7 @@ const test = require( 'tape' );
  */
 const getType = require( '../src/get-type-as-string' );
 
-test( 'getParamType from NameExpression', ( t ) => {
+test( 'getType from NameExpression', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -22,7 +22,20 @@ test( 'getParamType from NameExpression', ( t ) => {
 	t.end();
 } );
 
-test( 'getParamType from NullableType', ( t ) => {
+test( 'getType from AllLiteral', ( t ) => {
+	const type = getType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'AllLiteral',
+		},
+		name: 'paramName',
+	} );
+	t.equal( type, '*' );
+	t.end();
+} );
+
+test( 'getType from NullableType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -40,7 +53,7 @@ test( 'getParamType from NullableType', ( t ) => {
 	t.end();
 } );
 
-test( 'getParamType from RestType', ( t ) => {
+test( 'getType from RestType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -57,7 +70,7 @@ test( 'getParamType from RestType', ( t ) => {
 	t.end();
 } );
 
-test( 'getParamType from RestType with UnionType', ( t ) => {
+test( 'getType from RestType with UnionType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',

From b8e21b0f2c39380f527b8d7b9b1660fef8e696cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 17:46:31 +0100
Subject: [PATCH 149/213] Add support for type applications

---
 packages/docgen/coverage.md                   | 13 ++++++----
 packages/docgen/src/get-type-as-string.js     |  4 +++
 .../docgen/tests/test-get-type-as-string.js   | 26 +++++++++++++++++++
 3 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 10b5abc664ed95..05cc4c08d944de 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -16,23 +16,25 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
+Fix JSDoc manually:
+
+- [ ] rich-text `concat` type `@param` is `{...[object]}`
+- [ ] autop `description` contains HTML
+
 WIP:
 
+- [ ] rich-text `toHTMLString` `@param` is an object (create table?)
+
 TODO:
 
-- [ ] autop `description` contains HTML
 - [ ] blocks `pastHandler` has optional `@param`
-- [ ] blocks `setCategories` has `Object []` as a `@param` type
 - [ ] blocks `unstable__*` should this be docummented?
 - [ ] date `format`, `date` have a null `@param`.type
 - [ ] e2e-test-utils `mockOrTransform` contains undefined as a `@param`.type
 - [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
 - [ ] keycodes `CONSTANTS`
-- [ ] i18n `sprintf` has `string[]` as a `@param` type
-- [ ] rich-text `concat` type `@param` is `{...[object]}`
 - [ ] rich-text `indentListItems` has `@param`.description = null
 - [ ] rich-text `LINE_SEPARATOR` is a constant
-- [ ] rich-text `toHTMLString` `@param` is an object (create table?)
 - [ ] rich-text `unstableToDom` is this supposed to go undocumented?
 - [ ] shortcode `string` has `@param`.description = null
 
@@ -60,6 +62,7 @@ DONE:
 - [x] format-library
 - [x] hooks
 - [x] html-entities
+- [x] i18n
 - [x] jest-console
 - [x] jest-puppeteer-axe
 - [x] keycodes
diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js
index 4873dc85ab40c1..e1b9a5319a584f 100644
--- a/packages/docgen/src/get-type-as-string.js
+++ b/packages/docgen/src/get-type-as-string.js
@@ -6,6 +6,10 @@ const getType = function( param ) {
 			return `...${ getType( param.expression ) }`;
 		} else if ( param.type === 'NullableType' ) {
 			return `?${ getType( param.expression ) }`;
+		} else if ( param.type === 'TypeApplication' ) {
+			return `${ getType( param.expression ) }<${
+				param.applications.map( ( application ) => getType( application ) ).join( ',' )
+			}>`;
 		}
 		return getType( param.expression );
 	} else if ( param.elements ) {
diff --git a/packages/docgen/tests/test-get-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
index c9ebfc9a8425db..049f15ffc89100 100644
--- a/packages/docgen/tests/test-get-type-as-string.js
+++ b/packages/docgen/tests/test-get-type-as-string.js
@@ -35,6 +35,32 @@ test( 'getType from AllLiteral', ( t ) => {
 	t.end();
 } );
 
+test( 'getType with applications', ( t ) => {
+	const type = getType( {
+		title: 'param',
+		description: 'description',
+		type: {
+			type: 'TypeApplication',
+			expression: {
+				type: 'NameExpression',
+				name: 'Array',
+			},
+			applications: [
+				{
+					type: 'NameExpression',
+					name: 'Object',
+				},
+				{
+					type: 'NameExpression',
+					name: 'String',
+				},
+			],
+		},
+	} );
+	t.equal( type, 'Array<Object,String>' );
+	t.end();
+} );
+
 test( 'getType from NullableType', ( t ) => {
 	const type = getType( {
 		title: 'param',

From d8c8a18a43bf588b1844c0615fbf21ca148224e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 17:57:28 +0100
Subject: [PATCH 150/213] Add support for NullLiteral

---
 packages/docgen/coverage.md               | 17 ++++++++++++-----
 packages/docgen/src/get-type-as-string.js |  2 ++
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 05cc4c08d944de..f97737fd2db54b 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -18,18 +18,24 @@ Packages outside of scope:
 
 Fix JSDoc manually:
 
-- [ ] rich-text `concat` type `@param` is `{...[object]}`
 - [ ] autop `description` contains HTML
+- [ ] rich-text `concat` type `@param` is `{...[object]}`. Should be
 
-WIP:
-
-- [ ] rich-text `toHTMLString` `@param` is an object (create table?)
+```js
+/**
+ * Combine all Rich Text values into one. This is similar to
+ * `String.prototype.concat`.
+ *
+ * @param {...Object} values Objects to combine.
+ *
+ * @return {Object} A new value combining all given records.
+ */
+```
 
 TODO:
 
 - [ ] blocks `pastHandler` has optional `@param`
 - [ ] blocks `unstable__*` should this be docummented?
-- [ ] date `format`, `date` have a null `@param`.type
 - [ ] e2e-test-utils `mockOrTransform` contains undefined as a `@param`.type
 - [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
 - [ ] keycodes `CONSTANTS`
@@ -52,6 +58,7 @@ DONE:
 - [x] compose
 - [x] core-data
 - [x] data
+- [x] date
 - [x] deprecated
 - [x] dom
 - [x] dom-ready
diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js
index e1b9a5319a584f..6a05d7eb53daaf 100644
--- a/packages/docgen/src/get-type-as-string.js
+++ b/packages/docgen/src/get-type-as-string.js
@@ -17,6 +17,8 @@ const getType = function( param ) {
 		return `(${ types.join( '|' ) })`;
 	} else if ( param.type === 'AllLiteral' ) {
 		return '*';
+	} else if ( param.type === 'NullLiteral' ) {
+		return 'null';
 	}
 
 	return param.name;

From 3b3cd21dbcd7ed8201483e32f56443bf908add40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Feb 2019 18:17:05 +0100
Subject: [PATCH 151/213] Add support for UndefinedLiteral and optional
 parameters

---
 packages/docgen/coverage.md                 | 8 +++-----
 packages/docgen/src/get-jsdoc-from-token.js | 6 +++++-
 packages/docgen/src/get-type-as-string.js   | 4 ++++
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index f97737fd2db54b..3f0a9ace200feb 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -19,6 +19,7 @@ Packages outside of scope:
 Fix JSDoc manually:
 
 - [ ] autop `description` contains HTML
+- [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
 - [ ] rich-text `concat` type `@param` is `{...[object]}`. Should be
 
 ```js
@@ -34,15 +35,10 @@ Fix JSDoc manually:
 
 TODO:
 
-- [ ] blocks `pastHandler` has optional `@param`
 - [ ] blocks `unstable__*` should this be docummented?
-- [ ] e2e-test-utils `mockOrTransform` contains undefined as a `@param`.type
-- [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
 - [ ] keycodes `CONSTANTS`
-- [ ] rich-text `indentListItems` has `@param`.description = null
 - [ ] rich-text `LINE_SEPARATOR` is a constant
 - [ ] rich-text `unstableToDom` is this supposed to go undocumented?
-- [ ] shortcode `string` has `@param`.description = null
 
 DONE:
 
@@ -62,6 +58,7 @@ DONE:
 - [x] deprecated
 - [x] dom
 - [x] dom-ready
+- [x] e2e-test-utils
 - [x] edit-post
 - [x] editor
 - [x] element
@@ -79,6 +76,7 @@ DONE:
 - [x] plugins
 - [x] priority-queue
 - [x] redux-routine
+- [x] shortcode
 - [x] token-list
 - [x] url
 - [x] viewport
diff --git a/packages/docgen/src/get-jsdoc-from-token.js b/packages/docgen/src/get-jsdoc-from-token.js
index 1c4bb9885c0b93..af70d64af63a54 100644
--- a/packages/docgen/src/get-jsdoc-from-token.js
+++ b/packages/docgen/src/get-jsdoc-from-token.js
@@ -12,7 +12,11 @@ module.exports = function( token ) {
 	let jsdoc;
 	const comments = getLeadingComments( token );
 	if ( comments && comments.startsWith( '*\n' ) ) {
-		jsdoc = doctrine.parse( comments, { unwrap: true, recoverable: true } );
+		jsdoc = doctrine.parse( comments, {
+			unwrap: true,
+			recoverable: true,
+			sloppy: true,
+		} );
 	}
 	return jsdoc;
 };
diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js
index 6a05d7eb53daaf..f663850a188bf1 100644
--- a/packages/docgen/src/get-type-as-string.js
+++ b/packages/docgen/src/get-type-as-string.js
@@ -10,6 +10,8 @@ const getType = function( param ) {
 			return `${ getType( param.expression ) }<${
 				param.applications.map( ( application ) => getType( application ) ).join( ',' )
 			}>`;
+		} else if ( param.type === 'OptionalType' ) {
+			return `[${ getType( param.expression ) }]`;
 		}
 		return getType( param.expression );
 	} else if ( param.elements ) {
@@ -19,6 +21,8 @@ const getType = function( param ) {
 		return '*';
 	} else if ( param.type === 'NullLiteral' ) {
 		return 'null';
+	} else if ( param.type === 'UndefinedLiteral' ) {
+		return 'undefined';
 	}
 
 	return param.name;

From f485e71d03f884b058c0c96015fe299e593a4c0a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 8 Feb 2019 16:58:40 +0100
Subject: [PATCH 152/213] Add support for default values

---
 packages/docgen/src/get-type-as-string.js | 35 +++++++++++++++--------
 1 file changed, 23 insertions(+), 12 deletions(-)

diff --git a/packages/docgen/src/get-type-as-string.js b/packages/docgen/src/get-type-as-string.js
index f663850a188bf1..64bfaefd00d529 100644
--- a/packages/docgen/src/get-type-as-string.js
+++ b/packages/docgen/src/get-type-as-string.js
@@ -1,31 +1,42 @@
-const getType = function( param ) {
+const maybeAddDefault = function( value, defaultValue ) {
+	if ( defaultValue ) {
+		return `value=${ defaultValue }`;
+	}
+	return value;
+};
+
+const getType = function( param, defaultValue ) {
+	if ( ! defaultValue ) {
+		defaultValue = param.default;
+	}
+
 	if ( param.type.type ) {
-		return getType( param.type );
+		return getType( param.type, defaultValue );
 	} else if ( param.expression ) {
 		if ( param.type === 'RestType' ) {
-			return `...${ getType( param.expression ) }`;
+			return `...${ getType( param.expression, defaultValue ) }`;
 		} else if ( param.type === 'NullableType' ) {
-			return `?${ getType( param.expression ) }`;
+			return `?${ getType( param.expression, defaultValue ) }`;
 		} else if ( param.type === 'TypeApplication' ) {
-			return `${ getType( param.expression ) }<${
+			return `${ getType( param.expression, defaultValue ) }<${
 				param.applications.map( ( application ) => getType( application ) ).join( ',' )
 			}>`;
 		} else if ( param.type === 'OptionalType' ) {
-			return `[${ getType( param.expression ) }]`;
+			return `[${ getType( param.expression, defaultValue ) }]`;
 		}
-		return getType( param.expression );
+		return getType( param.expression, defaultValue );
 	} else if ( param.elements ) {
 		const types = param.elements.map( ( element ) => getType( element ) );
-		return `(${ types.join( '|' ) })`;
+		return maybeAddDefault( `(${ types.join( '|' ) })`, defaultValue );
 	} else if ( param.type === 'AllLiteral' ) {
-		return '*';
+		return maybeAddDefault( '*', defaultValue );
 	} else if ( param.type === 'NullLiteral' ) {
-		return 'null';
+		return maybeAddDefault( 'null', defaultValue );
 	} else if ( param.type === 'UndefinedLiteral' ) {
-		return 'undefined';
+		return maybeAddDefault( 'undefined', defaultValue );
 	}
 
-	return param.name;
+	return maybeAddDefault( param.name, defaultValue );
 };
 
 module.exports = function( param ) {

From bf2a2d469914d826a0bfd9efe70c67459ce8d096 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 8 Feb 2019 17:04:43 +0100
Subject: [PATCH 153/213] Add support for deprecated tag

---
 packages/docgen/src/formatter.js | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index 711901e814b532..fd553e91dbcf58 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -73,6 +73,15 @@ const formatSeeAndLinkTags = ( tags, docs ) => {
 	}
 };
 
+const formatDeprecated = ( tags, docs ) => {
+	if ( tags && tags.length > 0 ) {
+		docs.push( '\n' );
+		docs.push( ...tags.map(
+			( tag ) => `\n> **Deprecated** ${ cleanSpaces( tag.description ) }`
+		) );
+	}
+};
+
 module.exports = function( artifacts ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
@@ -91,6 +100,7 @@ module.exports = function( artifacts ) {
 	if ( artifacts && artifacts.length > 0 ) {
 		artifacts.forEach( ( artifact ) => {
 			docs.push( `## ${ artifact.name }` );
+			formatDeprecated( artifact.tags.filter( ( tag ) => tag.title === 'deprecated' ), docs );
 			docs.push( '\n' );
 			docs.push( '\n' );
 			docs.push( artifact.description );

From 6753293a162d381e651b8483ce49a62bdb718f72 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 8 Feb 2019 17:22:42 +0100
Subject: [PATCH 154/213] params and return tags are no longer special

---
 packages/docgen/src/formatter.js              | 12 +--
 .../src/get-intermediate-representation.js    |  6 --
 packages/docgen/tests/test-engine.js          | 32 ++++----
 .../test-get-intermediate-representation.js   | 74 ++++++-------------
 4 files changed, 44 insertions(+), 80 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index fd553e91dbcf58..c0f9d26d6423a0 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -13,14 +13,14 @@ const cleanSpaces = ( paragraph ) =>
 		).trim() :
 		'';
 
-const formatParamTags = ( params, docs ) => {
-	if ( params && params.length > 0 ) {
+const formatParamTags = ( tags, docs ) => {
+	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
 		docs.push( '**Parameters**' );
 		docs.push( '\n' );
-		docs.push( ...params.map(
-			( param ) => `\n- **${ param.name }** \`${ getType( param ) }\`: ${ cleanSpaces( param.description ) }`
+		docs.push( ...tags.map(
+			( tag ) => `\n- **${ tag.name }** \`${ getType( tag ) }\`: ${ cleanSpaces( tag.description ) }`
 		) );
 	}
 };
@@ -110,8 +110,8 @@ module.exports = function( artifacts ) {
 			);
 			formatExampleTag( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
 			formatTypeTag( artifact.tags.filter( ( tag ) => tag.title === 'type' ), docs );
-			formatParamTags( artifact.params, docs );
-			formatReturnTag( artifact.return, docs );
+			formatParamTags( artifact.tags.filter( ( tag ) => tag.title === 'param' ), docs );
+			formatReturnTag( artifact.tags.filter( ( tag ) => tag.title === 'return' ), docs );
 			docs.push( '\n' );
 			docs.push( '\n' );
 		} );
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 47be635cdb5db6..7fbccdaf5a661d 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -118,8 +118,6 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
 	return getJSDocFromDependency( token, entry, parseDependency );
 };
 
-const getTagsByName = ( tags, tagName ) => tags.filter( ( tag ) => tag.title === tagName );
-
 /**
  * Takes a export token and returns an intermediate representation in JSON.
  *
@@ -144,8 +142,6 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 				ir.push( {
 					name: namedExport.name,
 					description: namedExport.description,
-					params: getTagsByName( namedExport.tags, 'param' ),
-					return: getTagsByName( namedExport.tags, 'return' ),
 					tags: namedExport.tags,
 				} );
 			} );
@@ -153,8 +149,6 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 			ir.push( {
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
-				params: getTagsByName( get( doc, [ 'tags' ], [] ), 'param' ),
-				return: getTagsByName( get( doc, [ 'tags' ], [] ), 'return' ),
 				tags: get( doc, [ 'tags' ], [] ),
 			} );
 		}
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 0ee4a0de6da27a..557d89a0db3a1f 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -34,9 +34,9 @@ test( 'Engine - many exports at once', ( t ) => {
 	t.deepEqual(
 		ir,
 		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', params: [], return: [], tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', params: [], return: [], tags: [] },
-			{ name: 'default', description: 'Default declaration example.', params: [], return: [], tags: [] },
+			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
+			{ name: 'default', description: 'Default declaration example.', tags: [] },
 		]
 	);
 	t.end();
@@ -53,7 +53,7 @@ test( 'Engine - named export (function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -69,7 +69,7 @@ test( 'Engine - named export (variable)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -87,7 +87,7 @@ test( 'Engine - named export (single identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -105,7 +105,7 @@ test( 'Engine - named export (single identifier) using JSDoc from declaration',
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -131,8 +131,8 @@ test( 'Engine - named export (multiple identifiers) using JSDoc from declaration
 	t.deepEqual(
 		ir,
 		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', params: [], return: [], tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', params: [], return: [], tags: [] },
+			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
+			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
 		]
 	);
 	t.end();
@@ -153,7 +153,7 @@ test( 'Engine - named export (single identifier) using JSDoc from dependency', (
 	);
 	t.deepEqual(
 		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -169,7 +169,7 @@ test( 'Engine - default export (named function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -185,7 +185,7 @@ test( 'Engine - default export (anonymous function)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -203,7 +203,7 @@ test( 'Engine - default export (identifier)', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -221,7 +221,7 @@ test( 'Engine - default export (identifier) using JSDoc from function', ( t ) =>
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -239,7 +239,7 @@ test( 'Engine - default export (identifier) using JSDoc from variable', ( t ) =>
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'My declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -254,7 +254,7 @@ test( 'Engine - undocumented export', ( t ) => {
 ` );
 	t.deepEqual(
 		ir,
-		[ { name: 'default', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'Undocumented declaration.', tags: [] } ]
 	);
 	t.end();
 } );
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 20b9a31f8d049c..c5718145bde23f 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -22,8 +22,6 @@ test( 'IR - undocumented', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
 		name: 'default',
 		description: 'Undocumented declaration.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenOneliner = fs.readFileSync(
@@ -33,8 +31,6 @@ test( 'IR - undocumented', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenOneliner ) ), [ {
 		name: 'default',
 		description: 'Undocumented declaration.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	t.end();
@@ -48,8 +44,6 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassAnonymous ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenClassNamed = fs.readFileSync(
@@ -59,8 +53,6 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassNamed ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenFnAnonymous = fs.readFileSync(
@@ -70,8 +62,6 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnAnonymous ) ), [ {
 		name: 'default',
 		description: 'Function declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenFnNamed = fs.readFileSync(
@@ -81,8 +71,6 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnNamed ) ), [ {
 		name: 'default',
 		description: 'Function declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenVariable = fs.readFileSync(
@@ -92,8 +80,6 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
 		name: 'default',
 		description: 'Variable declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	t.end();
@@ -107,8 +93,6 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClass ) ), [ {
 		name: 'MyDeclaration',
 		description: 'My declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenFn = fs.readFileSync(
@@ -118,8 +102,6 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFn ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenVariable = fs.readFileSync(
@@ -129,8 +111,6 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const tokenVariables = fs.readFileSync(
@@ -138,8 +118,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariables ) ), [
-		{ name: 'firstDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] },
-		{ name: 'secondDeclaration', description: 'My declaration example.', params: [], return: [], tags: [] },
+		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [] },
 	] );
 	t.end();
 } );
@@ -156,8 +136,6 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'default',
 		description: 'Class declaration example.',
-		params: [],
-		return: [],
 		tags: [],
 	} ] );
 	const namedExport = fs.readFileSync(
@@ -170,11 +148,11 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'default', description: 'Function declaration example.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
 	);
 	t.end();
 } );
@@ -191,8 +169,6 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		params: [],
-		return: [],
 		tags: [] },
 	] );
 	const tokenObject = fs.readFileSync(
@@ -206,8 +182,6 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		params: [],
-		return: [],
 		tags: [] },
 	] );
 	const tokens = fs.readFileSync(
@@ -219,9 +193,9 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ), JSON.parse( asts ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
 	] );
 	const foo = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
@@ -232,11 +206,11 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
 	] );
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
 	] );
 	t.end();
 } );
@@ -253,9 +227,9 @@ test( 'IR - JSDoc in module dependency (named export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
 		[
-			{ name: 'functionDeclaration', description: 'Function declaration example.', params: [], return: [], tags: [] },
-			{ name: 'variableDeclaration', description: 'Variable declaration example.', params: [], return: [], tags: [] },
-			{ name: 'ClassDeclaration', description: 'Class declaration example.', params: [], return: [], tags: [] },
+			{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
+			{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+			{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
 		]
 	);
 	t.end();
@@ -272,7 +246,7 @@ test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { name: 'default', description: 'Module declaration.', params: [], return: [], tags: [] } ]
+		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),
@@ -280,7 +254,7 @@ test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { name: 'moduleName', description: 'Module declaration.', params: [], return: [], tags: [] } ]
+		[ { name: 'moduleName', description: 'Module declaration.', tags: [] } ]
 	);
 
 	t.end();
@@ -298,9 +272,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', params: [], return: [], tags: [] },
-			{ name: 'myFunction', description: 'Named function.', params: [], return: [], tags: [] },
-			{ name: 'MyClass', description: 'Named class.', params: [], return: [], tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [] },
 		]
 	);
 	const tokenCommented = fs.readFileSync(
@@ -310,9 +284,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', params: [], return: [], tags: [] },
-			{ name: 'myFunction', description: 'Named function.', params: [], return: [], tags: [] },
-			{ name: 'MyClass', description: 'Named class.', params: [], return: [], tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [] },
 		]
 	);
 	t.end();
@@ -336,8 +310,6 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 		[ {
 			name: 'default',
 			description: 'Function declaration.',
-			params: [],
-			return: [],
 			tags: [],
 		} ]
 	);
@@ -358,8 +330,6 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 		[ {
 			name: 'default',
 			description: 'Function declaration.',
-			params: [],
-			return: [],
 			tags: [],
 		} ]
 	);
@@ -389,7 +359,7 @@ test( 'IR - JSDoc in module dependency through import (named export)', function(
 	};
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { name: 'variables', description: 'Undocumented declaration.', params: [], return: [], tags: [] } ]
+		[ { name: 'variables', description: 'Undocumented declaration.', tags: [] } ]
 	);
 	t.end();
 } );

From 9bcce9e040321f01822098cfeea8c64c6288b0eb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 8 Feb 2019 17:50:48 +0100
Subject: [PATCH 155/213] Refactor formatter to compact code

---
 packages/docgen/src/formatter.js | 98 ++++++++++++++------------------
 1 file changed, 42 insertions(+), 56 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index c0f9d26d6423a0..d514ba0b7b43d6 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -3,6 +3,8 @@
  */
 const getType = require( './get-type-as-string' );
 
+const getTagsByName = ( tags, ...names ) => tags.filter( ( tag ) => names.some( ( name ) => name === tag.title ) );
+
 const cleanSpaces = ( paragraph ) =>
 	paragraph ?
 		paragraph.split( '\n' ).map(
@@ -13,19 +15,17 @@ const cleanSpaces = ( paragraph ) =>
 		).trim() :
 		'';
 
-const formatParamTags = ( tags, docs ) => {
+const formatTag = ( title, tags, formatter, docs ) => {
 	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
-		docs.push( '**Parameters**' );
+		docs.push( `**${ title }**` );
 		docs.push( '\n' );
-		docs.push( ...tags.map(
-			( tag ) => `\n- **${ tag.name }** \`${ getType( tag ) }\`: ${ cleanSpaces( tag.description ) }`
-		) );
+		docs.push( ...tags.map( formatter ) );
 	}
 };
 
-const formatExampleTag = ( tags, docs ) => {
+const formatExamples = ( tags, docs ) => {
 	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
 		docs.push( '\n' );
@@ -38,41 +38,6 @@ const formatExampleTag = ( tags, docs ) => {
 	}
 };
 
-const formatReturnTag = ( tag, docs ) => {
-	if ( tag && tag.length === 1 ) {
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( '**Returns**' );
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( `\`${ getType( tag[ 0 ] ) }\` ${ cleanSpaces( tag[ 0 ].description ) }` );
-	}
-};
-
-const formatTypeTag = ( tag, docs ) => {
-	if ( tag && tag.length === 1 ) {
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( '**Type**' );
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( `\`${ getType( tag[ 0 ] ) }\` ${ cleanSpaces( tag[ 0 ].description ) }` );
-	}
-};
-
-const formatSeeAndLinkTags = ( tags, docs ) => {
-	if ( tags && tags.length > 0 ) {
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( '**Related**' );
-		docs.push( '\n' );
-		docs.push( '\n' );
-		docs.push( ...tags.map(
-			( tag ) => `\n- ${ tag.description }`
-		) );
-	}
-};
-
 const formatDeprecated = ( tags, docs ) => {
 	if ( tags && tags.length > 0 ) {
 		docs.push( '\n' );
@@ -82,11 +47,17 @@ const formatDeprecated = ( tags, docs ) => {
 	}
 };
 
-module.exports = function( artifacts ) {
+const formatDescription = ( description, docs ) => {
+	docs.push( '\n' );
+	docs.push( '\n' );
+	docs.push( description );
+};
+
+module.exports = function( symbols ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
 	docs.push( '\n' );
-	artifacts.sort( ( first, second ) => {
+	symbols.sort( ( first, second ) => {
 		const firstName = first.name.toUpperCase();
 		const secondName = second.name.toUpperCase();
 		if ( firstName < secondName ) {
@@ -97,21 +68,36 @@ module.exports = function( artifacts ) {
 		}
 		return 0;
 	} );
-	if ( artifacts && artifacts.length > 0 ) {
-		artifacts.forEach( ( artifact ) => {
-			docs.push( `## ${ artifact.name }` );
-			formatDeprecated( artifact.tags.filter( ( tag ) => tag.title === 'deprecated' ), docs );
-			docs.push( '\n' );
-			docs.push( '\n' );
-			docs.push( artifact.description );
-			formatSeeAndLinkTags(
-				artifact.tags.filter( ( tag ) => ( tag.title === 'see' ) || ( tag.title === 'link' ) ),
+	if ( symbols && symbols.length > 0 ) {
+		symbols.forEach( ( symbol ) => {
+			docs.push( `## ${ symbol.name }` );
+			formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs );
+			formatDescription( symbol.description, docs );
+			formatTag(
+				'Related',
+				getTagsByName( symbol.tags, 'see', 'link' ),
+				( tag ) => `\n- ${ tag.description }`,
+				docs
+			);
+			formatExamples( getTagsByName( symbol.tags, 'example' ), docs );
+			formatTag(
+				'Type',
+				getTagsByName( symbol.tags, 'type' ),
+				( tag ) => `\n\`${ getType( tag ) }\` ${ cleanSpaces( tag.description ) }`,
+				docs
+			);
+			formatTag(
+				'Parameters',
+				getTagsByName( symbol.tags, 'param' ),
+				( tag ) => `\n- **${ tag.name }** \`${ getType( tag ) }\`: ${ cleanSpaces( tag.description ) }`,
+				docs
+			);
+			formatTag(
+				'Returns',
+				getTagsByName( symbol.tags, 'return' ),
+				( tag ) => `\n\`${ getType( tag ) }\` ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
-			formatExampleTag( artifact.tags.filter( ( tag ) => tag.title === 'example' ), docs );
-			formatTypeTag( artifact.tags.filter( ( tag ) => tag.title === 'type' ), docs );
-			formatParamTags( artifact.tags.filter( ( tag ) => tag.title === 'param' ), docs );
-			formatReturnTag( artifact.tags.filter( ( tag ) => tag.title === 'return' ), docs );
 			docs.push( '\n' );
 			docs.push( '\n' );
 		} );

From 22f78f0a5a6ae25c64bd8ac26ad8ebef0d54d372 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 8 Feb 2019 18:43:23 +0100
Subject: [PATCH 156/213] Update coverage

---
 packages/docgen/coverage.md | 44 ++++++++++++++++++-------------------
 1 file changed, 22 insertions(+), 22 deletions(-)

diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index 3f0a9ace200feb..ff795e6a61628a 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -16,29 +16,27 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
-Fix JSDoc manually:
-
-- [ ] autop `description` contains HTML
-- [ ] e2e-test-utils `setUpResponseMocking` has example mixed with description
-- [ ] rich-text `concat` type `@param` is `{...[object]}`. Should be
-
-```js
-/**
- * Combine all Rich Text values into one. This is similar to
- * `String.prototype.concat`.
- *
- * @param {...Object} values Objects to combine.
- *
- * @return {Object} A new value combining all given records.
- */
-```
-
 TODO:
 
-- [ ] blocks `unstable__*` should this be docummented?
-- [ ] keycodes `CONSTANTS`
-- [ ] rich-text `LINE_SEPARATOR` is a constant
-- [ ] rich-text `unstableToDom` is this supposed to go undocumented?
+These either happen in private API, aren't relevant, or pend of decission.
+
+- [ ] go undocummented: `unstable__*`, rich-text `unstableToDom`, `experimental__`
+- [ ] `constants` keycodes, rich-text `LINE_SEPARATOR`
+- [ ] `{?{ time: number, count: number }}`packages/editor/src/store/selectors.js
+- [ ] `{type=}` packages/block-library/src/image/edit.js
+- [ ] `@api` packages/editor/src/editor-styles/ast/stringify/compiler.js
+- [ ] `@callback` packages/components/src/autocomplete/index.js
+- [ ] `@cite` packages/block-serialization-default-parser/src/index.js
+- [ ] `@class` packages/edit-post/src/hooks/components/media-upload/index.js
+- [ ] `@const` packages/editor/src/editor-styles/transforms/wrap.js
+- [ ] `@constant` packages/editor/src/hooks/align.js
+- [ ] `@constructor` packages/edit-post/src/hooks/components/media-upload/index.js
+- [ ] `@inheritdoc` packages/edit-post/src/components/meta-boxes/meta-boxes-area/index.js
+- [ ] `@private` packages/editor/src/components/rich-text/index.js
+- [ ] `@property` babel-plugin-import-jsx-pragma
+- [ ] `@since` packages/block-serialization-default-parser/src/index.js
+- [ ] `@throws` packages/blocks/src/api/node.js
+- [ ] `@typedef` packages/blocks/src/api/registration.js
 
 DONE:
 
@@ -50,6 +48,7 @@ DONE:
 - [x] block-library
 - [x] block-serialization-default-parser
 - [x] block-serialization-spec-parser
+- [x] blocks
 - [x] components
 - [x] compose
 - [x] core-data
@@ -76,8 +75,9 @@ DONE:
 - [x] plugins
 - [x] priority-queue
 - [x] redux-routine
+- [x] rich-text
 - [x] shortcode
 - [x] token-list
 - [x] url
 - [x] viewport
-- [x] wordcount
\ No newline at end of file
+- [x] wordcount

From b16d957a2a1acfa38d16237bdfa84f62c15a41a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 12:46:30 +0100
Subject: [PATCH 157/213] Add line numbers (start, end) to export tokens

---
 packages/docgen/src/engine.js             |  1 +
 packages/docgen/src/get-export-entries.js | 12 ++++++++++++
 2 files changed, 13 insertions(+)

diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index 3ed82da74e99c5..eb9204bce6320f 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -11,6 +11,7 @@ const getIntermediateRepresentation = require( './get-intermediate-representatio
 
 const getAST = ( source ) => espree.parse( source, {
 	attachComment: true,
+	loc: true,
 	ecmaVersion: 2018,
 	ecmaFeatures: {
 		jsx: true,
diff --git a/packages/docgen/src/get-export-entries.js b/packages/docgen/src/get-export-entries.js
index bdb56f34bcb3ad..a69811b2b6545d 100644
--- a/packages/docgen/src/get-export-entries.js
+++ b/packages/docgen/src/get-export-entries.js
@@ -15,6 +15,8 @@ const { get } = require( 'lodash' );
  *    localName: 'localName',
  *    exportName: 'exportedName',
  *    module: null,
+ *    lineStart: 2,
+ *    lineEnd: 3,
  * } ]
  */
 module.exports = function( token ) {
@@ -39,6 +41,8 @@ module.exports = function( token ) {
 			localName: getLocalName( token ),
 			exportName: 'default',
 			module: null,
+			lineStart: token.loc.start.line,
+			lineEnd: token.loc.end.line,
 		} ];
 	}
 
@@ -47,6 +51,8 @@ module.exports = function( token ) {
 			localName: '*',
 			exportName: null,
 			module: token.source.value,
+			lineStart: token.loc.start.line,
+			lineEnd: token.loc.end.line,
 		} ];
 	}
 
@@ -56,6 +62,8 @@ module.exports = function( token ) {
 			localName: specifier.local.name,
 			exportName: specifier.exported.name,
 			module: get( token.source, [ 'value' ], null ),
+			lineStart: specifier.loc.start.line,
+			lineEnd: specifier.loc.end.line,
 		} ) );
 		return name;
 	}
@@ -67,6 +75,8 @@ module.exports = function( token ) {
 				localName: token.declaration.id.name,
 				exportName: token.declaration.id.name,
 				module: null,
+				lineStart: token.declaration.loc.start.line,
+				lineEnd: token.declaration.loc.end.line,
 			} );
 			break;
 
@@ -76,6 +86,8 @@ module.exports = function( token ) {
 					localName: declaration.id.name,
 					exportName: declaration.id.name,
 					module: null,
+					lineStart: token.declaration.loc.start.line,
+					lineEnd: token.declaration.loc.end.line,
 				} );
 			} );
 			break;

From acc8ccb960c185d65daf3d9ac83d8153065033d5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 13:24:54 +0100
Subject: [PATCH 158/213] Adapt tests to new API

---
 .../fixtures/default-class-anonymous.json     |  42 ++-
 .../tests/fixtures/default-class-named.json   |  52 ++-
 .../fixtures/default-function-anonymous.json  |  42 ++-
 .../fixtures/default-function-named-ast.json  |  74 ++++-
 .../fixtures/default-function-named.json      |  52 ++-
 .../fixtures/default-identifier-ast.json      |  84 ++++-
 .../tests/fixtures/default-identifier.json    |  20 ++
 .../fixtures/default-import-default-ast.json  |  70 ++++
 .../fixtures/default-import-default.json      |  20 ++
 .../fixtures/default-import-named-ast.json    |  80 +++++
 .../default-import-named-module-ir.json       |   8 +-
 .../tests/fixtures/default-import-named.json  |  20 ++
 .../fixtures/default-named-export-ast.json    |  94 +++++-
 .../tests/fixtures/default-named-export.json  |  72 ++++-
 .../default-undocumented-nocomments.json      |  20 ++
 .../default-undocumented-oneliner.json        |  42 ++-
 .../tests/fixtures/default-variable.json      |  32 +-
 .../docgen/tests/fixtures/named-class.json    |  52 ++-
 .../fixtures/named-default-exported.json      |  50 +++
 .../fixtures/named-default-module-ir.json     |  12 +-
 .../docgen/tests/fixtures/named-default.json  |  50 +++
 .../docgen/tests/fixtures/named-function.json |  94 ++++--
 .../tests/fixtures/named-identifier-ast.json  | 104 +++++-
 .../named-identifier-destructuring-ast.json   | 184 ++++++++++-
 .../named-identifier-destructuring.json       |  40 +++
 .../tests/fixtures/named-identifier.json      |  40 +++
 .../named-identifiers-and-inline-ast.json     | 286 +++++++++++++++-
 .../named-identifiers-and-inline.json         | 144 ++++++++-
 .../tests/fixtures/named-identifiers-ast.json | 306 +++++++++++++++++-
 .../tests/fixtures/named-identifiers-ir.json  |  24 +-
 .../tests/fixtures/named-identifiers.json     | 100 ++++++
 .../tests/fixtures/named-import-named.json    | 110 +++++++
 .../fixtures/named-import-namespace-ast.json  |  90 ++++++
 .../named-import-namespace-module.json        |  50 +++
 .../fixtures/named-import-namespace.json      |  40 +++
 .../docgen/tests/fixtures/named-variable.json |  62 +++-
 .../tests/fixtures/named-variables.json       |  92 +++++-
 .../tests/fixtures/namespace-commented.json   |  32 +-
 .../tests/fixtures/namespace-module-ir.json   |  16 +-
 packages/docgen/tests/fixtures/namespace.json |  20 ++
 .../docgen/tests/test-get-export-entries.js   |  54 +++-
 .../test-get-intermediate-representation.js   |   8 +-
 42 files changed, 2765 insertions(+), 119 deletions(-)

diff --git a/packages/docgen/tests/fixtures/default-class-anonymous.json b/packages/docgen/tests/fixtures/default-class-anonymous.json
index 55951cf7ce10d3..858f07abe98df9 100644
--- a/packages/docgen/tests/fixtures/default-class-anonymous.json
+++ b/packages/docgen/tests/fixtures/default-class-anonymous.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 38,
 	"end": 61,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 23
+		}
+	},
 	"range": [
 		38,
 		61
@@ -10,6 +20,16 @@
 		"type": "ClassDeclaration",
 		"start": 53,
 		"end": 61,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 15
+			},
+			"end": {
+				"line": 4,
+				"column": 23
+			}
+		},
 		"range": [
 			53,
 			61
@@ -20,6 +40,16 @@
 			"type": "ClassBody",
 			"start": 59,
 			"end": 61,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 21
+				},
+				"end": {
+					"line": 4,
+					"column": 23
+				}
+			},
 			"range": [
 				59,
 				61
@@ -36,7 +66,17 @@
 			"range": [
 				0,
 				37
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-class-named.json b/packages/docgen/tests/fixtures/default-class-named.json
index d460be909ffd53..7533ef32e60de0 100644
--- a/packages/docgen/tests/fixtures/default-class-named.json
+++ b/packages/docgen/tests/fixtures/default-class-named.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 38,
 	"end": 78,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 40
+		}
+	},
 	"range": [
 		38,
 		78
@@ -10,6 +20,16 @@
 		"type": "ClassDeclaration",
 		"start": 53,
 		"end": 78,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 15
+			},
+			"end": {
+				"line": 4,
+				"column": 40
+			}
+		},
 		"range": [
 			53,
 			78
@@ -18,6 +38,16 @@
 			"type": "Identifier",
 			"start": 59,
 			"end": 75,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 21
+				},
+				"end": {
+					"line": 4,
+					"column": 37
+				}
+			},
 			"range": [
 				59,
 				75
@@ -29,6 +59,16 @@
 			"type": "ClassBody",
 			"start": 76,
 			"end": 78,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 38
+				},
+				"end": {
+					"line": 4,
+					"column": 40
+				}
+			},
 			"range": [
 				76,
 				78
@@ -45,7 +85,17 @@
 			"range": [
 				0,
 				37
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-function-anonymous.json b/packages/docgen/tests/fixtures/default-function-anonymous.json
index 59f92aac1b9fa7..9d10cd6c962f0f 100644
--- a/packages/docgen/tests/fixtures/default-function-anonymous.json
+++ b/packages/docgen/tests/fixtures/default-function-anonymous.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 41,
 	"end": 69,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 28
+		}
+	},
 	"range": [
 		41,
 		69
@@ -10,6 +20,16 @@
 		"type": "FunctionDeclaration",
 		"start": 56,
 		"end": 69,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 15
+			},
+			"end": {
+				"line": 4,
+				"column": 28
+			}
+		},
 		"range": [
 			56,
 			69
@@ -23,6 +43,16 @@
 			"type": "BlockStatement",
 			"start": 67,
 			"end": 69,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 26
+				},
+				"end": {
+					"line": 4,
+					"column": 28
+				}
+			},
 			"range": [
 				67,
 				69
@@ -39,7 +69,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-function-named-ast.json b/packages/docgen/tests/fixtures/default-function-named-ast.json
index d641342db98640..a082f805974d26 100644
--- a/packages/docgen/tests/fixtures/default-function-named-ast.json
+++ b/packages/docgen/tests/fixtures/default-function-named-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 84,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 42
+		}
+	},
 	"range": [
 		41,
 		83
@@ -11,6 +21,16 @@
 			"type": "ExportDefaultDeclaration",
 			"start": 41,
 			"end": 83,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 42
+				}
+			},
 			"range": [
 				41,
 				83
@@ -19,6 +39,16 @@
 				"type": "FunctionDeclaration",
 				"start": 56,
 				"end": 83,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 15
+					},
+					"end": {
+						"line": 4,
+						"column": 42
+					}
+				},
 				"range": [
 					56,
 					83
@@ -27,6 +57,16 @@
 					"type": "Identifier",
 					"start": 65,
 					"end": 78,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 24
+						},
+						"end": {
+							"line": 4,
+							"column": 37
+						}
+					},
 					"range": [
 						65,
 						78
@@ -41,6 +81,16 @@
 					"type": "BlockStatement",
 					"start": 81,
 					"end": 83,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 40
+						},
+						"end": {
+							"line": 4,
+							"column": 42
+						}
+					},
 					"range": [
 						81,
 						83
@@ -57,7 +107,17 @@
 					"range": [
 						0,
 						40
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			]
 		}
@@ -72,7 +132,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-function-named.json b/packages/docgen/tests/fixtures/default-function-named.json
index 1905a0ebba22de..7765cbef0da6d9 100644
--- a/packages/docgen/tests/fixtures/default-function-named.json
+++ b/packages/docgen/tests/fixtures/default-function-named.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 41,
 	"end": 83,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 42
+		}
+	},
 	"range": [
 		41,
 		83
@@ -10,6 +20,16 @@
 		"type": "FunctionDeclaration",
 		"start": 56,
 		"end": 83,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 15
+			},
+			"end": {
+				"line": 4,
+				"column": 42
+			}
+		},
 		"range": [
 			56,
 			83
@@ -18,6 +38,16 @@
 			"type": "Identifier",
 			"start": 65,
 			"end": 78,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 24
+				},
+				"end": {
+					"line": 4,
+					"column": 37
+				}
+			},
 			"range": [
 				65,
 				78
@@ -32,6 +62,16 @@
 			"type": "BlockStatement",
 			"start": 81,
 			"end": 83,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 40
+				},
+				"end": {
+					"line": 4,
+					"column": 42
+				}
+			},
 			"range": [
 				81,
 				83
@@ -48,7 +88,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-identifier-ast.json b/packages/docgen/tests/fixtures/default-identifier-ast.json
index b7852864bcecda..d83f628004f7de 100644
--- a/packages/docgen/tests/fixtures/default-identifier-ast.json
+++ b/packages/docgen/tests/fixtures/default-identifier-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 98,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 32
+		}
+	},
 	"range": [
 		38,
 		97
@@ -11,6 +21,16 @@
 			"type": "ClassDeclaration",
 			"start": 38,
 			"end": 63,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 25
+				}
+			},
 			"range": [
 				38,
 				63
@@ -19,6 +39,16 @@
 				"type": "Identifier",
 				"start": 44,
 				"end": 60,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 6
+					},
+					"end": {
+						"line": 4,
+						"column": 22
+					}
+				},
 				"range": [
 					44,
 					60
@@ -30,6 +60,16 @@
 				"type": "ClassBody",
 				"start": 61,
 				"end": 63,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 23
+					},
+					"end": {
+						"line": 4,
+						"column": 25
+					}
+				},
 				"range": [
 					61,
 					63
@@ -45,7 +85,17 @@
 					"range": [
 						0,
 						37
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -53,6 +103,16 @@
 			"type": "ExportDefaultDeclaration",
 			"start": 65,
 			"end": 97,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 6,
+					"column": 32
+				}
+			},
 			"range": [
 				65,
 				97
@@ -61,6 +121,16 @@
 				"type": "Identifier",
 				"start": 80,
 				"end": 96,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 15
+					},
+					"end": {
+						"line": 6,
+						"column": 31
+					}
+				},
 				"range": [
 					80,
 					96
@@ -79,7 +149,17 @@
 			"range": [
 				0,
 				37
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-identifier.json b/packages/docgen/tests/fixtures/default-identifier.json
index 6921571287c53b..c5cb42d5ad4caa 100644
--- a/packages/docgen/tests/fixtures/default-identifier.json
+++ b/packages/docgen/tests/fixtures/default-identifier.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 65,
 	"end": 97,
+	"loc": {
+		"start": {
+			"line": 6,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 32
+		}
+	},
 	"range": [
 		65,
 		97
@@ -10,6 +20,16 @@
 		"type": "Identifier",
 		"start": 80,
 		"end": 96,
+		"loc": {
+			"start": {
+				"line": 6,
+				"column": 15
+			},
+			"end": {
+				"line": 6,
+				"column": 31
+			}
+		},
 		"range": [
 			80,
 			96
diff --git a/packages/docgen/tests/fixtures/default-import-default-ast.json b/packages/docgen/tests/fixtures/default-import-default-ast.json
index e7ac254cec46f2..ee77f27a561e76 100644
--- a/packages/docgen/tests/fixtures/default-import-default-ast.json
+++ b/packages/docgen/tests/fixtures/default-import-default-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 92,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 29
+		}
+	},
 	"range": [
 		0,
 		91
@@ -11,6 +21,16 @@
 			"type": "ImportDeclaration",
 			"start": 0,
 			"end": 60,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 1,
+					"column": 60
+				}
+			},
 			"range": [
 				0,
 				60
@@ -20,6 +40,16 @@
 					"type": "ImportDefaultSpecifier",
 					"start": 7,
 					"end": 20,
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 7
+						},
+						"end": {
+							"line": 1,
+							"column": 20
+						}
+					},
 					"range": [
 						7,
 						20
@@ -28,6 +58,16 @@
 						"type": "Identifier",
 						"start": 7,
 						"end": 20,
+						"loc": {
+							"start": {
+								"line": 1,
+								"column": 7
+							},
+							"end": {
+								"line": 1,
+								"column": 20
+							}
+						},
 						"range": [
 							7,
 							20
@@ -40,6 +80,16 @@
 				"type": "Literal",
 				"start": 26,
 				"end": 59,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 26
+					},
+					"end": {
+						"line": 1,
+						"column": 59
+					}
+				},
 				"range": [
 					26,
 					59
@@ -52,6 +102,16 @@
 			"type": "ExportDefaultDeclaration",
 			"start": 62,
 			"end": 91,
+			"loc": {
+				"start": {
+					"line": 3,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 29
+				}
+			},
 			"range": [
 				62,
 				91
@@ -60,6 +120,16 @@
 				"type": "Identifier",
 				"start": 77,
 				"end": 90,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 15
+					},
+					"end": {
+						"line": 3,
+						"column": 28
+					}
+				},
 				"range": [
 					77,
 					90
diff --git a/packages/docgen/tests/fixtures/default-import-default.json b/packages/docgen/tests/fixtures/default-import-default.json
index 6b47c06b1b29fc..fd453ed3011007 100644
--- a/packages/docgen/tests/fixtures/default-import-default.json
+++ b/packages/docgen/tests/fixtures/default-import-default.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 62,
 	"end": 91,
+	"loc": {
+		"start": {
+			"line": 3,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 29
+		}
+	},
 	"range": [
 		62,
 		91
@@ -10,6 +20,16 @@
 		"type": "Identifier",
 		"start": 77,
 		"end": 90,
+		"loc": {
+			"start": {
+				"line": 3,
+				"column": 15
+			},
+			"end": {
+				"line": 3,
+				"column": 28
+			}
+		},
 		"range": [
 			77,
 			90
diff --git a/packages/docgen/tests/fixtures/default-import-named-ast.json b/packages/docgen/tests/fixtures/default-import-named-ast.json
index efa7bded38f7e3..73947334d5ac83 100644
--- a/packages/docgen/tests/fixtures/default-import-named-ast.json
+++ b/packages/docgen/tests/fixtures/default-import-named-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 117,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 29
+		}
+	},
 	"range": [
 		0,
 		116
@@ -11,6 +21,16 @@
 			"type": "ImportDeclaration",
 			"start": 0,
 			"end": 85,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 1,
+					"column": 85
+				}
+			},
 			"range": [
 				0,
 				85
@@ -20,6 +40,16 @@
 					"type": "ImportSpecifier",
 					"start": 9,
 					"end": 45,
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 9
+						},
+						"end": {
+							"line": 1,
+							"column": 45
+						}
+					},
 					"range": [
 						9,
 						45
@@ -28,6 +58,16 @@
 						"type": "Identifier",
 						"start": 9,
 						"end": 28,
+						"loc": {
+							"start": {
+								"line": 1,
+								"column": 9
+							},
+							"end": {
+								"line": 1,
+								"column": 28
+							}
+						},
 						"range": [
 							9,
 							28
@@ -38,6 +78,16 @@
 						"type": "Identifier",
 						"start": 32,
 						"end": 45,
+						"loc": {
+							"start": {
+								"line": 1,
+								"column": 32
+							},
+							"end": {
+								"line": 1,
+								"column": 45
+							}
+						},
 						"range": [
 							32,
 							45
@@ -50,6 +100,16 @@
 				"type": "Literal",
 				"start": 53,
 				"end": 84,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 53
+					},
+					"end": {
+						"line": 1,
+						"column": 84
+					}
+				},
 				"range": [
 					53,
 					84
@@ -62,6 +122,16 @@
 			"type": "ExportDefaultDeclaration",
 			"start": 87,
 			"end": 116,
+			"loc": {
+				"start": {
+					"line": 3,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 29
+				}
+			},
 			"range": [
 				87,
 				116
@@ -70,6 +140,16 @@
 				"type": "Identifier",
 				"start": 102,
 				"end": 115,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 15
+					},
+					"end": {
+						"line": 3,
+						"column": 28
+					}
+				},
 				"range": [
 					102,
 					115
diff --git a/packages/docgen/tests/fixtures/default-import-named-module-ir.json b/packages/docgen/tests/fixtures/default-import-named-module-ir.json
index b2c0a7beccba2f..3c04255485cb97 100644
--- a/packages/docgen/tests/fixtures/default-import-named-module-ir.json
+++ b/packages/docgen/tests/fixtures/default-import-named-module-ir.json
@@ -1,7 +1 @@
-[
-	{
-		"name": "functionDeclaration",
-		"description": "Function declaration.",
-		"tags": []
-	}
-]
\ No newline at end of file
+[{"name":"functionDeclaration","description":"Function declaration.","tags":[]}]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-import-named.json b/packages/docgen/tests/fixtures/default-import-named.json
index 6b65941d8de579..25d0f6024356f9 100644
--- a/packages/docgen/tests/fixtures/default-import-named.json
+++ b/packages/docgen/tests/fixtures/default-import-named.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 87,
 	"end": 116,
+	"loc": {
+		"start": {
+			"line": 3,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 29
+		}
+	},
 	"range": [
 		87,
 		116
@@ -10,6 +20,16 @@
 		"type": "Identifier",
 		"start": 102,
 		"end": 115,
+		"loc": {
+			"start": {
+				"line": 3,
+				"column": 15
+			},
+			"end": {
+				"line": 3,
+				"column": 28
+			}
+		},
 		"range": [
 			102,
 			115
diff --git a/packages/docgen/tests/fixtures/default-named-export-ast.json b/packages/docgen/tests/fixtures/default-named-export-ast.json
index 07f17844d5caf4..31fde5d2e6883f 100644
--- a/packages/docgen/tests/fixtures/default-named-export-ast.json
+++ b/packages/docgen/tests/fixtures/default-named-export-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 119,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 35
+		}
+	},
 	"range": [
 		41,
 		118
@@ -11,6 +21,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 41,
 			"end": 81,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 40
+				}
+			},
 			"range": [
 				41,
 				81
@@ -19,6 +39,16 @@
 				"type": "FunctionDeclaration",
 				"start": 48,
 				"end": 81,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 7
+					},
+					"end": {
+						"line": 4,
+						"column": 40
+					}
+				},
 				"range": [
 					48,
 					81
@@ -27,6 +57,16 @@
 					"type": "Identifier",
 					"start": 57,
 					"end": 76,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 16
+						},
+						"end": {
+							"line": 4,
+							"column": 35
+						}
+					},
 					"range": [
 						57,
 						76
@@ -41,6 +81,16 @@
 					"type": "BlockStatement",
 					"start": 79,
 					"end": 81,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 38
+						},
+						"end": {
+							"line": 4,
+							"column": 40
+						}
+					},
 					"range": [
 						79,
 						81
@@ -59,7 +109,17 @@
 					"range": [
 						0,
 						40
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -67,6 +127,16 @@
 			"type": "ExportDefaultDeclaration",
 			"start": 83,
 			"end": 118,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 6,
+					"column": 35
+				}
+			},
 			"range": [
 				83,
 				118
@@ -75,6 +145,16 @@
 				"type": "Identifier",
 				"start": 98,
 				"end": 117,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 15
+					},
+					"end": {
+						"line": 6,
+						"column": 34
+					}
+				},
 				"range": [
 					98,
 					117
@@ -93,7 +173,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-named-export.json b/packages/docgen/tests/fixtures/default-named-export.json
index 9aee275e9fa5a1..b432555e4d7a43 100644
--- a/packages/docgen/tests/fixtures/default-named-export.json
+++ b/packages/docgen/tests/fixtures/default-named-export.json
@@ -3,6 +3,16 @@
 		"type": "ExportNamedDeclaration",
 		"start": 41,
 		"end": 81,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 0
+			},
+			"end": {
+				"line": 4,
+				"column": 40
+			}
+		},
 		"range": [
 			41,
 			81
@@ -11,6 +21,16 @@
 			"type": "FunctionDeclaration",
 			"start": 48,
 			"end": 81,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 7
+				},
+				"end": {
+					"line": 4,
+					"column": 40
+				}
+			},
 			"range": [
 				48,
 				81
@@ -19,6 +39,16 @@
 				"type": "Identifier",
 				"start": 57,
 				"end": 76,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 16
+					},
+					"end": {
+						"line": 4,
+						"column": 35
+					}
+				},
 				"range": [
 					57,
 					76
@@ -33,6 +63,16 @@
 				"type": "BlockStatement",
 				"start": 79,
 				"end": 81,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 38
+					},
+					"end": {
+						"line": 4,
+						"column": 40
+					}
+				},
 				"range": [
 					79,
 					81
@@ -51,7 +91,17 @@
 				"range": [
 					0,
 					40
-				]
+				],
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 0
+					},
+					"end": {
+						"line": 3,
+						"column": 3
+					}
+				}
 			}
 		]
 	},
@@ -59,6 +109,16 @@
 		"type": "ExportDefaultDeclaration",
 		"start": 83,
 		"end": 118,
+		"loc": {
+			"start": {
+				"line": 6,
+				"column": 0
+			},
+			"end": {
+				"line": 6,
+				"column": 35
+			}
+		},
 		"range": [
 			83,
 			118
@@ -67,6 +127,16 @@
 			"type": "Identifier",
 			"start": 98,
 			"end": 117,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 15
+				},
+				"end": {
+					"line": 6,
+					"column": 34
+				}
+			},
 			"range": [
 				98,
 				117
diff --git a/packages/docgen/tests/fixtures/default-undocumented-nocomments.json b/packages/docgen/tests/fixtures/default-undocumented-nocomments.json
index 887cf3f9f0a948..ac0eef84379339 100644
--- a/packages/docgen/tests/fixtures/default-undocumented-nocomments.json
+++ b/packages/docgen/tests/fixtures/default-undocumented-nocomments.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 38,
 	"end": 67,
+	"loc": {
+		"start": {
+			"line": 3,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 29
+		}
+	},
 	"range": [
 		38,
 		67
@@ -10,6 +20,16 @@
 		"type": "Identifier",
 		"start": 53,
 		"end": 66,
+		"loc": {
+			"start": {
+				"line": 3,
+				"column": 15
+			},
+			"end": {
+				"line": 3,
+				"column": 28
+			}
+		},
 		"range": [
 			53,
 			66
diff --git a/packages/docgen/tests/fixtures/default-undocumented-oneliner.json b/packages/docgen/tests/fixtures/default-undocumented-oneliner.json
index 800319a816bfd8..45c6ab79f09133 100644
--- a/packages/docgen/tests/fixtures/default-undocumented-oneliner.json
+++ b/packages/docgen/tests/fixtures/default-undocumented-oneliner.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 34,
 	"end": 63,
+	"loc": {
+		"start": {
+			"line": 2,
+			"column": 0
+		},
+		"end": {
+			"line": 2,
+			"column": 29
+		}
+	},
 	"range": [
 		34,
 		63
@@ -10,6 +20,16 @@
 		"type": "FunctionDeclaration",
 		"start": 49,
 		"end": 63,
+		"loc": {
+			"start": {
+				"line": 2,
+				"column": 15
+			},
+			"end": {
+				"line": 2,
+				"column": 29
+			}
+		},
 		"range": [
 			49,
 			63
@@ -23,6 +43,16 @@
 			"type": "BlockStatement",
 			"start": 60,
 			"end": 63,
+			"loc": {
+				"start": {
+					"line": 2,
+					"column": 26
+				},
+				"end": {
+					"line": 2,
+					"column": 29
+				}
+			},
 			"range": [
 				60,
 				63
@@ -39,7 +69,17 @@
 			"range": [
 				0,
 				33
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 1,
+					"column": 33
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/default-variable.json b/packages/docgen/tests/fixtures/default-variable.json
index 71688384b70d65..e6204ba061364b 100644
--- a/packages/docgen/tests/fixtures/default-variable.json
+++ b/packages/docgen/tests/fixtures/default-variable.json
@@ -2,6 +2,16 @@
 	"type": "ExportDefaultDeclaration",
 	"start": 41,
 	"end": 61,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 20
+		}
+	},
 	"range": [
 		41,
 		61
@@ -10,6 +20,16 @@
 		"type": "Literal",
 		"start": 56,
 		"end": 60,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 15
+			},
+			"end": {
+				"line": 4,
+				"column": 19
+			}
+		},
 		"range": [
 			56,
 			60
@@ -26,7 +46,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-class.json b/packages/docgen/tests/fixtures/named-class.json
index 163fcdb31cf250..e6da37a8974a0a 100644
--- a/packages/docgen/tests/fixtures/named-class.json
+++ b/packages/docgen/tests/fixtures/named-class.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 35,
 	"end": 64,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 29
+		}
+	},
 	"range": [
 		35,
 		64
@@ -10,6 +20,16 @@
 		"type": "ClassDeclaration",
 		"start": 42,
 		"end": 64,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 7
+			},
+			"end": {
+				"line": 4,
+				"column": 29
+			}
+		},
 		"range": [
 			42,
 			64
@@ -18,6 +38,16 @@
 			"type": "Identifier",
 			"start": 48,
 			"end": 61,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 13
+				},
+				"end": {
+					"line": 4,
+					"column": 26
+				}
+			},
 			"range": [
 				48,
 				61
@@ -29,6 +59,16 @@
 			"type": "ClassBody",
 			"start": 62,
 			"end": 64,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 27
+				},
+				"end": {
+					"line": 4,
+					"column": 29
+				}
+			},
 			"range": [
 				62,
 				64
@@ -47,7 +87,17 @@
 			"range": [
 				0,
 				34
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-default-exported.json b/packages/docgen/tests/fixtures/named-default-exported.json
index f684e0f5872e59..5cfbfc16615810 100644
--- a/packages/docgen/tests/fixtures/named-default-exported.json
+++ b/packages/docgen/tests/fixtures/named-default-exported.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 0,
 	"end": 63,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 1,
+			"column": 63
+		}
+	},
 	"range": [
 		0,
 		63
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 9,
 			"end": 30,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 9
+				},
+				"end": {
+					"line": 1,
+					"column": 30
+				}
+			},
 			"range": [
 				9,
 				30
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 9,
 				"end": 16,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 9
+					},
+					"end": {
+						"line": 1,
+						"column": 16
+					}
+				},
 				"range": [
 					9,
 					16
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 20,
 				"end": 30,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 20
+					},
+					"end": {
+						"line": 1,
+						"column": 30
+					}
+				},
 				"range": [
 					20,
 					30
@@ -42,6 +82,16 @@
 		"type": "Literal",
 		"start": 38,
 		"end": 62,
+		"loc": {
+			"start": {
+				"line": 1,
+				"column": 38
+			},
+			"end": {
+				"line": 1,
+				"column": 62
+			}
+		},
 		"range": [
 			38,
 			62
diff --git a/packages/docgen/tests/fixtures/named-default-module-ir.json b/packages/docgen/tests/fixtures/named-default-module-ir.json
index a4d2e308dd7006..9e9b2ce30509ed 100644
--- a/packages/docgen/tests/fixtures/named-default-module-ir.json
+++ b/packages/docgen/tests/fixtures/named-default-module-ir.json
@@ -1,7 +1,5 @@
-[
-	{
-		"name": "default",
-		"description": "Module declaration.",
-		"tags": []
-	}
-]
\ No newline at end of file
+[{
+	"name": "default",
+	"description": "Module declaration.",
+	"tags": []
+}]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-default.json b/packages/docgen/tests/fixtures/named-default.json
index ad523e8550146f..fd3a3c79d6a8b3 100644
--- a/packages/docgen/tests/fixtures/named-default.json
+++ b/packages/docgen/tests/fixtures/named-default.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 0,
 	"end": 49,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 1,
+			"column": 49
+		}
+	},
 	"range": [
 		0,
 		49
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 9,
 			"end": 16,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 9
+				},
+				"end": {
+					"line": 1,
+					"column": 16
+				}
+			},
 			"range": [
 				9,
 				16
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 9,
 				"end": 16,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 9
+					},
+					"end": {
+						"line": 1,
+						"column": 16
+					}
+				},
 				"range": [
 					9,
 					16
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 9,
 				"end": 16,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 9
+					},
+					"end": {
+						"line": 1,
+						"column": 16
+					}
+				},
 				"range": [
 					9,
 					16
@@ -42,6 +82,16 @@
 		"type": "Literal",
 		"start": 24,
 		"end": 48,
+		"loc": {
+			"start": {
+				"line": 1,
+				"column": 24
+			},
+			"end": {
+				"line": 1,
+				"column": 48
+			}
+		},
 		"range": [
 			24,
 			48
diff --git a/packages/docgen/tests/fixtures/named-function.json b/packages/docgen/tests/fixtures/named-function.json
index f75087e8b740bd..8de0b612c6af6d 100644
--- a/packages/docgen/tests/fixtures/named-function.json
+++ b/packages/docgen/tests/fixtures/named-function.json
@@ -1,26 +1,56 @@
 {
 	"type": "ExportNamedDeclaration",
-	"start": 46,
-	"end": 100,
+	"start": 35,
+	"end": 69,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 34
+		}
+	},
 	"range": [
-		46,
-		100
+		35,
+		69
 	],
 	"declaration": {
 		"type": "FunctionDeclaration",
-		"start": 53,
-		"end": 100,
+		"start": 42,
+		"end": 69,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 7
+			},
+			"end": {
+				"line": 4,
+				"column": 34
+			}
+		},
 		"range": [
-			53,
-			100
+			42,
+			69
 		],
 		"id": {
 			"type": "Identifier",
-			"start": 62,
-			"end": 75,
+			"start": 51,
+			"end": 64,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 16
+				},
+				"end": {
+					"line": 4,
+					"column": 29
+				}
+			},
 			"range": [
-				62,
-				75
+				51,
+				64
 			],
 			"name": "myDeclaration"
 		},
@@ -30,11 +60,21 @@
 		"params": [],
 		"body": {
 			"type": "BlockStatement",
-			"start": 78,
-			"end": 100,
+			"start": 67,
+			"end": 69,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 32
+				},
+				"end": {
+					"line": 4,
+					"column": 34
+				}
+			},
 			"range": [
-				78,
-				100
+				67,
+				69
 			],
 			"body": []
 		}
@@ -44,13 +84,23 @@
 	"leadingComments": [
 		{
 			"type": "Block",
-			"value": "*\n \t\t * My declaration example.\n \t\t ",
-			"start": 3,
-			"end": 43,
+			"value": "*\n * My declaration example.\n ",
+			"start": 0,
+			"end": 34,
 			"range": [
-				3,
-				43
-			]
+				0,
+				34
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifier-ast.json b/packages/docgen/tests/fixtures/named-identifier-ast.json
index 5a9256cc955d8c..40eb2039185e3d 100644
--- a/packages/docgen/tests/fixtures/named-identifier-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifier-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 90,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 25
+		}
+	},
 	"range": [
 		35,
 		89
@@ -11,6 +21,16 @@
 			"type": "FunctionDeclaration",
 			"start": 35,
 			"end": 62,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 27
+				}
+			},
 			"range": [
 				35,
 				62
@@ -19,6 +39,16 @@
 				"type": "Identifier",
 				"start": 44,
 				"end": 57,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 9
+					},
+					"end": {
+						"line": 4,
+						"column": 22
+					}
+				},
 				"range": [
 					44,
 					57
@@ -33,6 +63,16 @@
 				"type": "BlockStatement",
 				"start": 60,
 				"end": 62,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 25
+					},
+					"end": {
+						"line": 4,
+						"column": 27
+					}
+				},
 				"range": [
 					60,
 					62
@@ -48,7 +88,17 @@
 					"range": [
 						0,
 						34
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -56,6 +106,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 64,
 			"end": 89,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 6,
+					"column": 25
+				}
+			},
 			"range": [
 				64,
 				89
@@ -66,6 +126,16 @@
 					"type": "ExportSpecifier",
 					"start": 73,
 					"end": 86,
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 9
+						},
+						"end": {
+							"line": 6,
+							"column": 22
+						}
+					},
 					"range": [
 						73,
 						86
@@ -74,6 +144,16 @@
 						"type": "Identifier",
 						"start": 73,
 						"end": 86,
+						"loc": {
+							"start": {
+								"line": 6,
+								"column": 9
+							},
+							"end": {
+								"line": 6,
+								"column": 22
+							}
+						},
 						"range": [
 							73,
 							86
@@ -84,6 +164,16 @@
 						"type": "Identifier",
 						"start": 73,
 						"end": 86,
+						"loc": {
+							"start": {
+								"line": 6,
+								"column": 9
+							},
+							"end": {
+								"line": 6,
+								"column": 22
+							}
+						},
 						"range": [
 							73,
 							86
@@ -105,7 +195,17 @@
 			"range": [
 				0,
 				34
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json b/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
index bc6f890a7fb83d..9c17f5ad7401d9 100644
--- a/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 141,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 44
+		}
+	},
 	"range": [
 		35,
 		140
@@ -11,6 +21,16 @@
 			"type": "VariableDeclaration",
 			"start": 35,
 			"end": 94,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 59
+				}
+			},
 			"range": [
 				35,
 				94
@@ -20,6 +40,16 @@
 					"type": "VariableDeclarator",
 					"start": 41,
 					"end": 93,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 6
+						},
+						"end": {
+							"line": 4,
+							"column": 58
+						}
+					},
 					"range": [
 						41,
 						93
@@ -28,6 +58,16 @@
 						"type": "ObjectPattern",
 						"start": 41,
 						"end": 60,
+						"loc": {
+							"start": {
+								"line": 4,
+								"column": 6
+							},
+							"end": {
+								"line": 4,
+								"column": 25
+							}
+						},
 						"range": [
 							41,
 							60
@@ -37,6 +77,16 @@
 								"type": "Property",
 								"start": 43,
 								"end": 58,
+								"loc": {
+									"start": {
+										"line": 4,
+										"column": 8
+									},
+									"end": {
+										"line": 4,
+										"column": 23
+									}
+								},
 								"range": [
 									43,
 									58
@@ -48,6 +98,16 @@
 									"type": "Identifier",
 									"start": 43,
 									"end": 58,
+									"loc": {
+										"start": {
+											"line": 4,
+											"column": 8
+										},
+										"end": {
+											"line": 4,
+											"column": 23
+										}
+									},
 									"range": [
 										43,
 										58
@@ -59,6 +119,16 @@
 									"type": "Identifier",
 									"start": 43,
 									"end": 58,
+									"loc": {
+										"start": {
+											"line": 4,
+											"column": 8
+										},
+										"end": {
+											"line": 4,
+											"column": 23
+										}
+									},
 									"range": [
 										43,
 										58
@@ -72,6 +142,16 @@
 						"type": "ObjectExpression",
 						"start": 63,
 						"end": 93,
+						"loc": {
+							"start": {
+								"line": 4,
+								"column": 28
+							},
+							"end": {
+								"line": 4,
+								"column": 58
+							}
+						},
 						"range": [
 							63,
 							93
@@ -81,6 +161,16 @@
 								"type": "Property",
 								"start": 65,
 								"end": 91,
+								"loc": {
+									"start": {
+										"line": 4,
+										"column": 30
+									},
+									"end": {
+										"line": 4,
+										"column": 56
+									}
+								},
 								"range": [
 									65,
 									91
@@ -92,6 +182,16 @@
 									"type": "Identifier",
 									"start": 65,
 									"end": 80,
+									"loc": {
+										"start": {
+											"line": 4,
+											"column": 30
+										},
+										"end": {
+											"line": 4,
+											"column": 45
+										}
+									},
 									"range": [
 										65,
 										80
@@ -102,6 +202,16 @@
 									"type": "ArrowFunctionExpression",
 									"start": 82,
 									"end": 91,
+									"loc": {
+										"start": {
+											"line": 4,
+											"column": 47
+										},
+										"end": {
+											"line": 4,
+											"column": 56
+										}
+									},
 									"range": [
 										82,
 										91
@@ -115,6 +225,16 @@
 										"type": "BlockStatement",
 										"start": 88,
 										"end": 91,
+										"loc": {
+											"start": {
+												"line": 4,
+												"column": 53
+											},
+											"end": {
+												"line": 4,
+												"column": 56
+											}
+										},
 										"range": [
 											88,
 											91
@@ -138,7 +258,17 @@
 					"range": [
 						0,
 						34
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -146,6 +276,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 96,
 			"end": 140,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 6,
+					"column": 44
+				}
+			},
 			"range": [
 				96,
 				140
@@ -156,6 +296,16 @@
 					"type": "ExportSpecifier",
 					"start": 105,
 					"end": 137,
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 9
+						},
+						"end": {
+							"line": 6,
+							"column": 41
+						}
+					},
 					"range": [
 						105,
 						137
@@ -164,6 +314,16 @@
 						"type": "Identifier",
 						"start": 105,
 						"end": 120,
+						"loc": {
+							"start": {
+								"line": 6,
+								"column": 9
+							},
+							"end": {
+								"line": 6,
+								"column": 24
+							}
+						},
 						"range": [
 							105,
 							120
@@ -174,6 +334,16 @@
 						"type": "Identifier",
 						"start": 124,
 						"end": 137,
+						"loc": {
+							"start": {
+								"line": 6,
+								"column": 28
+							},
+							"end": {
+								"line": 6,
+								"column": 41
+							}
+						},
 						"range": [
 							124,
 							137
@@ -195,7 +365,17 @@
 			"range": [
 				0,
 				34
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring.json b/packages/docgen/tests/fixtures/named-identifier-destructuring.json
index b80334dcb1a568..ac2695f1c68fa2 100644
--- a/packages/docgen/tests/fixtures/named-identifier-destructuring.json
+++ b/packages/docgen/tests/fixtures/named-identifier-destructuring.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 96,
 	"end": 140,
+	"loc": {
+		"start": {
+			"line": 6,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 44
+		}
+	},
 	"range": [
 		96,
 		140
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 105,
 			"end": 137,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 9
+				},
+				"end": {
+					"line": 6,
+					"column": 41
+				}
+			},
 			"range": [
 				105,
 				137
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 105,
 				"end": 120,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 9
+					},
+					"end": {
+						"line": 6,
+						"column": 24
+					}
+				},
 				"range": [
 					105,
 					120
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 124,
 				"end": 137,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 28
+					},
+					"end": {
+						"line": 6,
+						"column": 41
+					}
+				},
 				"range": [
 					124,
 					137
diff --git a/packages/docgen/tests/fixtures/named-identifier.json b/packages/docgen/tests/fixtures/named-identifier.json
index 73b4c8f12b95b5..3c2c7680042cfb 100644
--- a/packages/docgen/tests/fixtures/named-identifier.json
+++ b/packages/docgen/tests/fixtures/named-identifier.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 64,
 	"end": 89,
+	"loc": {
+		"start": {
+			"line": 6,
+			"column": 0
+		},
+		"end": {
+			"line": 6,
+			"column": 25
+		}
+	},
 	"range": [
 		64,
 		89
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 73,
 			"end": 86,
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 9
+				},
+				"end": {
+					"line": 6,
+					"column": 22
+				}
+			},
 			"range": [
 				73,
 				86
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 73,
 				"end": 86,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 9
+					},
+					"end": {
+						"line": 6,
+						"column": 22
+					}
+				},
 				"range": [
 					73,
 					86
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 73,
 				"end": 86,
+				"loc": {
+					"start": {
+						"line": 6,
+						"column": 9
+					},
+					"end": {
+						"line": 6,
+						"column": 22
+					}
+				},
 				"range": [
 					73,
 					86
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json b/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
index 3af45ee2d999a1..d761a6035d6c2b 100644
--- a/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 275,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 16,
+			"column": 40
+		}
+	},
 	"range": [
 		41,
 		273
@@ -11,6 +21,16 @@
 			"type": "FunctionDeclaration",
 			"start": 41,
 			"end": 74,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 33
+				}
+			},
 			"range": [
 				41,
 				74
@@ -19,6 +39,16 @@
 				"type": "Identifier",
 				"start": 50,
 				"end": 69,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 9
+					},
+					"end": {
+						"line": 4,
+						"column": 28
+					}
+				},
 				"range": [
 					50,
 					69
@@ -33,6 +63,16 @@
 				"type": "BlockStatement",
 				"start": 72,
 				"end": 74,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 31
+					},
+					"end": {
+						"line": 4,
+						"column": 33
+					}
+				},
 				"range": [
 					72,
 					74
@@ -48,7 +88,17 @@
 					"range": [
 						0,
 						40
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			],
 			"trailingComments": [
@@ -60,7 +110,17 @@
 					"range": [
 						76,
 						113
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 0
+						},
+						"end": {
+							"line": 8,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -68,6 +128,16 @@
 			"type": "ClassDeclaration",
 			"start": 114,
 			"end": 139,
+			"loc": {
+				"start": {
+					"line": 9,
+					"column": 0
+				},
+				"end": {
+					"line": 9,
+					"column": 25
+				}
+			},
 			"range": [
 				114,
 				139
@@ -76,6 +146,16 @@
 				"type": "Identifier",
 				"start": 120,
 				"end": 136,
+				"loc": {
+					"start": {
+						"line": 9,
+						"column": 6
+					},
+					"end": {
+						"line": 9,
+						"column": 22
+					}
+				},
 				"range": [
 					120,
 					136
@@ -87,6 +167,16 @@
 				"type": "ClassBody",
 				"start": 137,
 				"end": 139,
+				"loc": {
+					"start": {
+						"line": 9,
+						"column": 23
+					},
+					"end": {
+						"line": 9,
+						"column": 25
+					}
+				},
 				"range": [
 					137,
 					139
@@ -102,7 +192,17 @@
 					"range": [
 						76,
 						113
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 0
+						},
+						"end": {
+							"line": 8,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -110,6 +210,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 141,
 			"end": 190,
+			"loc": {
+				"start": {
+					"line": 11,
+					"column": 0
+				},
+				"end": {
+					"line": 11,
+					"column": 49
+				}
+			},
 			"range": [
 				141,
 				190
@@ -120,6 +230,16 @@
 					"type": "ExportSpecifier",
 					"start": 150,
 					"end": 169,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 9
+						},
+						"end": {
+							"line": 11,
+							"column": 28
+						}
+					},
 					"range": [
 						150,
 						169
@@ -128,6 +248,16 @@
 						"type": "Identifier",
 						"start": 150,
 						"end": 169,
+						"loc": {
+							"start": {
+								"line": 11,
+								"column": 9
+							},
+							"end": {
+								"line": 11,
+								"column": 28
+							}
+						},
 						"range": [
 							150,
 							169
@@ -138,6 +268,16 @@
 						"type": "Identifier",
 						"start": 150,
 						"end": 169,
+						"loc": {
+							"start": {
+								"line": 11,
+								"column": 9
+							},
+							"end": {
+								"line": 11,
+								"column": 28
+							}
+						},
 						"range": [
 							150,
 							169
@@ -149,6 +289,16 @@
 					"type": "ExportSpecifier",
 					"start": 171,
 					"end": 187,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 30
+						},
+						"end": {
+							"line": 11,
+							"column": 46
+						}
+					},
 					"range": [
 						171,
 						187
@@ -157,6 +307,16 @@
 						"type": "Identifier",
 						"start": 171,
 						"end": 187,
+						"loc": {
+							"start": {
+								"line": 11,
+								"column": 30
+							},
+							"end": {
+								"line": 11,
+								"column": 46
+							}
+						},
 						"range": [
 							171,
 							187
@@ -167,6 +327,16 @@
 						"type": "Identifier",
 						"start": 171,
 						"end": 187,
+						"loc": {
+							"start": {
+								"line": 11,
+								"column": 30
+							},
+							"end": {
+								"line": 11,
+								"column": 46
+							}
+						},
 						"range": [
 							171,
 							187
@@ -185,7 +355,17 @@
 					"range": [
 						192,
 						232
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 13,
+							"column": 0
+						},
+						"end": {
+							"line": 15,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -193,6 +373,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 233,
 			"end": 273,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 0
+				},
+				"end": {
+					"line": 16,
+					"column": 40
+				}
+			},
 			"range": [
 				233,
 				273
@@ -201,6 +391,16 @@
 				"type": "VariableDeclaration",
 				"start": 240,
 				"end": 273,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 7
+					},
+					"end": {
+						"line": 16,
+						"column": 40
+					}
+				},
 				"range": [
 					240,
 					273
@@ -210,6 +410,16 @@
 						"type": "VariableDeclarator",
 						"start": 246,
 						"end": 272,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 13
+							},
+							"end": {
+								"line": 16,
+								"column": 39
+							}
+						},
 						"range": [
 							246,
 							272
@@ -218,6 +428,16 @@
 							"type": "Identifier",
 							"start": 246,
 							"end": 265,
+							"loc": {
+								"start": {
+									"line": 16,
+									"column": 13
+								},
+								"end": {
+									"line": 16,
+									"column": 32
+								}
+							},
 							"range": [
 								246,
 								265
@@ -228,6 +448,16 @@
 							"type": "Literal",
 							"start": 268,
 							"end": 272,
+							"loc": {
+								"start": {
+									"line": 16,
+									"column": 35
+								},
+								"end": {
+									"line": 16,
+									"column": 39
+								}
+							},
 							"range": [
 								268,
 								272
@@ -250,7 +480,17 @@
 					"range": [
 						192,
 						232
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 13,
+							"column": 0
+						},
+						"end": {
+							"line": 15,
+							"column": 3
+						}
+					}
 				}
 			]
 		}
@@ -265,7 +505,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		},
 		{
 			"type": "Block",
@@ -275,7 +525,17 @@
 			"range": [
 				76,
 				113
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 8,
+					"column": 3
+				}
+			}
 		},
 		{
 			"type": "Block",
@@ -285,7 +545,17 @@
 			"range": [
 				192,
 				232
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 13,
+					"column": 0
+				},
+				"end": {
+					"line": 15,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline.json b/packages/docgen/tests/fixtures/named-identifiers-and-inline.json
index 01addf4b90b0f0..960e07f08fd7c8 100644
--- a/packages/docgen/tests/fixtures/named-identifiers-and-inline.json
+++ b/packages/docgen/tests/fixtures/named-identifiers-and-inline.json
@@ -3,6 +3,16 @@
 		"type": "ExportNamedDeclaration",
 		"start": 141,
 		"end": 190,
+		"loc": {
+			"start": {
+				"line": 11,
+				"column": 0
+			},
+			"end": {
+				"line": 11,
+				"column": 49
+			}
+		},
 		"range": [
 			141,
 			190
@@ -13,6 +23,16 @@
 				"type": "ExportSpecifier",
 				"start": 150,
 				"end": 169,
+				"loc": {
+					"start": {
+						"line": 11,
+						"column": 9
+					},
+					"end": {
+						"line": 11,
+						"column": 28
+					}
+				},
 				"range": [
 					150,
 					169
@@ -21,6 +41,16 @@
 					"type": "Identifier",
 					"start": 150,
 					"end": 169,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 9
+						},
+						"end": {
+							"line": 11,
+							"column": 28
+						}
+					},
 					"range": [
 						150,
 						169
@@ -31,6 +61,16 @@
 					"type": "Identifier",
 					"start": 150,
 					"end": 169,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 9
+						},
+						"end": {
+							"line": 11,
+							"column": 28
+						}
+					},
 					"range": [
 						150,
 						169
@@ -42,6 +82,16 @@
 				"type": "ExportSpecifier",
 				"start": 171,
 				"end": 187,
+				"loc": {
+					"start": {
+						"line": 11,
+						"column": 30
+					},
+					"end": {
+						"line": 11,
+						"column": 46
+					}
+				},
 				"range": [
 					171,
 					187
@@ -50,6 +100,16 @@
 					"type": "Identifier",
 					"start": 171,
 					"end": 187,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 30
+						},
+						"end": {
+							"line": 11,
+							"column": 46
+						}
+					},
 					"range": [
 						171,
 						187
@@ -60,6 +120,16 @@
 					"type": "Identifier",
 					"start": 171,
 					"end": 187,
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 30
+						},
+						"end": {
+							"line": 11,
+							"column": 46
+						}
+					},
 					"range": [
 						171,
 						187
@@ -78,7 +148,17 @@
 				"range": [
 					192,
 					232
-				]
+				],
+				"loc": {
+					"start": {
+						"line": 13,
+						"column": 0
+					},
+					"end": {
+						"line": 15,
+						"column": 3
+					}
+				}
 			}
 		]
 	},
@@ -86,6 +166,16 @@
 		"type": "ExportNamedDeclaration",
 		"start": 233,
 		"end": 273,
+		"loc": {
+			"start": {
+				"line": 16,
+				"column": 0
+			},
+			"end": {
+				"line": 16,
+				"column": 40
+			}
+		},
 		"range": [
 			233,
 			273
@@ -94,6 +184,16 @@
 			"type": "VariableDeclaration",
 			"start": 240,
 			"end": 273,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 7
+				},
+				"end": {
+					"line": 16,
+					"column": 40
+				}
+			},
 			"range": [
 				240,
 				273
@@ -103,6 +203,16 @@
 					"type": "VariableDeclarator",
 					"start": 246,
 					"end": 272,
+					"loc": {
+						"start": {
+							"line": 16,
+							"column": 13
+						},
+						"end": {
+							"line": 16,
+							"column": 39
+						}
+					},
 					"range": [
 						246,
 						272
@@ -111,6 +221,16 @@
 						"type": "Identifier",
 						"start": 246,
 						"end": 265,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 13
+							},
+							"end": {
+								"line": 16,
+								"column": 32
+							}
+						},
 						"range": [
 							246,
 							265
@@ -121,6 +241,16 @@
 						"type": "Literal",
 						"start": 268,
 						"end": 272,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 35
+							},
+							"end": {
+								"line": 16,
+								"column": 39
+							}
+						},
 						"range": [
 							268,
 							272
@@ -143,7 +273,17 @@
 				"range": [
 					192,
 					232
-				]
+				],
+				"loc": {
+					"start": {
+						"line": 13,
+						"column": 0
+					},
+					"end": {
+						"line": 15,
+						"column": 3
+					}
+				}
 			}
 		]
 	}
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ast.json b/packages/docgen/tests/fixtures/named-identifiers-ast.json
index 0fa80b3d38b654..f6aa5b92541abc 100644
--- a/packages/docgen/tests/fixtures/named-identifiers-ast.json
+++ b/packages/docgen/tests/fixtures/named-identifiers-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 288,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 16,
+			"column": 70
+		}
+	},
 	"range": [
 		41,
 		287
@@ -11,6 +21,16 @@
 			"type": "FunctionDeclaration",
 			"start": 41,
 			"end": 74,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 0
+				},
+				"end": {
+					"line": 4,
+					"column": 33
+				}
+			},
 			"range": [
 				41,
 				74
@@ -19,6 +39,16 @@
 				"type": "Identifier",
 				"start": 50,
 				"end": 69,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 9
+					},
+					"end": {
+						"line": 4,
+						"column": 28
+					}
+				},
 				"range": [
 					50,
 					69
@@ -33,6 +63,16 @@
 				"type": "BlockStatement",
 				"start": 72,
 				"end": 74,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 31
+					},
+					"end": {
+						"line": 4,
+						"column": 33
+					}
+				},
 				"range": [
 					72,
 					74
@@ -48,7 +88,17 @@
 					"range": [
 						0,
 						40
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 0
+						},
+						"end": {
+							"line": 3,
+							"column": 3
+						}
+					}
 				}
 			],
 			"trailingComments": [
@@ -60,7 +110,17 @@
 					"range": [
 						76,
 						113
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 0
+						},
+						"end": {
+							"line": 8,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -68,6 +128,16 @@
 			"type": "ClassDeclaration",
 			"start": 114,
 			"end": 139,
+			"loc": {
+				"start": {
+					"line": 9,
+					"column": 0
+				},
+				"end": {
+					"line": 9,
+					"column": 25
+				}
+			},
 			"range": [
 				114,
 				139
@@ -76,6 +146,16 @@
 				"type": "Identifier",
 				"start": 120,
 				"end": 136,
+				"loc": {
+					"start": {
+						"line": 9,
+						"column": 6
+					},
+					"end": {
+						"line": 9,
+						"column": 22
+					}
+				},
 				"range": [
 					120,
 					136
@@ -87,6 +167,16 @@
 				"type": "ClassBody",
 				"start": 137,
 				"end": 139,
+				"loc": {
+					"start": {
+						"line": 9,
+						"column": 23
+					},
+					"end": {
+						"line": 9,
+						"column": 25
+					}
+				},
 				"range": [
 					137,
 					139
@@ -102,7 +192,17 @@
 					"range": [
 						76,
 						113
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 6,
+							"column": 0
+						},
+						"end": {
+							"line": 8,
+							"column": 3
+						}
+					}
 				}
 			],
 			"trailingComments": [
@@ -114,7 +214,17 @@
 					"range": [
 						141,
 						181
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 0
+						},
+						"end": {
+							"line": 13,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -122,6 +232,16 @@
 			"type": "VariableDeclaration",
 			"start": 182,
 			"end": 215,
+			"loc": {
+				"start": {
+					"line": 14,
+					"column": 0
+				},
+				"end": {
+					"line": 14,
+					"column": 33
+				}
+			},
 			"range": [
 				182,
 				215
@@ -131,6 +251,16 @@
 					"type": "VariableDeclarator",
 					"start": 188,
 					"end": 214,
+					"loc": {
+						"start": {
+							"line": 14,
+							"column": 6
+						},
+						"end": {
+							"line": 14,
+							"column": 32
+						}
+					},
 					"range": [
 						188,
 						214
@@ -139,6 +269,16 @@
 						"type": "Identifier",
 						"start": 188,
 						"end": 207,
+						"loc": {
+							"start": {
+								"line": 14,
+								"column": 6
+							},
+							"end": {
+								"line": 14,
+								"column": 25
+							}
+						},
 						"range": [
 							188,
 							207
@@ -149,6 +289,16 @@
 						"type": "Literal",
 						"start": 210,
 						"end": 214,
+						"loc": {
+							"start": {
+								"line": 14,
+								"column": 28
+							},
+							"end": {
+								"line": 14,
+								"column": 32
+							}
+						},
 						"range": [
 							210,
 							214
@@ -168,7 +318,17 @@
 					"range": [
 						141,
 						181
-					]
+					],
+					"loc": {
+						"start": {
+							"line": 11,
+							"column": 0
+						},
+						"end": {
+							"line": 13,
+							"column": 3
+						}
+					}
 				}
 			]
 		},
@@ -176,6 +336,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 217,
 			"end": 287,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 0
+				},
+				"end": {
+					"line": 16,
+					"column": 70
+				}
+			},
 			"range": [
 				217,
 				287
@@ -186,6 +356,16 @@
 					"type": "ExportSpecifier",
 					"start": 226,
 					"end": 245,
+					"loc": {
+						"start": {
+							"line": 16,
+							"column": 9
+						},
+						"end": {
+							"line": 16,
+							"column": 28
+						}
+					},
 					"range": [
 						226,
 						245
@@ -194,6 +374,16 @@
 						"type": "Identifier",
 						"start": 226,
 						"end": 245,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 9
+							},
+							"end": {
+								"line": 16,
+								"column": 28
+							}
+						},
 						"range": [
 							226,
 							245
@@ -204,6 +394,16 @@
 						"type": "Identifier",
 						"start": 226,
 						"end": 245,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 9
+							},
+							"end": {
+								"line": 16,
+								"column": 28
+							}
+						},
 						"range": [
 							226,
 							245
@@ -215,6 +415,16 @@
 					"type": "ExportSpecifier",
 					"start": 247,
 					"end": 266,
+					"loc": {
+						"start": {
+							"line": 16,
+							"column": 30
+						},
+						"end": {
+							"line": 16,
+							"column": 49
+						}
+					},
 					"range": [
 						247,
 						266
@@ -223,6 +433,16 @@
 						"type": "Identifier",
 						"start": 247,
 						"end": 266,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 30
+							},
+							"end": {
+								"line": 16,
+								"column": 49
+							}
+						},
 						"range": [
 							247,
 							266
@@ -233,6 +453,16 @@
 						"type": "Identifier",
 						"start": 247,
 						"end": 266,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 30
+							},
+							"end": {
+								"line": 16,
+								"column": 49
+							}
+						},
 						"range": [
 							247,
 							266
@@ -244,6 +474,16 @@
 					"type": "ExportSpecifier",
 					"start": 268,
 					"end": 284,
+					"loc": {
+						"start": {
+							"line": 16,
+							"column": 51
+						},
+						"end": {
+							"line": 16,
+							"column": 67
+						}
+					},
 					"range": [
 						268,
 						284
@@ -252,6 +492,16 @@
 						"type": "Identifier",
 						"start": 268,
 						"end": 284,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 51
+							},
+							"end": {
+								"line": 16,
+								"column": 67
+							}
+						},
 						"range": [
 							268,
 							284
@@ -262,6 +512,16 @@
 						"type": "Identifier",
 						"start": 268,
 						"end": 284,
+						"loc": {
+							"start": {
+								"line": 16,
+								"column": 51
+							},
+							"end": {
+								"line": 16,
+								"column": 67
+							}
+						},
 						"range": [
 							268,
 							284
@@ -283,7 +543,17 @@
 			"range": [
 				0,
 				40
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		},
 		{
 			"type": "Block",
@@ -293,7 +563,17 @@
 			"range": [
 				76,
 				113
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 6,
+					"column": 0
+				},
+				"end": {
+					"line": 8,
+					"column": 3
+				}
+			}
 		},
 		{
 			"type": "Block",
@@ -303,7 +583,17 @@
 			"range": [
 				141,
 				181
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 11,
+					"column": 0
+				},
+				"end": {
+					"line": 13,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ir.json b/packages/docgen/tests/fixtures/named-identifiers-ir.json
index 961dc6650583e4..ab7e9787fa15f4 100644
--- a/packages/docgen/tests/fixtures/named-identifiers-ir.json
+++ b/packages/docgen/tests/fixtures/named-identifiers-ir.json
@@ -1,23 +1 @@
-[
-	{
-		"name": "functionDeclaration",
-		"description": "Function declaration example.",
-		"params": [],
-		"return": [],
-		"tags": []
-	},
-	{
-		"name": "variableDeclaration",
-		"description": "Variable declaration example.",
-		"params": [],
-		"return": [],
-		"tags": []
-	},
-	{
-		"name": "ClassDeclaration",
-		"description": "Class declaration example.",
-		"params": [],
-		"return": [],
-		"tags": []
-	}
-]
\ No newline at end of file
+[{"name":"ClassDeclaration","description":"Class declaration example.","tags":[]},{"name":"functionDeclaration","description":"Function declaration example.","tags":[]},{"name":"variableDeclaration","description":"Variable declaration example.","tags":[]}]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-identifiers.json b/packages/docgen/tests/fixtures/named-identifiers.json
index 918c76213557ca..eb1e017e311b42 100644
--- a/packages/docgen/tests/fixtures/named-identifiers.json
+++ b/packages/docgen/tests/fixtures/named-identifiers.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 217,
 	"end": 287,
+	"loc": {
+		"start": {
+			"line": 16,
+			"column": 0
+		},
+		"end": {
+			"line": 16,
+			"column": 70
+		}
+	},
 	"range": [
 		217,
 		287
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 226,
 			"end": 245,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 9
+				},
+				"end": {
+					"line": 16,
+					"column": 28
+				}
+			},
 			"range": [
 				226,
 				245
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 226,
 				"end": 245,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 9
+					},
+					"end": {
+						"line": 16,
+						"column": 28
+					}
+				},
 				"range": [
 					226,
 					245
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 226,
 				"end": 245,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 9
+					},
+					"end": {
+						"line": 16,
+						"column": 28
+					}
+				},
 				"range": [
 					226,
 					245
@@ -41,6 +81,16 @@
 			"type": "ExportSpecifier",
 			"start": 247,
 			"end": 266,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 30
+				},
+				"end": {
+					"line": 16,
+					"column": 49
+				}
+			},
 			"range": [
 				247,
 				266
@@ -49,6 +99,16 @@
 				"type": "Identifier",
 				"start": 247,
 				"end": 266,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 30
+					},
+					"end": {
+						"line": 16,
+						"column": 49
+					}
+				},
 				"range": [
 					247,
 					266
@@ -59,6 +119,16 @@
 				"type": "Identifier",
 				"start": 247,
 				"end": 266,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 30
+					},
+					"end": {
+						"line": 16,
+						"column": 49
+					}
+				},
 				"range": [
 					247,
 					266
@@ -70,6 +140,16 @@
 			"type": "ExportSpecifier",
 			"start": 268,
 			"end": 284,
+			"loc": {
+				"start": {
+					"line": 16,
+					"column": 51
+				},
+				"end": {
+					"line": 16,
+					"column": 67
+				}
+			},
 			"range": [
 				268,
 				284
@@ -78,6 +158,16 @@
 				"type": "Identifier",
 				"start": 268,
 				"end": 284,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 51
+					},
+					"end": {
+						"line": 16,
+						"column": 67
+					}
+				},
 				"range": [
 					268,
 					284
@@ -88,6 +178,16 @@
 				"type": "Identifier",
 				"start": 268,
 				"end": 284,
+				"loc": {
+					"start": {
+						"line": 16,
+						"column": 51
+					},
+					"end": {
+						"line": 16,
+						"column": 67
+					}
+				},
 				"range": [
 					268,
 					284
diff --git a/packages/docgen/tests/fixtures/named-import-named.json b/packages/docgen/tests/fixtures/named-import-named.json
index e042900ea14a3e..8d3340586992f9 100644
--- a/packages/docgen/tests/fixtures/named-import-named.json
+++ b/packages/docgen/tests/fixtures/named-import-named.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 0,
 	"end": 101,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 5,
+			"column": 29
+		}
+	},
 	"range": [
 		0,
 		101
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 10,
 			"end": 29,
+			"loc": {
+				"start": {
+					"line": 2,
+					"column": 1
+				},
+				"end": {
+					"line": 2,
+					"column": 20
+				}
+			},
 			"range": [
 				10,
 				29
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 10,
 				"end": 29,
+				"loc": {
+					"start": {
+						"line": 2,
+						"column": 1
+					},
+					"end": {
+						"line": 2,
+						"column": 20
+					}
+				},
 				"range": [
 					10,
 					29
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 10,
 				"end": 29,
+				"loc": {
+					"start": {
+						"line": 2,
+						"column": 1
+					},
+					"end": {
+						"line": 2,
+						"column": 20
+					}
+				},
 				"range": [
 					10,
 					29
@@ -41,6 +81,16 @@
 			"type": "ExportSpecifier",
 			"start": 32,
 			"end": 51,
+			"loc": {
+				"start": {
+					"line": 3,
+					"column": 1
+				},
+				"end": {
+					"line": 3,
+					"column": 20
+				}
+			},
 			"range": [
 				32,
 				51
@@ -49,6 +99,16 @@
 				"type": "Identifier",
 				"start": 32,
 				"end": 51,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 1
+					},
+					"end": {
+						"line": 3,
+						"column": 20
+					}
+				},
 				"range": [
 					32,
 					51
@@ -59,6 +119,16 @@
 				"type": "Identifier",
 				"start": 32,
 				"end": 51,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 1
+					},
+					"end": {
+						"line": 3,
+						"column": 20
+					}
+				},
 				"range": [
 					32,
 					51
@@ -70,6 +140,16 @@
 			"type": "ExportSpecifier",
 			"start": 54,
 			"end": 70,
+			"loc": {
+				"start": {
+					"line": 4,
+					"column": 1
+				},
+				"end": {
+					"line": 4,
+					"column": 17
+				}
+			},
 			"range": [
 				54,
 				70
@@ -78,6 +158,16 @@
 				"type": "Identifier",
 				"start": 54,
 				"end": 70,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 1
+					},
+					"end": {
+						"line": 4,
+						"column": 17
+					}
+				},
 				"range": [
 					54,
 					70
@@ -88,6 +178,16 @@
 				"type": "Identifier",
 				"start": 54,
 				"end": 70,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 1
+					},
+					"end": {
+						"line": 4,
+						"column": 17
+					}
+				},
 				"range": [
 					54,
 					70
@@ -100,6 +200,16 @@
 		"type": "Literal",
 		"start": 79,
 		"end": 100,
+		"loc": {
+			"start": {
+				"line": 5,
+				"column": 7
+			},
+			"end": {
+				"line": 5,
+				"column": 28
+			}
+		},
 		"range": [
 			79,
 			100
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-ast.json b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
index decd724de3af07..f17b43fcef7533 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace-ast.json
+++ b/packages/docgen/tests/fixtures/named-import-namespace-ast.json
@@ -2,6 +2,16 @@
 	"type": "Program",
 	"start": 0,
 	"end": 85,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 21
+		}
+	},
 	"range": [
 		0,
 		84
@@ -11,6 +21,16 @@
 			"type": "ImportDeclaration",
 			"start": 0,
 			"end": 61,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 1,
+					"column": 61
+				}
+			},
 			"range": [
 				0,
 				61
@@ -20,6 +40,16 @@
 					"type": "ImportNamespaceSpecifier",
 					"start": 7,
 					"end": 21,
+					"loc": {
+						"start": {
+							"line": 1,
+							"column": 7
+						},
+						"end": {
+							"line": 1,
+							"column": 21
+						}
+					},
 					"range": [
 						7,
 						21
@@ -28,6 +58,16 @@
 						"type": "Identifier",
 						"start": 12,
 						"end": 21,
+						"loc": {
+							"start": {
+								"line": 1,
+								"column": 12
+							},
+							"end": {
+								"line": 1,
+								"column": 21
+							}
+						},
 						"range": [
 							12,
 							21
@@ -40,6 +80,16 @@
 				"type": "Literal",
 				"start": 27,
 				"end": 60,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 27
+					},
+					"end": {
+						"line": 1,
+						"column": 60
+					}
+				},
 				"range": [
 					27,
 					60
@@ -52,6 +102,16 @@
 			"type": "ExportNamedDeclaration",
 			"start": 63,
 			"end": 84,
+			"loc": {
+				"start": {
+					"line": 3,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 21
+				}
+			},
 			"range": [
 				63,
 				84
@@ -62,6 +122,16 @@
 					"type": "ExportSpecifier",
 					"start": 72,
 					"end": 81,
+					"loc": {
+						"start": {
+							"line": 3,
+							"column": 9
+						},
+						"end": {
+							"line": 3,
+							"column": 18
+						}
+					},
 					"range": [
 						72,
 						81
@@ -70,6 +140,16 @@
 						"type": "Identifier",
 						"start": 72,
 						"end": 81,
+						"loc": {
+							"start": {
+								"line": 3,
+								"column": 9
+							},
+							"end": {
+								"line": 3,
+								"column": 18
+							}
+						},
 						"range": [
 							72,
 							81
@@ -80,6 +160,16 @@
 						"type": "Identifier",
 						"start": 72,
 						"end": 81,
+						"loc": {
+							"start": {
+								"line": 3,
+								"column": 9
+							},
+							"end": {
+								"line": 3,
+								"column": 18
+							}
+						},
 						"range": [
 							72,
 							81
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module.json b/packages/docgen/tests/fixtures/named-import-namespace-module.json
index dba6c3a8856810..3e467a9404209a 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace-module.json
+++ b/packages/docgen/tests/fixtures/named-import-namespace-module.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 0,
 	"end": 63,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 1,
+			"column": 63
+		}
+	},
 	"range": [
 		0,
 		63
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 9,
 			"end": 28,
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 9
+				},
+				"end": {
+					"line": 1,
+					"column": 28
+				}
+			},
 			"range": [
 				9,
 				28
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 9,
 				"end": 16,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 9
+					},
+					"end": {
+						"line": 1,
+						"column": 16
+					}
+				},
 				"range": [
 					9,
 					16
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 20,
 				"end": 28,
+				"loc": {
+					"start": {
+						"line": 1,
+						"column": 20
+					},
+					"end": {
+						"line": 1,
+						"column": 28
+					}
+				},
 				"range": [
 					20,
 					28
@@ -42,6 +82,16 @@
 		"type": "Literal",
 		"start": 36,
 		"end": 62,
+		"loc": {
+			"start": {
+				"line": 1,
+				"column": 36
+			},
+			"end": {
+				"line": 1,
+				"column": 62
+			}
+		},
 		"range": [
 			36,
 			62
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.json b/packages/docgen/tests/fixtures/named-import-namespace.json
index 044a07d8735adb..a2ea24189479d3 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace.json
+++ b/packages/docgen/tests/fixtures/named-import-namespace.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 63,
 	"end": 84,
+	"loc": {
+		"start": {
+			"line": 3,
+			"column": 0
+		},
+		"end": {
+			"line": 3,
+			"column": 21
+		}
+	},
 	"range": [
 		63,
 		84
@@ -12,6 +22,16 @@
 			"type": "ExportSpecifier",
 			"start": 72,
 			"end": 81,
+			"loc": {
+				"start": {
+					"line": 3,
+					"column": 9
+				},
+				"end": {
+					"line": 3,
+					"column": 18
+				}
+			},
 			"range": [
 				72,
 				81
@@ -20,6 +40,16 @@
 				"type": "Identifier",
 				"start": 72,
 				"end": 81,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 9
+					},
+					"end": {
+						"line": 3,
+						"column": 18
+					}
+				},
 				"range": [
 					72,
 					81
@@ -30,6 +60,16 @@
 				"type": "Identifier",
 				"start": 72,
 				"end": 81,
+				"loc": {
+					"start": {
+						"line": 3,
+						"column": 9
+					},
+					"end": {
+						"line": 3,
+						"column": 18
+					}
+				},
 				"range": [
 					72,
 					81
diff --git a/packages/docgen/tests/fixtures/named-variable.json b/packages/docgen/tests/fixtures/named-variable.json
index a5cab04541dfef..1c5797990ceab8 100644
--- a/packages/docgen/tests/fixtures/named-variable.json
+++ b/packages/docgen/tests/fixtures/named-variable.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 35,
 	"end": 69,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 34
+		}
+	},
 	"range": [
 		35,
 		69
@@ -10,6 +20,16 @@
 		"type": "VariableDeclaration",
 		"start": 42,
 		"end": 69,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 7
+			},
+			"end": {
+				"line": 4,
+				"column": 34
+			}
+		},
 		"range": [
 			42,
 			69
@@ -19,6 +39,16 @@
 				"type": "VariableDeclarator",
 				"start": 48,
 				"end": 68,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 13
+					},
+					"end": {
+						"line": 4,
+						"column": 33
+					}
+				},
 				"range": [
 					48,
 					68
@@ -27,6 +57,16 @@
 					"type": "Identifier",
 					"start": 48,
 					"end": 61,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 13
+						},
+						"end": {
+							"line": 4,
+							"column": 26
+						}
+					},
 					"range": [
 						48,
 						61
@@ -37,6 +77,16 @@
 					"type": "Literal",
 					"start": 64,
 					"end": 68,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 29
+						},
+						"end": {
+							"line": 4,
+							"column": 33
+						}
+					},
 					"range": [
 						64,
 						68
@@ -59,7 +109,17 @@
 			"range": [
 				0,
 				34
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-variables.json b/packages/docgen/tests/fixtures/named-variables.json
index ac491c7dcafc04..24d1d1525e9501 100644
--- a/packages/docgen/tests/fixtures/named-variables.json
+++ b/packages/docgen/tests/fixtures/named-variables.json
@@ -2,6 +2,16 @@
 	"type": "ExportNamedDeclaration",
 	"start": 35,
 	"end": 97,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 5,
+			"column": 24
+		}
+	},
 	"range": [
 		35,
 		97
@@ -10,6 +20,16 @@
 		"type": "VariableDeclaration",
 		"start": 42,
 		"end": 97,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 7
+			},
+			"end": {
+				"line": 5,
+				"column": 24
+			}
+		},
 		"range": [
 			42,
 			97
@@ -19,6 +39,16 @@
 				"type": "VariableDeclarator",
 				"start": 48,
 				"end": 71,
+				"loc": {
+					"start": {
+						"line": 4,
+						"column": 13
+					},
+					"end": {
+						"line": 4,
+						"column": 36
+					}
+				},
 				"range": [
 					48,
 					71
@@ -27,6 +57,16 @@
 					"type": "Identifier",
 					"start": 48,
 					"end": 64,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 13
+						},
+						"end": {
+							"line": 4,
+							"column": 29
+						}
+					},
 					"range": [
 						48,
 						64
@@ -37,6 +77,16 @@
 					"type": "Literal",
 					"start": 67,
 					"end": 71,
+					"loc": {
+						"start": {
+							"line": 4,
+							"column": 32
+						},
+						"end": {
+							"line": 4,
+							"column": 36
+						}
+					},
 					"range": [
 						67,
 						71
@@ -49,6 +99,16 @@
 				"type": "VariableDeclarator",
 				"start": 74,
 				"end": 96,
+				"loc": {
+					"start": {
+						"line": 5,
+						"column": 1
+					},
+					"end": {
+						"line": 5,
+						"column": 23
+					}
+				},
 				"range": [
 					74,
 					96
@@ -57,6 +117,16 @@
 					"type": "Identifier",
 					"start": 74,
 					"end": 91,
+					"loc": {
+						"start": {
+							"line": 5,
+							"column": 1
+						},
+						"end": {
+							"line": 5,
+							"column": 18
+						}
+					},
 					"range": [
 						74,
 						91
@@ -67,6 +137,16 @@
 					"type": "Literal",
 					"start": 94,
 					"end": 96,
+					"loc": {
+						"start": {
+							"line": 5,
+							"column": 21
+						},
+						"end": {
+							"line": 5,
+							"column": 23
+						}
+					},
 					"range": [
 						94,
 						96
@@ -89,7 +169,17 @@
 			"range": [
 				0,
 				34
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/namespace-commented.json b/packages/docgen/tests/fixtures/namespace-commented.json
index 0448308fd91a41..37166ddd12a5ca 100644
--- a/packages/docgen/tests/fixtures/namespace-commented.json
+++ b/packages/docgen/tests/fixtures/namespace-commented.json
@@ -2,6 +2,16 @@
 	"type": "ExportAllDeclaration",
 	"start": 43,
 	"end": 78,
+	"loc": {
+		"start": {
+			"line": 4,
+			"column": 0
+		},
+		"end": {
+			"line": 4,
+			"column": 35
+		}
+	},
 	"range": [
 		43,
 		78
@@ -10,6 +20,16 @@
 		"type": "Literal",
 		"start": 57,
 		"end": 77,
+		"loc": {
+			"start": {
+				"line": 4,
+				"column": 14
+			},
+			"end": {
+				"line": 4,
+				"column": 34
+			}
+		},
 		"range": [
 			57,
 			77
@@ -26,7 +46,17 @@
 			"range": [
 				0,
 				42
-			]
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 3,
+					"column": 3
+				}
+			}
 		}
 	]
 }
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/namespace-module-ir.json b/packages/docgen/tests/fixtures/namespace-module-ir.json
index 803944d60e1d7d..7798095b482fac 100644
--- a/packages/docgen/tests/fixtures/namespace-module-ir.json
+++ b/packages/docgen/tests/fixtures/namespace-module-ir.json
@@ -1,22 +1,22 @@
 [
 	{
-		"name": "myVariable",
-		"description": "Named variable.",
+		"name": "default",
+		"description": "Default variable declaration.",
 		"tags": []
 	},
 	{
-		"name": "myFunction",
-		"description": "Named function.",
+		"name": "MyClass",
+		"description": "Named class.",
 		"tags": []
 	},
 	{
-		"name": "MyClass",
-		"description": "Named class.",
+		"name": "myFunction",
+		"description": "Named function.",
 		"tags": []
 	},
 	{
-		"name": "default",
-		"description": "Default variable declaration.",
+		"name": "myVariable",
+		"description": "Named variable.",
 		"tags": []
 	}
 ]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/namespace.json b/packages/docgen/tests/fixtures/namespace.json
index 1a2ba4a6e73c69..d6aa32af9ac61e 100644
--- a/packages/docgen/tests/fixtures/namespace.json
+++ b/packages/docgen/tests/fixtures/namespace.json
@@ -2,6 +2,16 @@
 	"type": "ExportAllDeclaration",
 	"start": 0,
 	"end": 35,
+	"loc": {
+		"start": {
+			"line": 1,
+			"column": 0
+		},
+		"end": {
+			"line": 1,
+			"column": 35
+		}
+	},
 	"range": [
 		0,
 		35
@@ -10,6 +20,16 @@
 		"type": "Literal",
 		"start": 14,
 		"end": 34,
+		"loc": {
+			"start": {
+				"line": 1,
+				"column": 14
+			},
+			"end": {
+				"line": 1,
+				"column": 34
+			}
+		},
 		"range": [
 			14,
 			34
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index cf00049d6a018c..b98ad769857952 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -24,6 +24,8 @@ test( 'Export entries: default class (anonymous)', function( t ) {
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -38,6 +40,8 @@ test( 'Export entries: default class (named)', function( t ) {
 		localName: 'ClassDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -52,6 +56,8 @@ test( 'Export entries: default function (anonymous)', function( t ) {
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -66,6 +72,8 @@ test( 'Export entries: default function (named)', function( t ) {
 		localName: 'myDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -80,6 +88,8 @@ test( 'Export entries: default identifier', function( t ) {
 		localName: 'ClassDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 6,
+		lineEnd: 6,
 	} ] );
 	t.end();
 } );
@@ -94,6 +104,8 @@ test( 'Export entries: default import (named)', function( t ) {
 		localName: 'fnDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 3,
+		lineEnd: 3,
 	} ] );
 	t.end();
 } );
@@ -108,6 +120,8 @@ test( 'Export entries: default import (default)', function( t ) {
 		localName: 'fnDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 3,
+		lineEnd: 3,
 	} ] );
 	t.end();
 } );
@@ -122,12 +136,16 @@ test( 'Export entries: default named export', function( t ) {
 		localName: 'functionDeclaration',
 		exportName: 'functionDeclaration',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const defaultExport = getExportEntries( JSON.parse( tokens )[ 1 ] );
 	t.deepEqual( defaultExport, [ {
 		localName: 'functionDeclaration',
 		exportName: 'default',
 		module: null,
+		lineStart: 6,
+		lineEnd: 6,
 	} ] );
 	t.end();
 } );
@@ -142,6 +160,8 @@ test( 'Export entries: default variable', function( t ) {
 		localName: '*default*',
 		exportName: 'default',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -156,6 +176,8 @@ test( 'Export entries - named class', function( t ) {
 		localName: 'MyDeclaration',
 		exportName: 'MyDeclaration',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -170,6 +192,8 @@ test( 'Export entries - named default', function( t ) {
 		localName: 'default',
 		exportName: 'default',
 		module: './named-default-module',
+		lineStart: 1,
+		lineEnd: 1,
 	} ] );
 	t.end();
 } );
@@ -184,6 +208,8 @@ test( 'Export entries - named default (exported)', function( t ) {
 		localName: 'default',
 		exportName: 'moduleName',
 		module: './named-default-module',
+		lineStart: 1,
+		lineEnd: 1,
 	} ] );
 	t.end();
 } );
@@ -198,6 +224,8 @@ test( 'Export entries - named function', function( t ) {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -212,6 +240,8 @@ test( 'Export entries - named identifier', function( t ) {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
 		module: null,
+		lineStart: 6,
+		lineEnd: 6,
 	} ] );
 	const tokenObject = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
@@ -222,6 +252,8 @@ test( 'Export entries - named identifier', function( t ) {
 		localName: 'someDeclaration',
 		exportName: 'myDeclaration',
 		module: null,
+		lineStart: 6,
+		lineEnd: 6,
 	} ] );
 	t.end();
 } );
@@ -233,9 +265,9 @@ test( 'Export entries - named identifiers', function( t ) {
 	);
 	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [
-		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null },
-		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
-		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null },
+		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 16, lineEnd: 16 },
+		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
+		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 16, lineEnd: 16 },
 	] );
 	const tokenIdentifiersAndInline = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
@@ -243,12 +275,12 @@ test( 'Export entries - named identifiers', function( t ) {
 	);
 	const name0 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 0 ] );
 	t.deepEqual( name0, [
-		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null },
-		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null },
+		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 11, lineEnd: 11 },
+		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 11, lineEnd: 11 },
 	] );
 	const name1 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 1 ] );
 	t.deepEqual( name1, [
-		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null },
+		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
 	] );
 	t.end();
 } );
@@ -260,7 +292,7 @@ test( 'Export entries - named import namespace', function( t ) {
 	);
 	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [
-		{ localName: 'variables', exportName: 'variables', module: null },
+		{ localName: 'variables', exportName: 'variables', module: null, lineStart: 3, lineEnd: 3 },
 	] );
 	t.end();
 } );
@@ -275,6 +307,8 @@ test( 'Export entries - named variable', function( t ) {
 		localName: 'myDeclaration',
 		exportName: 'myDeclaration',
 		module: null,
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -286,8 +320,8 @@ test( 'Export entries - named variables', function( t ) {
 	);
 	const name = getExportEntries( JSON.parse( token ) );
 	t.deepEqual( name, [
-		{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null },
-		{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null },
+		{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null, lineStart: 4, lineEnd: 5 },
+		{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null, lineStart: 4, lineEnd: 5 },
 	] );
 	t.end();
 } );
@@ -302,6 +336,8 @@ test( 'Export entries - namespace (*)', function( t ) {
 		localName: '*',
 		exportName: null,
 		module: './namespace-module',
+		lineStart: 1,
+		lineEnd: 1,
 	} ] );
 	t.end();
 } );
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index c5718145bde23f..281897f8d16cba 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -272,9 +272,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
 			{ name: 'MyClass', description: 'Named class.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
 		]
 	);
 	const tokenCommented = fs.readFileSync(
@@ -284,9 +284,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
 		[
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
 			{ name: 'MyClass', description: 'Named class.', tags: [] },
+			{ name: 'myFunction', description: 'Named function.', tags: [] },
+			{ name: 'myVariable', description: 'Named variable.', tags: [] },
 		]
 	);
 	t.end();

From b91360841e41295737e9cfe6528eda5927dc27e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 13:39:35 +0100
Subject: [PATCH 159/213] Add line number to intermediate representation

---
 .../src/get-intermediate-representation.js    |  4 ++
 .../test-get-intermediate-representation.js   | 70 +++++++++++++------
 2 files changed, 54 insertions(+), 20 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 7fbccdaf5a661d..a9417e574302c6 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -143,6 +143,8 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 					name: namedExport.name,
 					description: namedExport.description,
 					tags: namedExport.tags,
+					lineStart: namedExport.lineStart,
+					lineEnd: namedExport.lineEnd,
 				} );
 			} );
 		} else {
@@ -150,6 +152,8 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
 				tags: get( doc, [ 'tags' ], [] ),
+				lineStart: entry.lineStart,
+				lineEnd: entry.lineEnd,
 			} );
 		}
 	} );
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 281897f8d16cba..b3f791de60d3d0 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -23,6 +23,8 @@ test( 'IR - undocumented', function( t ) {
 		name: 'default',
 		description: 'Undocumented declaration.',
 		tags: [],
+		lineStart: 3,
+		lineEnd: 3,
 	} ] );
 	const tokenOneliner = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-undocumented-oneliner.json' ),
@@ -32,6 +34,8 @@ test( 'IR - undocumented', function( t ) {
 		name: 'default',
 		description: 'Undocumented declaration.',
 		tags: [],
+		lineStart: 2,
+		lineEnd: 2,
 	} ] );
 	t.end();
 } );
@@ -45,6 +49,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenClassNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-named.json' ),
@@ -54,6 +60,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenFnAnonymous = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
@@ -63,6 +71,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		name: 'default',
 		description: 'Function declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenFnNamed = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-named.json' ),
@@ -72,6 +82,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		name: 'default',
 		description: 'Function declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenVariable = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-variable.json' ),
@@ -81,6 +93,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		name: 'default',
 		description: 'Variable declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	t.end();
 } );
@@ -94,6 +108,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		name: 'MyDeclaration',
 		description: 'My declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenFn = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-function.json' ),
@@ -103,6 +119,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenVariable = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-variable.json' ),
@@ -112,14 +130,16 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
+		lineStart: 4,
+		lineEnd: 4,
 	} ] );
 	const tokenVariables = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-variables.json' ),
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariables ) ), [
-		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [] },
-		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [] },
+		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
+		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
 	] );
 	t.end();
 } );
@@ -137,6 +157,8 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
+		lineStart: 6,
+		lineEnd: 6,
 	} ] );
 	const namedExport = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-named-export.json' ),
@@ -148,11 +170,11 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [] } ]
+		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 } ]
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'default', description: 'Function declaration example.', tags: [] } ]
+		[ { name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 } ]
 	);
 	t.end();
 } );
@@ -169,8 +191,10 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		tags: [] },
-	] );
+		tags: [],
+		lineStart: 6,
+		lineEnd: 6,
+	} ] );
 	const tokenObject = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
 		'utf-8'
@@ -182,8 +206,10 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
 		name: 'myDeclaration',
 		description: 'My declaration example.',
-		tags: [] },
-	] );
+		tags: [],
+		lineStart: 6,
+		lineEnd: 6,
+	} ] );
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers.json' ),
 		'utf-8'
@@ -193,9 +219,9 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ), JSON.parse( asts ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
 	] );
 	const foo = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
@@ -206,11 +232,11 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
+		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
 	] );
 	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
+		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
 	] );
 	t.end();
 } );
@@ -227,9 +253,9 @@ test( 'IR - JSDoc in module dependency (named export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
 		[
-			{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [] },
-			{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [] },
-			{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [] },
+			{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 },
+			{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 },
+			{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 },
 		]
 	);
 	t.end();
@@ -246,7 +272,7 @@ test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
 	) );
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { name: 'default', description: 'Module declaration.', tags: [] } ]
+		[ { name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),
@@ -254,7 +280,7 @@ test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
 	);
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { name: 'moduleName', description: 'Module declaration.', tags: [] } ]
+		[ { name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
 	);
 
 	t.end();
@@ -311,6 +337,8 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 			name: 'default',
 			description: 'Function declaration.',
 			tags: [],
+			lineStart: 3,
+			lineEnd: 3,
 		} ]
 	);
 	const tokenNamed = fs.readFileSync(
@@ -331,6 +359,8 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 			name: 'default',
 			description: 'Function declaration.',
 			tags: [],
+			lineStart: 3,
+			lineEnd: 3,
 		} ]
 	);
 	t.end();
@@ -359,7 +389,7 @@ test( 'IR - JSDoc in module dependency through import (named export)', function(
 	};
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { name: 'variables', description: 'Undocumented declaration.', tags: [] } ]
+		[ { name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 } ]
 	);
 	t.end();
 } );

From de6d74bfe9e5ed945b253e0bc6f68da9a033e417 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 13:43:29 +0100
Subject: [PATCH 160/213] Fix line numbers for namespace export

---
 .../docgen/src/get-intermediate-representation.js    |  4 ++--
 .../tests/test-get-intermediate-representation.js    | 12 ++++++------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index a9417e574302c6..21913d7a5dc6e3 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -143,8 +143,8 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 					name: namedExport.name,
 					description: namedExport.description,
 					tags: namedExport.tags,
-					lineStart: namedExport.lineStart,
-					lineEnd: namedExport.lineEnd,
+					lineStart: entry.lineStart,
+					lineEnd: entry.lineEnd,
 				} );
 			} );
 		} else {
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index b3f791de60d3d0..70ef2de96e7730 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -298,9 +298,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
 		[
-			{ name: 'MyClass', description: 'Named class.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 },
+			{ name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 },
+			{ name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 },
 		]
 	);
 	const tokenCommented = fs.readFileSync(
@@ -310,9 +310,9 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 	t.deepEqual(
 		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
 		[
-			{ name: 'MyClass', description: 'Named class.', tags: [] },
-			{ name: 'myFunction', description: 'Named function.', tags: [] },
-			{ name: 'myVariable', description: 'Named variable.', tags: [] },
+			{ name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 },
 		]
 	);
 	t.end();

From c31d43c6060a830272c5b0d167b9b9e19e3c5ebc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 13:45:20 +0100
Subject: [PATCH 161/213] Remove duplicated tests

---
 packages/docgen/tests/test-engine.js | 251 ---------------------------
 1 file changed, 251 deletions(-)

diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
index 557d89a0db3a1f..07a2608e39c9c5 100644
--- a/packages/docgen/tests/test-engine.js
+++ b/packages/docgen/tests/test-engine.js
@@ -8,257 +8,6 @@ const test = require( 'tape' );
  */
 const engine = require( '../src/engine' );
 
-test( 'Engine - many exports at once', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * First declaration example.
- 		 */
-		export const firstDeclaration = function() {
-			// do nothing
-		}
-
-		/**
-		 * Second declaration example.
-		 */
-		export function secondDeclaration(){
-			// do nothing
-		}
-
-		/**
-		 * Default declaration example.
-		 */
-		export default function() {
-			// do nothing
-		}
-` );
-	t.deepEqual(
-		ir,
-		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
-			{ name: 'default', description: 'Default declaration example.', tags: [] },
-		]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (function)', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * My declaration example.
- 		 */
-		export function myDeclaration() {
-			// do nothing
-		}
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (variable)', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * My declaration example.
- 		 */
-		export const myDeclaration = function() {
-			// do nothing
-		}
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (single identifier)', ( t ) => {
-	const { ir } = engine( `
-	const myDeclaration = function() {
-		// do nothing
-	}
-	
-	/**
-	 * My declaration example.
-	 */
-	export { myDeclaration };
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (single identifier) using JSDoc from declaration', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * My declaration example.
- 		 */
-		const myDeclaration = function() {
-			// do nothing
-		}
-
-		export { myDeclaration };
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (multiple identifiers) using JSDoc from declaration', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * First declaration example.
- 		 */
-		const firstDeclaration = function() {
-			// do nothing
-		}
-
-		/**
- 		 * Second declaration example.
- 		 */
-		const secondDeclaration = function() {
-			// do nothing
-		}
-
-		export { firstDeclaration, secondDeclaration };
-` );
-	t.deepEqual(
-		ir,
-		[
-			{ name: 'firstDeclaration', description: 'First declaration example.', tags: [] },
-			{ name: 'secondDeclaration', description: 'Second declaration example.', tags: [] },
-		]
-	);
-	t.end();
-} );
-
-test( 'Engine - named export (single identifier) using JSDoc from dependency', ( t ) => {
-	const dependency = `/**
- 		 * My declaration example.
- 		 */
-		export const myDeclaration = function() {
-			// do nothing
-		}
-	`;
-	const getDependency = () => engine( dependency ).ir;
-	const { ir } = engine(
-		`export { myDeclaration } from './my-dependency';`,
-		getDependency
-	);
-	t.deepEqual(
-		ir,
-		[ { name: 'myDeclaration', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - default export (named function)', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * My declaration example.
- 		 */
-		export default function myDeclaration() {
-			// do nothing
-		}
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - default export (anonymous function)', ( t ) => {
-	const { ir } = engine( `
-		/**
- 		 * My declaration example.
- 		 */
-		export default function() {
-			// do nothing
-		}
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - default export (identifier)', ( t ) => {
-	const { ir } = engine( `
-		function myDeclaration() {
-			// do nothing
-		}
-
-		/**
- 		 * My declaration example.
- 		 */
-		export default myDeclaration;
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - default export (identifier) using JSDoc from function', ( t ) => {
-	const { ir } = engine( `
-		/**
-		 * My declaration example.
-		 */
-		function myDeclaration() {
-			// do nothing
-		}
-
-		export default myDeclaration;
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - default export (identifier) using JSDoc from variable', ( t ) => {
-	const { ir } = engine( `
-		/**
-		 * My declaration example.
-		 */
-		const myDeclaration = function() {
-			// do nothing
-		}
-
-		export default myDeclaration;
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'My declaration example.', tags: [] } ]
-	);
-	t.end();
-} );
-
-test( 'Engine - undocumented export', ( t ) => {
-	const { ir } = engine( `
-		const myDeclaration = function() {
-			// do nothing
-		}
-
-		export default myDeclaration;
-` );
-	t.deepEqual(
-		ir,
-		[ { name: 'default', description: 'Undocumented declaration.', tags: [] } ]
-	);
-	t.end();
-} );
-
 test( 'Engine - undefined code', ( t ) => {
 	const { ir } = engine( undefined );
 	t.deepEqual( ir, [ ] );

From a14178f7d95a3b229419106042ec495ff4328e29 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 13:46:01 +0100
Subject: [PATCH 162/213] Better test names

---
 .../docgen/tests/test-get-export-entries.js    | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
index b98ad769857952..03057dcca87efe 100644
--- a/packages/docgen/tests/test-get-export-entries.js
+++ b/packages/docgen/tests/test-get-export-entries.js
@@ -14,7 +14,7 @@ const test = require( 'tape' );
  */
 const getExportEntries = require( '../src/get-export-entries' );
 
-test( 'Export entries: default class (anonymous)', function( t ) {
+test( 'Export entries - default class (anonymous)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
@@ -30,7 +30,7 @@ test( 'Export entries: default class (anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default class (named)', function( t ) {
+test( 'Export entries - default class (named)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-class-named.json' ),
 		'utf-8'
@@ -46,7 +46,7 @@ test( 'Export entries: default class (named)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default function (anonymous)', function( t ) {
+test( 'Export entries - default function (anonymous)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
 		'utf-8'
@@ -62,7 +62,7 @@ test( 'Export entries: default function (anonymous)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default function (named)', function( t ) {
+test( 'Export entries - default function (named)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-function-named.json' ),
 		'utf-8'
@@ -78,7 +78,7 @@ test( 'Export entries: default function (named)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default identifier', function( t ) {
+test( 'Export entries - default identifier', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-identifier.json' ),
 		'utf-8'
@@ -94,7 +94,7 @@ test( 'Export entries: default identifier', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default import (named)', function( t ) {
+test( 'Export entries - default import (named)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-import-named.json' ),
 		'utf-8'
@@ -110,7 +110,7 @@ test( 'Export entries: default import (named)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default import (default)', function( t ) {
+test( 'Export entries - default import (default)', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-import-default.json' ),
 		'utf-8'
@@ -126,7 +126,7 @@ test( 'Export entries: default import (default)', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default named export', function( t ) {
+test( 'Export entries - default named export', function( t ) {
 	const tokens = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-named-export.json' ),
 		'utf-8'
@@ -150,7 +150,7 @@ test( 'Export entries: default named export', function( t ) {
 	t.end();
 } );
 
-test( 'Export entries: default variable', function( t ) {
+test( 'Export entries - default variable', function( t ) {
 	const token = fs.readFileSync(
 		path.join( __dirname, './fixtures/default-variable.json' ),
 		'utf-8'

From ab9dd27d14039d28d1ff2a79d1bcf18e47227e10 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 17:05:22 +0100
Subject: [PATCH 163/213] Add path to intermediate representation

---
 packages/docgen/src/cli.js                      | 14 ++++++++------
 packages/docgen/src/engine.js                   |  3 ++-
 .../src/get-intermediate-representation.js      | 17 ++++-------------
 3 files changed, 14 insertions(+), 20 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 17832996d6f7b2..f7ec24e35941ea 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -40,20 +40,21 @@ const relativeToAbsolute = ( basePath, relativePath ) => {
 	process.exit( 1 );
 };
 
-const getIRFromRelativePath = ( basePath ) => ( relativePath ) => {
+const getIRFromRelativePath = ( rootDir, basePath ) => ( relativePath ) => {
 	if ( ! relativePath.startsWith( './' ) ) {
 		return [];
 	}
 	const absolutePath = relativeToAbsolute( basePath, relativePath );
-	const result = processFile( absolutePath );
+	const result = processFile( rootDir, absolutePath );
 	return result.ir || undefined;
 };
 
-const processFile = ( inputFile ) => {
+const processFile = ( rootDir, inputFile ) => {
 	try {
 		const data = fs.readFileSync( inputFile, 'utf8' );
 		currentFileStack.push( inputFile );
-		const result = engine( data, getIRFromRelativePath( last( currentFileStack ) ) );
+		const relativePath = path.relative( rootDir, inputFile );
+		const result = engine( relativePath, data, getIRFromRelativePath( rootDir, last( currentFileStack ) ) );
 		currentFileStack.pop( inputFile );
 		return result;
 	} catch ( e ) {
@@ -68,19 +69,20 @@ const processFile = ( inputFile ) => {
  */
 
 // Prepare input
+const processDir = process.cwd();
 let initialInputFile = process.argv[ 2 ];
 if ( initialInputFile === undefined ) {
 	process.stdout.write( '\nUsage: <path-to-docgen> <relative-path-to-entry-point.js>' );
 	process.stdout.write( '\n\n' );
 	process.exit( 1 );
 }
-initialInputFile = path.join( process.cwd(), initialInputFile );
+initialInputFile = path.join( processDir, initialInputFile );
 
 const debugMode = process.argv[ 3 ] === '--debug' ? true : false;
 
 // Process
 const currentFileStack = []; // To keep track of file being processed.
-const result = processFile( initialInputFile );
+const result = processFile( processDir, initialInputFile );
 
 // Ouput
 const inputBase = path.join(
diff --git a/packages/docgen/src/engine.js b/packages/docgen/src/engine.js
index eb9204bce6320f..0c01f94ef9b505 100644
--- a/packages/docgen/src/engine.js
+++ b/packages/docgen/src/engine.js
@@ -27,12 +27,13 @@ const getExportTokens = ( ast ) => ast.body.filter(
 	].some( ( declaration ) => declaration === node.type )
 );
 
-const engine = ( code, getIRFromPath = () => {} ) => {
+const engine = ( path, code, getIRFromPath = () => {} ) => {
 	const result = {};
 	result.ast = getAST( code );
 	result.tokens = getExportTokens( result.ast );
 	result.ir = flatten( result.tokens.map(
 		( token ) => getIntermediateRepresentation(
+			path,
 			token,
 			result.ast,
 			getIRFromPath
diff --git a/packages/docgen/src/get-intermediate-representation.js b/packages/docgen/src/get-intermediate-representation.js
index 21913d7a5dc6e3..eee7775d69979a 100644
--- a/packages/docgen/src/get-intermediate-representation.js
+++ b/packages/docgen/src/get-intermediate-representation.js
@@ -46,18 +46,6 @@ const hasImportWithName = ( node, name ) =>
 
 const isImportDeclaration = ( node ) => node.type === 'ImportDeclaration';
 
-// const someSpecifierMatchesName = ( name, node ) => node.specifiers.some( ( specifier ) => {
-// 	if ( specifier.type === 'ImportDefaultSpecifier' ) {
-// 		return name === 'default';
-// 	} else if (
-// 		specifier.type === 'ExportSpecifier' ||
-// 		specifier.type === 'ImportNamespaceSpecifier'
-// 	) {
-// 		return name === specifier.local.name;
-// 	}
-// 	return name === specifier.imported.name;
-// } );
-
 const someImportMatchesName = ( name, token ) => {
 	let matches = false;
 	token.specifiers.forEach( ( specifier ) => {
@@ -125,6 +113,7 @@ 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 {Function} [parseDependency] Function that takes a path
@@ -132,7 +121,7 @@ const getJSDoc = ( token, entry, ast, parseDependency ) => {
  *
  * @return {Object} Intermediate Representation in JSON.
  */
-module.exports = function( token, ast = { body: [] }, parseDependency = () => {} ) {
+module.exports = function( path, token, ast = { body: [] }, parseDependency = () => {} ) {
 	const exportEntries = getExportEntries( token );
 	const ir = [];
 	exportEntries.forEach( ( entry ) => {
@@ -140,6 +129,7 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 		if ( entry.localName === NAMESPACE_EXPORT ) {
 			doc.forEach( ( namedExport ) => {
 				ir.push( {
+					path,
 					name: namedExport.name,
 					description: namedExport.description,
 					tags: namedExport.tags,
@@ -149,6 +139,7 @@ module.exports = function( token, ast = { body: [] }, parseDependency = () => {}
 			} );
 		} else {
 			ir.push( {
+				path,
 				name: entry.exportName,
 				description: get( doc, [ 'description' ], UNDOCUMENTED ),
 				tags: get( doc, [ 'tags' ], [] ),

From a935f66024366dd80832dca0c01150ffc316a0de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 17:15:02 +0100
Subject: [PATCH 164/213] Adapt tests to API changes

---
 .../test-get-intermediate-representation.js   | 113 ++++++++++--------
 1 file changed, 64 insertions(+), 49 deletions(-)

diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 70ef2de96e7730..376035a305ba4c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -19,7 +19,8 @@ test( 'IR - undocumented', function( t ) {
 		path.join( __dirname, './fixtures/default-undocumented-nocomments.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Undocumented declaration.',
 		tags: [],
@@ -30,7 +31,8 @@ test( 'IR - undocumented', function( t ) {
 		path.join( __dirname, './fixtures/default-undocumented-oneliner.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenOneliner ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenOneliner ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Undocumented declaration.',
 		tags: [],
@@ -45,7 +47,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassAnonymous ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClassAnonymous ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
@@ -56,7 +59,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-class-named.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClassNamed ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClassNamed ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
@@ -67,7 +71,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnAnonymous ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFnAnonymous ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Function declaration example.',
 		tags: [],
@@ -78,7 +83,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-function-named.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFnNamed ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFnNamed ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Function declaration example.',
 		tags: [],
@@ -89,7 +95,8 @@ test( 'IR - JSDoc in export statement (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-variable.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Variable declaration example.',
 		tags: [],
@@ -104,7 +111,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-class.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenClass ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClass ) ), [ {
+		path: null,
 		name: 'MyDeclaration',
 		description: 'My declaration example.',
 		tags: [],
@@ -115,7 +123,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-function.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenFn ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFn ) ), [ {
+		path: null,
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
@@ -126,7 +135,8 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-variable.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariable ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ), [ {
+		path: null,
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
@@ -137,9 +147,9 @@ test( 'IR - JSDoc in export statement (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-variables.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenVariables ) ), [
-		{ name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
-		{ name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariables ) ), [
+		{ path: null, name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
+		{ path: null, name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
 	] );
 	t.end();
 } );
@@ -153,7 +163,8 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 		path.join( __dirname, './fixtures/default-identifier-ast.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ), [ {
+		path: null,
 		name: 'default',
 		description: 'Class declaration example.',
 		tags: [],
@@ -169,12 +180,12 @@ test( 'IR - JSDoc in same file (default export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 } ]
+		getIntermediateRepresentation( null, JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
+		[ { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 } ]
 	);
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 } ]
+		getIntermediateRepresentation( null, JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
+		[ { path: null, name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 } ]
 	);
 	t.end();
 } );
@@ -188,7 +199,8 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-identifier-ast.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( token ), JSON.parse( ast ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ), [ {
+		path: null,
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
@@ -203,7 +215,8 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-identifier-destructuring-ast.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
+		path: null,
 		name: 'myDeclaration',
 		description: 'My declaration example.',
 		tags: [],
@@ -218,10 +231,10 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-identifiers-ast.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( tokens ), JSON.parse( asts ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokens ), JSON.parse( asts ) ), [
+		{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+		{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+		{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
 	] );
 	const foo = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
@@ -231,12 +244,12 @@ test( 'IR - JSDoc in same file (named export)', function( t ) {
 		path.join( __dirname, './fixtures/named-identifiers-and-inline-ast.json' ),
 		'utf-8'
 	);
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
-		{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
-		{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
+		{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
+		{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
 	] );
-	t.deepEqual( getIntermediateRepresentation( JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
-		{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
+	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
+		{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
 	] );
 	t.end();
 } );
@@ -251,11 +264,11 @@ test( 'IR - JSDoc in module dependency (named export)', function( t ) {
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
+		getIntermediateRepresentation( null, JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
 		[
-			{ name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 },
-			{ name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 },
-			{ name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 },
+			{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 },
+			{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 },
 		]
 	);
 	t.end();
@@ -271,16 +284,16 @@ test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
+		getIntermediateRepresentation( null, JSON.parse( tokenDefault ), { body: [] }, getModule ),
+		[ { path: null, name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
 	);
 	const tokenDefaultExported = fs.readFileSync(
 		path.join( __dirname, './fixtures/named-default-exported.json' ),
 		'utf-8'
 	);
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
+		getIntermediateRepresentation( null, JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
+		[ { path: null, name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
 	);
 
 	t.end();
@@ -296,11 +309,11 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( token ), { body: [] }, getModule ),
+		getIntermediateRepresentation( null, JSON.parse( token ), { body: [] }, getModule ),
 		[
-			{ name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 },
-			{ name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 },
-			{ name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 },
+			{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 },
+			{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 },
+			{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 },
 		]
 	);
 	const tokenCommented = fs.readFileSync(
@@ -308,11 +321,11 @@ test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
 		'utf-8'
 	);
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenCommented ), { body: [] }, getModule ),
+		getIntermediateRepresentation( null, JSON.parse( tokenCommented ), { body: [] }, getModule ),
 		[
-			{ name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 },
-			{ name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 },
-			{ name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 },
+			{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 },
 		]
 	);
 	t.end();
@@ -332,8 +345,9 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
+		getIntermediateRepresentation( null, JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
 		[ {
+			path: null,
 			name: 'default',
 			description: 'Function declaration.',
 			tags: [],
@@ -354,8 +368,9 @@ test( 'IR - JSDoc in module dependency through import (default export)', functio
 		'utf-8'
 	) );
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
+		getIntermediateRepresentation( null, JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
 		[ {
+			path: null,
 			name: 'default',
 			description: 'Function declaration.',
 			tags: [],
@@ -388,8 +403,8 @@ test( 'IR - JSDoc in module dependency through import (named export)', function(
 		) );
 	};
 	t.deepEqual(
-		getIntermediateRepresentation( JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 } ]
+		getIntermediateRepresentation( null, JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
+		[ { path: null, name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 } ]
 	);
 	t.end();
 } );

From 6070c62d95ea0b5cffd7653e6ba802f0c11217a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 17:41:55 +0100
Subject: [PATCH 165/213] Add path and line numbers to markdown output

---
 packages/docgen/src/formatter.js | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index d514ba0b7b43d6..f6b6b147d9d4b0 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+
 /**
  * Internal dependencies
  */
@@ -70,7 +75,10 @@ module.exports = function( symbols ) {
 	} );
 	if ( symbols && symbols.length > 0 ) {
 		symbols.forEach( ( symbol ) => {
+			const symbolPath = path.basename( symbol.path );
+			const symbolPathWithLines = `${ symbolPath }#L${ symbol.lineStart }-L${ symbol.lineEnd }`;
 			docs.push( `## ${ symbol.name }` );
+			docs.push( `\n\n[${ symbolPathWithLines }](${ symbolPathWithLines })` );
 			formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs );
 			formatDescription( symbol.description, docs );
 			formatTag(

From 8016fb71174a31ecc9fec14d06e0e8e7f4b8c1f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 17:59:47 +0100
Subject: [PATCH 166/213] Add TODO file

---
 packages/docgen/TODO.md     | 9 +++++++++
 packages/docgen/coverage.md | 8 ++++----
 2 files changed, 13 insertions(+), 4 deletions(-)
 create mode 100644 packages/docgen/TODO.md

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
new file mode 100644
index 00000000000000..521de54f3d90b2
--- /dev/null
+++ b/packages/docgen/TODO.md
@@ -0,0 +1,9 @@
+# TODO
+
+- [x] Pass file info (line, name) to the formatter.
+- [ ] CLI: allow for passing a formatter.
+- [ ] CLI: allow for filtering specific names that should go undocumented.
+- [ ] Find alternative to `doctrine`.
+- [ ] Chore: update examples in README.
+- [ ] Chore: register the package with lerna.
+- [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/coverage.md b/packages/docgen/coverage.md
index ff795e6a61628a..83c5dfd3d59fa6 100644
--- a/packages/docgen/coverage.md
+++ b/packages/docgen/coverage.md
@@ -1,6 +1,6 @@
 # Coverage
 
-Packages outside of scope:
+## Packages outside of scope
 
 - babel-plugin-makepot. CommonJS module. Babel plugin.
 - babel-preset-default. CommonJS module. Babel preset.
@@ -16,9 +16,9 @@ Packages outside of scope:
 - postcss-themes. CommonJS module.
 - scripts. CommonJS module.
 
-TODO:
+## TODO
 
-These either happen in private API, aren't relevant, or pend of decission.
+These either happen in private API, aren't relevant, or are pending of decission.
 
 - [ ] go undocummented: `unstable__*`, rich-text `unstableToDom`, `experimental__`
 - [ ] `constants` keycodes, rich-text `LINE_SEPARATOR`
@@ -38,7 +38,7 @@ These either happen in private API, aren't relevant, or pend of decission.
 - [ ] `@throws` packages/blocks/src/api/node.js
 - [ ] `@typedef` packages/blocks/src/api/registration.js
 
-DONE:
+## DONE
 
 - [x] a11y
 - [x] annotations

From e842a63f75e4117b37b9e662cdbe9fccb4a251af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 18:45:14 +0100
Subject: [PATCH 167/213] Use optionator to process CLI options

---
 packages/docgen/TODO.md      |  2 ++
 packages/docgen/package.json |  3 +++
 packages/docgen/src/cli.js   | 27 ++++++++++++++++++---------
 3 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 521de54f3d90b2..3fbcb95717ff17 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,8 +1,10 @@
 # TODO
 
 - [x] Pass file info (line, name) to the formatter.
+- [ ] CLI: allow for passing the output file.
 - [ ] CLI: allow for passing a formatter.
 - [ ] CLI: allow for filtering specific names that should go undocumented.
+- [ ] IR: make it independent from doctrine output & offer a better alternative to type description?
 - [ ] Find alternative to `doctrine`.
 - [ ] Chore: update examples in README.
 - [ ] Chore: register the package with lerna.
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index c13a62fe92a6c2..9cd6b72f14eedb 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -19,6 +19,9 @@
 	"bin": {
 		"docgen": "./src/cli.js"
 	},
+	"dependencies": {
+		"optionator": "0.8.2"
+	},
 	"devDependencies": {
 		"faucet": "0.0.1",
 		"tape": "4.9.2"
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index f7ec24e35941ea..af363f7a9a1c4c 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -1,16 +1,12 @@
 /**
- * Node dependencies.
+ * External dependencies
  */
 const fs = require( 'fs' );
 const path = require( 'path' );
-
-/**
- * External dependencies.
- */
 const { last } = require( 'lodash' );
 
 /**
- * Internal dependencies.
+ * Internal dependencies
  */
 const engine = require( './engine' );
 const formatter = require( './formatter' );
@@ -68,17 +64,30 @@ const processFile = ( rootDir, inputFile ) => {
  * Start up processing.
  */
 
+const optionator = require( 'optionator' )( {
+	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
+	options: [ {
+		option: 'debug',
+		type: 'Boolean',
+		default: false,
+		description: 'run in debug mode, which outputs intermediate files',
+	} ],
+} );
+
+const options = optionator.parseArgv( process.argv );
+
 // Prepare input
 const processDir = process.cwd();
-let initialInputFile = process.argv[ 2 ];
+let initialInputFile = options._[ 0 ];
 if ( initialInputFile === undefined ) {
-	process.stdout.write( '\nUsage: <path-to-docgen> <relative-path-to-entry-point.js>' );
+	process.stdout.write( '\n' );
+	process.stdout.write( optionator.generateHelp() );
 	process.stdout.write( '\n\n' );
 	process.exit( 1 );
 }
 initialInputFile = path.join( processDir, initialInputFile );
 
-const debugMode = process.argv[ 3 ] === '--debug' ? true : false;
+const debugMode = options.debug ? true : false;
 
 // Process
 const currentFileStack = []; // To keep track of file being processed.

From c0ba93bb0caa828f33d550939e70a09536d61ab2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 19:05:26 +0100
Subject: [PATCH 168/213] Allow to specify a markdown output file

---
 packages/docgen/src/cli.js       | 39 +++++++++++++++++++-------------
 packages/docgen/src/formatter.js | 10 ++++++--
 2 files changed, 31 insertions(+), 18 deletions(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index af363f7a9a1c4c..09d376c6d5d7c0 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -67,6 +67,11 @@ const processFile = ( rootDir, inputFile ) => {
 const optionator = require( 'optionator' )( {
 	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
 	options: [ {
+		option: 'output',
+		alias: 'o',
+		type: 'String',
+		description: 'Markdown file to contain API docs',
+	}, {
 		option: 'debug',
 		type: 'Boolean',
 		default: false,
@@ -76,41 +81,43 @@ const optionator = require( 'optionator' )( {
 
 const options = optionator.parseArgv( process.argv );
 
-// Prepare input
+// Input: process CLI args, prepare files, etc
 const processDir = process.cwd();
-let initialInputFile = options._[ 0 ];
-if ( initialInputFile === undefined ) {
+let sourceFile = options._[ 0 ];
+if ( sourceFile === undefined ) {
 	process.stdout.write( '\n' );
 	process.stdout.write( optionator.generateHelp() );
 	process.stdout.write( '\n\n' );
 	process.exit( 1 );
 }
-initialInputFile = path.join( processDir, initialInputFile );
+sourceFile = path.join( processDir, sourceFile );
 
 const debugMode = options.debug ? true : false;
 
-// Process
-const currentFileStack = []; // To keep track of file being processed.
-const result = processFile( processDir, initialInputFile );
-
-// Ouput
 const inputBase = path.join(
-	path.dirname( initialInputFile ),
-	path.basename( initialInputFile, path.extname( initialInputFile ) )
+	path.dirname( sourceFile ),
+	path.basename( sourceFile, path.extname( sourceFile ) )
 );
-const doc = inputBase + '-api.md';
-const ir = inputBase + '-ir.json';
-const tokens = inputBase + '-exports.json';
 const ast = inputBase + '-ast.json';
+const tokens = inputBase + '-exports.json';
+const ir = inputBase + '-ir.json';
+const doc = options.output ?
+	path.join( processDir, options.output ) :
+	inputBase + '-api.md';
+
+// Process
+const currentFileStack = []; // To keep track of file being processed.
+const result = processFile( processDir, sourceFile );
 
+// Ouput
 if ( result === undefined ) {
 	process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' );
-	process.stdout.write( `\n${ initialInputFile }` );
+	process.stdout.write( `\n${ sourceFile }` );
 	process.stdout.write( '\n\n' );
 	process.exit( 0 );
 }
 
-fs.writeFileSync( doc, formatter( result.ir ) );
+fs.writeFileSync( doc, formatter( processDir, doc, result.ir ) );
 if ( debugMode ) {
 	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
 	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index f6b6b147d9d4b0..a657f3290b4a61 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -58,7 +58,7 @@ const formatDescription = ( description, docs ) => {
 	docs.push( description );
 };
 
-module.exports = function( symbols ) {
+module.exports = function( rootDir, docPath, symbols ) {
 	const docs = [ '# API' ];
 	docs.push( '\n' );
 	docs.push( '\n' );
@@ -75,7 +75,13 @@ module.exports = function( symbols ) {
 	} );
 	if ( symbols && symbols.length > 0 ) {
 		symbols.forEach( ( symbol ) => {
-			const symbolPath = path.basename( symbol.path );
+			const symbolPath = path.join(
+				path.relative(
+					path.dirname( docPath ),
+					path.join( rootDir, path.dirname( symbol.path ) )
+				),
+				path.basename( symbol.path ),
+			);
 			const symbolPathWithLines = `${ symbolPath }#L${ symbol.lineStart }-L${ symbol.lineEnd }`;
 			docs.push( `## ${ symbol.name }` );
 			docs.push( `\n\n[${ symbolPathWithLines }](${ symbolPathWithLines })` );

From 915091cf6ddce5587f14fab76aca014be5aaa294 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 19:35:58 +0100
Subject: [PATCH 169/213] Allow to pass a formatter

---
 packages/docgen/TODO.md    |  4 ++--
 packages/docgen/src/cli.js | 28 +++++++++++++++++++++++++---
 2 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 3fbcb95717ff17..312764f3a63ea6 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,8 +1,8 @@
 # TODO
 
 - [x] Pass file info (line, name) to the formatter.
-- [ ] CLI: allow for passing the output file.
-- [ ] CLI: allow for passing a formatter.
+- [x] CLI: allow for passing the output file.
+- [x] CLI: allow for passing a formatter.
 - [ ] CLI: allow for filtering specific names that should go undocumented.
 - [ ] IR: make it independent from doctrine output & offer a better alternative to type description?
 - [ ] Find alternative to `doctrine`.
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 09d376c6d5d7c0..061b77db1eea25 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -60,6 +60,18 @@ const processFile = ( rootDir, inputFile ) => {
 	}
 };
 
+const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols ) => {
+	try {
+		const customFormatter = require( customFormatterFile );
+		return customFormatter( rootDir, doc, symbols );
+	} catch ( e ) {
+		process.stdout.write( `\n${ e }` );
+		process.stdout.write( '\n\n' );
+		process.exit( 1 );
+	}
+	return 'custom formatter';
+};
+
 /**
  * Start up processing.
  */
@@ -67,15 +79,20 @@ const processFile = ( rootDir, inputFile ) => {
 const optionator = require( 'optionator' )( {
 	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
 	options: [ {
+		option: 'formatter',
+		alias: 'f',
+		type: 'String',
+		description: 'A custom function to format the generated documentation.',
+	}, {
 		option: 'output',
 		alias: 'o',
 		type: 'String',
-		description: 'Markdown file to contain API docs',
+		description: 'Output file to will contain the API documentation.',
 	}, {
 		option: 'debug',
 		type: 'Boolean',
 		default: false,
-		description: 'run in debug mode, which outputs intermediate files',
+		description: 'Run in debug mode, which outputs some intermediate files useful for debugging.',
 	} ],
 } );
 
@@ -117,7 +134,12 @@ if ( result === undefined ) {
 	process.exit( 0 );
 }
 
-fs.writeFileSync( doc, formatter( processDir, doc, result.ir ) );
+const outputContents = options.formatter ?
+	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, result, ir ) :
+	formatter( processDir, doc, result.ir );
+
+fs.writeFileSync( doc, outputContents );
+
 if ( debugMode ) {
 	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
 	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );

From f7577df6fe98203888e2f78f1663fce938ffbb5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 11 Feb 2019 19:36:14 +0100
Subject: [PATCH 170/213] Document new added options

---
 packages/docgen/README.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 021b91ea840943..934642b78f696b 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -13,6 +13,15 @@ Some characteristics:
 
 This command will generate a file named `entry-point-api.md` containing all the exports and its JSDoc comments.
 
+### CLI options
+
+* **--formatter** or **-f** `(String)`: An optional custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
+  * *rootDir* `(String)`: current working directory as seen by docgen.
+  * *docPath* `(String)`: path of the output document to generate.
+  * *symbols* `(Array)`: the symbols found.
+* **--output** or **-o** `(String)`: Output file that will contain the API documentation.
+* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
+
 ## Examples
 
 ### Default export

From 9ab9cfbea6fd637c5b48750b8a4fb9e2e079a58a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 12 Feb 2019 14:32:25 +0100
Subject: [PATCH 171/213] CLI: add ability to ignore symbols by name

---
 packages/docgen/README.md  |  5 +++--
 packages/docgen/TODO.md    |  2 +-
 packages/docgen/src/cli.js | 11 +++++++----
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 934642b78f696b..45944e1efcf603 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -15,11 +15,12 @@ This command will generate a file named `entry-point-api.md` containing all the
 
 ### CLI options
 
-* **--formatter** or **-f** `(String)`: An optional custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
+* **--formatter** `(String)`: An optional custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
   * *rootDir* `(String)`: current working directory as seen by docgen.
   * *docPath* `(String)`: path of the output document to generate.
   * *symbols* `(Array)`: the symbols found.
-* **--output** or **-o** `(String)`: Output file that will contain the API documentation.
+* **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it.
+* **--output** `(String)`: Output file that will contain the API documentation.
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
 
 ## Examples
diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 312764f3a63ea6..b246b204cc7a2e 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -3,7 +3,7 @@
 - [x] Pass file info (line, name) to the formatter.
 - [x] CLI: allow for passing the output file.
 - [x] CLI: allow for passing a formatter.
-- [ ] CLI: allow for filtering specific names that should go undocumented.
+- [x] CLI: allow for filtering specific names that should go undocumented.
 - [ ] IR: make it independent from doctrine output & offer a better alternative to type description?
 - [ ] Find alternative to `doctrine`.
 - [ ] Chore: update examples in README.
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 061b77db1eea25..e8d16089aef45e 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -80,14 +80,16 @@ const optionator = require( 'optionator' )( {
 	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
 	options: [ {
 		option: 'formatter',
-		alias: 'f',
 		type: 'String',
 		description: 'A custom function to format the generated documentation.',
 	}, {
 		option: 'output',
-		alias: 'o',
 		type: 'String',
 		description: 'Output file to will contain the API documentation.',
+	}, {
+		option: 'ignore',
+		type: 'RegExp',
+		description: 'A regular expression used to ignore symbols whose name match it.',
 	}, {
 		option: 'debug',
 		type: 'Boolean',
@@ -125,6 +127,7 @@ const doc = options.output ?
 // Process
 const currentFileStack = []; // To keep track of file being processed.
 const result = processFile( processDir, sourceFile );
+const filteredIr = result.ir.filter( ( { name } ) => options.ignore ? ! name.match( options.ignore ) : true );
 
 // Ouput
 if ( result === undefined ) {
@@ -135,8 +138,8 @@ if ( result === undefined ) {
 }
 
 const outputContents = options.formatter ?
-	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, result, ir ) :
-	formatter( processDir, doc, result.ir );
+	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr ) :
+	formatter( processDir, doc, filteredIr );
 
 fs.writeFileSync( doc, outputContents );
 

From 63c6702b6be7f2c7c7f093d9371e10a4211eb45a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 12 Feb 2019 18:23:21 +0100
Subject: [PATCH 172/213] Update README

---
 packages/docgen/README.md | 145 ++++++++++++++++++++++++++++++++++----
 packages/docgen/TODO.md   |   8 ++-
 2 files changed, 136 insertions(+), 17 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 45944e1efcf603..4b345e3ba12f45 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -32,6 +32,10 @@ Entry point:
 ```js
 /**
  * Adds two numbers.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
  */
 export default function addition( term1, term2 ) {
 	// Implementation would go here.
@@ -41,12 +45,22 @@ export default function addition( term1, term2 ) {
 Output:
 
 ```markdown
-
 # API
 
 ## default
 
+[example.js#L8-L10](example.js#L8-L10)
+
 Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
 ```
 
 ### Named export
@@ -56,61 +70,164 @@ Entry point:
 ```js
 /**
  * Adds two numbers.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
  */
 function addition( term1, term2 ) {
-	// Implementation would go here.
+	return term1 + term2;
 }
 
-export { count };
+/**
+ * Adds two numbers.
+ *
+ * @deprecated Use `addition` instead.
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
+ */
+function count( term1, term2 ) {
+	return term1 + term2;
+}
+
+export { count, addition };
 ```
 
 Output:
 
 ```markdown
-
 # API
 
+## addition
+
+[example.js#L25-L25](example.js#L25-L25)
+
+Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+
 ## count
 
+[example.js#L25-L25](example.js#L25-L25)
+
+> **Deprecated** Use `addition` instead.
+
 Adds two numbers.
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
 ```
 
 ### Namespace export
 
-Let `count/index.js` be:
+Let the entry point be:
+
+```js
+export * from './count';
+```
+
+with `./count/index.js` contents being:
 
 ```js
 /**
  * Substracts two numbers.
+ *
+ * @example
+ *
+ * ```js
+ * const result = substraction( 5, 2 );
+ * console.log( result ); // Will log 3
+ * ```
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of subtracting the two numbers.
  */
 export function substraction( term1, term2 ) {
-	// Implementation would go here.
+	return term1 - term2;
 }
 
 /**
  * Adds two numbers.
+ *
+  * @example
+ *
+ * ```js
+ * const result = addition( 5, 2 );
+ * console.log( result ); // Will log 7
+ * ```
+ *
+ * @param {number} term1 First number.
+ * @param {number} term2 Second number.
+ * @return {number} The result of adding the two numbers.
  */
 export function addition( term1, term2 ) {
 	// Implementation would go here.
+	return term1 - term2;
 }
 ```
 
-And the entry point:
-
-```js
-export * from './count';
-```
-
 Output would be:
 
-```markdown
+````markdown
 # API
 
 ## addition
 
+[example-module.js#L1-L1](example-module.js#L1-L1)
+
 Adds two numbers.
 
+**Usage**
+
+```js
+const result = addition( 5, 2 );
+console.log( result ); // Will log 7
+```
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of adding the two numbers.
+
 ## substraction
 
+[example-module.js#L1-L1](example-module.js#L1-L1)
+
 Substracts two numbers.
-```
\ No newline at end of file
+
+**Usage**
+
+```js
+const result = substraction( 5, 2 );
+console.log( result ); // Will log 3
+```
+
+**Parameters**
+
+- **term1** `number`: First number.
+- **term2** `number`: Second number.
+
+**Returns**
+
+`number` The result of subtracting the two numbers.
+````
\ No newline at end of file
diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index b246b204cc7a2e..a7d3d6bfc5e80a 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -4,8 +4,10 @@
 - [x] CLI: allow for passing the output file.
 - [x] CLI: allow for passing a formatter.
 - [x] CLI: allow for filtering specific names that should go undocumented.
-- [ ] IR: make it independent from doctrine output & offer a better alternative to type description?
-- [ ] Find alternative to `doctrine`.
-- [ ] Chore: update examples in README.
+- [ ] Find alternative to `doctrine` & make IR independent from doctrine output
+- [ ] IR: offer a better alternative to type description?
+- [ ] IR: support `../` dependencies.
+- [ ] Review `/** Internal dependencies`. Context: https://wordpress.slack.com/archives/C5UNMSU4R/p1549980709040800
+- [x] Chore: update examples in README.
 - [ ] Chore: register the package with lerna.
 - [ ] See [coverage](coverage.md#TODO)

From d90aaf525277a9adac308f50951b50e576ac5c5e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 13:30:08 +0100
Subject: [PATCH 173/213] CLI: support append to existing Markdown file

---
 packages/docgen/README.md        |  3 ++-
 packages/docgen/package.json     |  6 ++++-
 packages/docgen/src/cli.js       | 44 +++++++++++++++++++++++++++-----
 packages/docgen/src/formatter.js |  7 +++--
 4 files changed, 50 insertions(+), 10 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 4b345e3ba12f45..be161307c5615b 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -15,13 +15,14 @@ This command will generate a file named `entry-point-api.md` containing all the
 
 ### CLI options
 
-* **--formatter** `(String)`: An optional custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
+* **--formatter** `(String)`: A path to a custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input:
   * *rootDir* `(String)`: current working directory as seen by docgen.
   * *docPath* `(String)`: path of the output document to generate.
   * *symbols* `(Array)`: the symbols found.
 * **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it.
 * **--output** `(String)`: Output file that will contain the API documentation.
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
+* **--append** `(String)`: Title of the Markdown section to append the generated documentation to. It takes precedence over and bypasses the *--formatter* option.
 
 ## Examples
 
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 9cd6b72f14eedb..11c5f2c016b924 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -24,7 +24,11 @@
 	},
 	"devDependencies": {
 		"faucet": "0.0.1",
-		"tape": "4.9.2"
+		"mdast-util-inject": "1.1.0",
+		"remark": "9.0.0",
+		"remark-parse": "6.0.3",
+		"tape": "4.9.2",
+		"unified": "7.1.0"
 	},
 	"publishConfig": {
 		"access": "public"
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index e8d16089aef45e..4c02cf2708a268 100644
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -4,6 +4,10 @@
 const fs = require( 'fs' );
 const path = require( 'path' );
 const { last } = require( 'lodash' );
+const remark = require( 'remark' );
+const unified = require( 'unified' );
+const remarkParser = require( 'remark-parse' );
+const inject = require( 'mdast-util-inject' );
 
 /**
  * Internal dependencies
@@ -60,10 +64,10 @@ const processFile = ( rootDir, inputFile ) => {
 	}
 };
 
-const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols ) => {
+const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, headingTitle ) => {
 	try {
 		const customFormatter = require( customFormatterFile );
-		return customFormatter( rootDir, doc, symbols );
+		return customFormatter( rootDir, doc, symbols, headingTitle );
 	} catch ( e ) {
 		process.stdout.write( `\n${ e }` );
 		process.stdout.write( '\n\n' );
@@ -90,6 +94,10 @@ const optionator = require( 'optionator' )( {
 		option: 'ignore',
 		type: 'RegExp',
 		description: 'A regular expression used to ignore symbols whose name match it.',
+	}, {
+		option: 'append',
+		type: 'String',
+		description: 'Markdown section title to append documentation to.',
 	}, {
 		option: 'debug',
 		type: 'Boolean',
@@ -137,11 +145,35 @@ if ( result === undefined ) {
 	process.exit( 0 );
 }
 
-const outputContents = options.formatter ?
-	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr ) :
-	formatter( processDir, doc, filteredIr );
+// wrap the inject utility as an remark plugin
+const appendContents = ( { heading, newContents } ) => {
+	return function transform( targetAst, file, next ) {
+		if ( ! inject( heading, targetAst, newContents ) ) {
+			return next( new Error( `Heading ${ heading } not found.` ) );
+		}
+		next();
+	};
+};
 
-fs.writeFileSync( doc, outputContents );
+if ( options.append ) {
+	const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
+	const contentsAST = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
+	remark()
+		.use( { settings: { commonmark: true } } )
+		.use( appendContents, { heading: options.append, newContents: contentsAST } )
+		.process( currentReadmeFile, function( err, file ) {
+			if ( err ) {
+				throw err;
+			}
+			fs.writeFileSync( doc, file );
+		} );
+} else {
+	const outputContents = options.formatter ?
+		runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' ) :
+		formatter( processDir, doc, filteredIr, 'API' );
+
+	fs.writeFileSync( doc, outputContents );
+}
 
 if ( debugMode ) {
 	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index a657f3290b4a61..aa1940f2d46aa8 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -58,8 +58,11 @@ const formatDescription = ( description, docs ) => {
 	docs.push( description );
 };
 
-module.exports = function( rootDir, docPath, symbols ) {
-	const docs = [ '# API' ];
+module.exports = function( rootDir, docPath, symbols, headingTitle ) {
+	const docs = [ ];
+	if ( headingTitle ) {
+		docs.push( `# ${ headingTitle }` );
+	}
 	docs.push( '\n' );
 	docs.push( '\n' );
 	symbols.sort( ( first, second ) => {

From 4abfe528951b95d29e90f87e9f62e912e95c9efc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 16:54:17 +0100
Subject: [PATCH 174/213] Make linter happy

---
 packages/docgen/tests/fixtures/default-import-default.js | 3 +++
 packages/docgen/tests/fixtures/default-import-named.js   | 3 +++
 packages/docgen/tests/fixtures/named-import-namespace.js | 3 +++
 3 files changed, 9 insertions(+)

diff --git a/packages/docgen/tests/fixtures/default-import-default.js b/packages/docgen/tests/fixtures/default-import-default.js
index d5bec9984b17b0..073e3dde436f43 100644
--- a/packages/docgen/tests/fixtures/default-import-default.js
+++ b/packages/docgen/tests/fixtures/default-import-default.js
@@ -1,3 +1,6 @@
+/**
+ * Internal dependencies
+ */
 import fnDeclaration from './default-import-default-module';
 
 export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import-named.js b/packages/docgen/tests/fixtures/default-import-named.js
index 0f9b6032b32e9c..b7f4609237c6c0 100644
--- a/packages/docgen/tests/fixtures/default-import-named.js
+++ b/packages/docgen/tests/fixtures/default-import-named.js
@@ -1,3 +1,6 @@
+/**
+ * Internal dependencies
+ */
 import { functionDeclaration as fnDeclaration } from './default-import-named-module';
 
 export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.js b/packages/docgen/tests/fixtures/named-import-namespace.js
index 987e272ae1964b..a6b9234374d421 100644
--- a/packages/docgen/tests/fixtures/named-import-namespace.js
+++ b/packages/docgen/tests/fixtures/named-import-namespace.js
@@ -1,3 +1,6 @@
+/**
+ * Internal dependencies
+ */
 import * as variables from './named-import-namespace-module';
 
 export { variables };

From 3dfb4cc3beb0ce50921af1051c5dfbf316e0a4d3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 17:19:51 +0100
Subject: [PATCH 175/213] Add package to manifest

---
 docs/manifest.json | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/manifest.json b/docs/manifest.json
index c6eccbce1d73d3..fbaa1039cf678d 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -635,6 +635,12 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/deprecated/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/docgen",
+		"slug": "packages-docgen",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/packages/docgen/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/dom-ready",
 		"slug": "packages-dom-ready",

From 1b6578bb021aee08ce3ecd869e4b88299c06c287 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 17:43:28 +0100
Subject: [PATCH 176/213] Update as per new package recommendations

---
 packages/docgen/CHANGELOG.md |  4 ++--
 packages/docgen/README.md    | 12 +++++++++++-
 packages/docgen/package.json |  4 ++--
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/packages/docgen/CHANGELOG.md b/packages/docgen/CHANGELOG.md
index c90df3c7488eca..ae69187866b19e 100644
--- a/packages/docgen/CHANGELOG.md
+++ b/packages/docgen/CHANGELOG.md
@@ -1,3 +1,3 @@
-## 1.0.0 (next)
+## 1.0.0 (Unreleased)
 
-TBD
+- Initial release
diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index be161307c5615b..59e79336dca478 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -7,6 +7,14 @@ Some characteristics:
 * If the export statement doesn't contain any JSDoc, it'll look up for JSDoc up to the declaration.
 * It can resolve relative dependencies, either files or directories. For example, `import default from './dependency'` will find `dependency.js` or `dependency/index.js`
 
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/docgen --save-dev
+```
+
 ## Usage
 
 `node src/cli.js <entry-point.js>`
@@ -231,4 +239,6 @@ console.log( result ); // Will log 3
 **Returns**
 
 `number` The result of subtracting the two numbers.
-````
\ No newline at end of file
+````
+
+<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 11c5f2c016b924..06cfbb4d048937 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -1,6 +1,6 @@
 {
 	"name": "docgen",
-	"version": "1.0.0",
+	"version": "1.0.0-beta.0",
 	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -8,7 +8,7 @@
 		"jsdoc",
 		"documentation"
 	],
-	"homepage": "https://github.com/WordPress/gutenberg",
+	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/docgen/README.md",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/WordPress/gutenberg.git"

From 09e47754aea1d204533bdd599b6bd2e096f21462 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 17:51:03 +0100
Subject: [PATCH 177/213] Update package name

---
 packages/docgen/package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 06cfbb4d048937..0daa45e309c33b 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -1,5 +1,5 @@
 {
-	"name": "docgen",
+	"name": "@wordpress/docgen",
 	"version": "1.0.0-beta.0",
 	"description": "Autogenerate public API documentation from exports and JSDoc comments.",
 	"author": "The WordPress Contributors",

From fe3c531231b46e11512aacfe0178e8ce76312d97 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 13 Feb 2019 18:08:53 +0100
Subject: [PATCH 178/213] Add docgen as a dev dependency

---
 package-lock.json          | 7 +++++++
 package.json               | 1 +
 packages/docgen/src/cli.js | 0
 3 files changed, 8 insertions(+)
 mode change 100644 => 100755 packages/docgen/src/cli.js

diff --git a/package-lock.json b/package-lock.json
index 1b825c2ffbb3a4..f5054836d4ae28 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2701,6 +2701,13 @@
 				"@wordpress/hooks": "file:packages/hooks"
 			}
 		},
+		"@wordpress/docgen": {
+			"version": "file:packages/docgen",
+			"dev": true,
+			"requires": {
+				"optionator": "0.8.2"
+			}
+		},
 		"@wordpress/dom": {
 			"version": "file:packages/dom",
 			"requires": {
diff --git a/package.json b/package.json
index eb1b308d87f2a1..3185071be7171c 100644
--- a/package.json
+++ b/package.json
@@ -66,6 +66,7 @@
 		"@wordpress/babel-preset-default": "file:packages/babel-preset-default",
 		"@wordpress/browserslist-config": "file:packages/browserslist-config",
 		"@wordpress/custom-templated-path-webpack-plugin": "file:packages/custom-templated-path-webpack-plugin",
+		"@wordpress/docgen": "file:packages/docgen",
 		"@wordpress/e2e-test-utils": "file:packages/e2e-test-utils",
 		"@wordpress/e2e-tests": "file:packages/e2e-tests",
 		"@wordpress/eslint-plugin": "file:packages/eslint-plugin",
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
old mode 100644
new mode 100755

From 03e779ccbec911236299b2d8178e3551ec8a7ac4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 15 Feb 2019 12:25:25 +0100
Subject: [PATCH 179/213] Add wordpress keyword to package.json

---
 packages/docgen/package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 0daa45e309c33b..5704c0d0139228 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -6,7 +6,8 @@
 	"license": "GPL-2.0-or-later",
 	"keywords": [
 		"jsdoc",
-		"documentation"
+		"documentation",
+		"wordpress"
 	],
 	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/docgen/README.md",
 	"repository": {

From 3dc741076814fe9cc8b603b12590e589f224669b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 15 Feb 2019 12:30:38 +0100
Subject: [PATCH 180/213] Mark as a bash command

---
 packages/docgen/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 59e79336dca478..45c858085e6c77 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -17,7 +17,9 @@ npm install @wordpress/docgen --save-dev
 
 ## Usage
 
-`node src/cli.js <entry-point.js>`
+```bash
+node src/cli.js <entry-point.js>
+```
 
 This command will generate a file named `entry-point-api.md` containing all the exports and its JSDoc comments.
 

From bf08a545cff196cb6321f7ba887b59a12aa04ef2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 21 Feb 2019 17:45:14 +0100
Subject: [PATCH 181/213] CLI: allow for walking parent directories

---
 packages/docgen/src/cli.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 4c02cf2708a268..2659e086a25f61 100755
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -41,7 +41,7 @@ const relativeToAbsolute = ( basePath, relativePath ) => {
 };
 
 const getIRFromRelativePath = ( rootDir, basePath ) => ( relativePath ) => {
-	if ( ! relativePath.startsWith( './' ) ) {
+	if ( ! relativePath.startsWith( '.' ) ) {
 		return [];
 	}
 	const absolutePath = relativeToAbsolute( basePath, relativePath );

From 26411bbff2aede5341a46ba37c1ecfe17c5db803 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 11:20:32 +0100
Subject: [PATCH 182/213] Add tests for tags

---
 packages/docgen/TODO.md                       |  11 +-
 .../tests/fixtures/tags-function-exports.json | 269 ++++++++++++++++++
 .../docgen/tests/fixtures/tags-function.js    |  24 ++
 .../tests/fixtures/tags-variable-exports.json | 125 ++++++++
 .../docgen/tests/fixtures/tags-variable.js    |   7 +
 .../test-get-intermediate-representation.js   |  90 ++++++
 6 files changed, 518 insertions(+), 8 deletions(-)
 create mode 100644 packages/docgen/tests/fixtures/tags-function-exports.json
 create mode 100644 packages/docgen/tests/fixtures/tags-function.js
 create mode 100644 packages/docgen/tests/fixtures/tags-variable-exports.json
 create mode 100644 packages/docgen/tests/fixtures/tags-variable.js

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index a7d3d6bfc5e80a..d9b83b190031cf 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,13 +1,8 @@
 # TODO
 
-- [x] Pass file info (line, name) to the formatter.
-- [x] CLI: allow for passing the output file.
-- [x] CLI: allow for passing a formatter.
-- [x] CLI: allow for filtering specific names that should go undocumented.
-- [ ] Find alternative to `doctrine` & make IR independent from doctrine output
+- [ ] IR: find alternative to `doctrine` and/or make it independent from its output.
 - [ ] IR: offer a better alternative to type description?
-- [ ] IR: support `../` dependencies.
-- [ ] Review `/** Internal dependencies`. Context: https://wordpress.slack.com/archives/C5UNMSU4R/p1549980709040800
-- [x] Chore: update examples in README.
+- [ ] Markdown: implement token-based insertion.
 - [ ] Chore: register the package with lerna.
+- [ ] Chore: make a command available in the Gutenberg repo.
 - [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/tests/fixtures/tags-function-exports.json b/packages/docgen/tests/fixtures/tags-function-exports.json
new file mode 100644
index 00000000000000..3d0677a818c4b6
--- /dev/null
+++ b/packages/docgen/tests/fixtures/tags-function-exports.json
@@ -0,0 +1,269 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 521,
+	"end": 609,
+	"loc": {
+		"start": {
+			"line": 22,
+			"column": 0
+		},
+		"end": {
+			"line": 24,
+			"column": 2
+		}
+	},
+	"range": [
+		521,
+		609
+	],
+	"declaration": {
+		"type": "VariableDeclaration",
+		"start": 528,
+		"end": 609,
+		"loc": {
+			"start": {
+				"line": 22,
+				"column": 7
+			},
+			"end": {
+				"line": 24,
+				"column": 2
+			}
+		},
+		"range": [
+			528,
+			609
+		],
+		"declarations": [
+			{
+				"type": "VariableDeclarator",
+				"start": 534,
+				"end": 608,
+				"loc": {
+					"start": {
+						"line": 22,
+						"column": 13
+					},
+					"end": {
+						"line": 24,
+						"column": 1
+					}
+				},
+				"range": [
+					534,
+					608
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 534,
+					"end": 537,
+					"loc": {
+						"start": {
+							"line": 22,
+							"column": 13
+						},
+						"end": {
+							"line": 22,
+							"column": 16
+						}
+					},
+					"range": [
+						534,
+						537
+					],
+					"name": "sum"
+				},
+				"init": {
+					"type": "ArrowFunctionExpression",
+					"start": 540,
+					"end": 608,
+					"loc": {
+						"start": {
+							"line": 22,
+							"column": 19
+						},
+						"end": {
+							"line": 24,
+							"column": 1
+						}
+					},
+					"range": [
+						540,
+						608
+					],
+					"id": null,
+					"generator": false,
+					"expression": false,
+					"async": false,
+					"params": [
+						{
+							"type": "Identifier",
+							"start": 542,
+							"end": 552,
+							"loc": {
+								"start": {
+									"line": 22,
+									"column": 21
+								},
+								"end": {
+									"line": 22,
+									"column": 31
+								}
+							},
+							"range": [
+								542,
+								552
+							],
+							"name": "firstParam"
+						},
+						{
+							"type": "Identifier",
+							"start": 554,
+							"end": 565,
+							"loc": {
+								"start": {
+									"line": 22,
+									"column": 33
+								},
+								"end": {
+									"line": 22,
+									"column": 44
+								}
+							},
+							"range": [
+								554,
+								565
+							],
+							"name": "secondParam"
+						}
+					],
+					"body": {
+						"type": "BlockStatement",
+						"start": 571,
+						"end": 608,
+						"loc": {
+							"start": {
+								"line": 22,
+								"column": 50
+							},
+							"end": {
+								"line": 24,
+								"column": 1
+							}
+						},
+						"range": [
+							571,
+							608
+						],
+						"body": [
+							{
+								"type": "ReturnStatement",
+								"start": 574,
+								"end": 606,
+								"loc": {
+									"start": {
+										"line": 23,
+										"column": 1
+									},
+									"end": {
+										"line": 23,
+										"column": 33
+									}
+								},
+								"range": [
+									574,
+									606
+								],
+								"argument": {
+									"type": "BinaryExpression",
+									"start": 581,
+									"end": 605,
+									"loc": {
+										"start": {
+											"line": 23,
+											"column": 8
+										},
+										"end": {
+											"line": 23,
+											"column": 32
+										}
+									},
+									"range": [
+										581,
+										605
+									],
+									"left": {
+										"type": "Identifier",
+										"start": 581,
+										"end": 591,
+										"loc": {
+											"start": {
+												"line": 23,
+												"column": 8
+											},
+											"end": {
+												"line": 23,
+												"column": 18
+											}
+										},
+										"range": [
+											581,
+											591
+										],
+										"name": "firstParam"
+									},
+									"operator": "+",
+									"right": {
+										"type": "Identifier",
+										"start": 594,
+										"end": 605,
+										"loc": {
+											"start": {
+												"line": 23,
+												"column": 21
+											},
+											"end": {
+												"line": 23,
+												"column": 32
+											}
+										},
+										"range": [
+											594,
+											605
+										],
+										"name": "secondParam"
+									}
+								}
+							}
+						]
+					}
+				}
+			}
+		],
+		"kind": "const"
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ",
+			"start": 0,
+			"end": 520,
+			"range": [
+				0,
+				520
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 21,
+					"column": 3
+				}
+			}
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/tags-function.js b/packages/docgen/tests/fixtures/tags-function.js
new file mode 100644
index 00000000000000..8d4261e0f63289
--- /dev/null
+++ b/packages/docgen/tests/fixtures/tags-function.js
@@ -0,0 +1,24 @@
+/**
+ * A function that adds two parameters.
+ *
+ * @deprecated Use native addition instead.
+ * @since v2
+ *
+ * @see addition
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators
+ *
+ * @param {number} firstParam The first param to add.
+ * @param {number} secondParam The second param to add.
+ *
+ *  @example
+ *
+ * ```js
+ * const addResult = sum( 1, 3 );
+ * console.log( addResult ); // will yield 4
+ * ```
+ *
+ * @return {number} The result of adding the two params.
+ */
+export const sum = ( firstParam, secondParam ) => {
+	return firstParam + secondParam;
+};
diff --git a/packages/docgen/tests/fixtures/tags-variable-exports.json b/packages/docgen/tests/fixtures/tags-variable-exports.json
new file mode 100644
index 00000000000000..80482610d28e54
--- /dev/null
+++ b/packages/docgen/tests/fixtures/tags-variable-exports.json
@@ -0,0 +1,125 @@
+{
+	"type": "ExportNamedDeclaration",
+	"start": 111,
+	"end": 141,
+	"loc": {
+		"start": {
+			"line": 7,
+			"column": 0
+		},
+		"end": {
+			"line": 7,
+			"column": 30
+		}
+	},
+	"range": [
+		111,
+		141
+	],
+	"declaration": {
+		"type": "VariableDeclaration",
+		"start": 118,
+		"end": 141,
+		"loc": {
+			"start": {
+				"line": 7,
+				"column": 7
+			},
+			"end": {
+				"line": 7,
+				"column": 30
+			}
+		},
+		"range": [
+			118,
+			141
+		],
+		"declarations": [
+			{
+				"type": "VariableDeclarator",
+				"start": 124,
+				"end": 140,
+				"loc": {
+					"start": {
+						"line": 7,
+						"column": 13
+					},
+					"end": {
+						"line": 7,
+						"column": 29
+					}
+				},
+				"range": [
+					124,
+					140
+				],
+				"id": {
+					"type": "Identifier",
+					"start": 124,
+					"end": 135,
+					"loc": {
+						"start": {
+							"line": 7,
+							"column": 13
+						},
+						"end": {
+							"line": 7,
+							"column": 24
+						}
+					},
+					"range": [
+						124,
+						135
+					],
+					"name": "THE_MEANING"
+				},
+				"init": {
+					"type": "Literal",
+					"start": 138,
+					"end": 140,
+					"loc": {
+						"start": {
+							"line": 7,
+							"column": 27
+						},
+						"end": {
+							"line": 7,
+							"column": 29
+						}
+					},
+					"range": [
+						138,
+						140
+					],
+					"value": 42,
+					"raw": "42"
+				}
+			}
+		],
+		"kind": "const"
+	},
+	"specifiers": [],
+	"source": null,
+	"leadingComments": [
+		{
+			"type": "Block",
+			"value": "*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ",
+			"start": 0,
+			"end": 110,
+			"range": [
+				0,
+				110
+			],
+			"loc": {
+				"start": {
+					"line": 1,
+					"column": 0
+				},
+				"end": {
+					"line": 6,
+					"column": 3
+				}
+			}
+		}
+	]
+}
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/tags-variable.js b/packages/docgen/tests/fixtures/tags-variable.js
new file mode 100644
index 00000000000000..d2d32717a67bcb
--- /dev/null
+++ b/packages/docgen/tests/fixtures/tags-variable.js
@@ -0,0 +1,7 @@
+/**
+ * Constant to document the meaning of life,
+ * the universe and everything else.
+ *
+ * @type {number}
+ */
+export const THE_MEANING = 42;
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 376035a305ba4c..9a58b0c88464e8 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -408,3 +408,93 @@ test( 'IR - JSDoc in module dependency through import (named export)', function(
 	);
 	t.end();
 } );
+
+test( 'IR - tags are extracted properly', function( t ) {
+	const tokensFn = fs.readFileSync(
+		path.join( __dirname, './fixtures/tags-function-exports.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( null, JSON.parse( tokensFn ) ),
+		[ {
+			path: null,
+			name: 'sum',
+			description: 'A function that adds two parameters.',
+			tags: [
+				{
+					title: 'deprecated',
+					description: 'Use native addition instead.',
+				},
+				{
+					title: 'since',
+					description: 'v2',
+				},
+				{
+					title: 'see',
+					description: 'addition',
+				},
+				{
+					title: 'link',
+					description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators',
+				},
+				{
+					title: 'param',
+					description: 'The first param to add.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+					name: 'firstParam',
+				},
+				{
+					title: 'param',
+					description: 'The second param to add.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+					name: 'secondParam',
+				},
+				{
+					title: 'example',
+					description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
+				},
+				{
+					title: 'return',
+					description: 'The result of adding the two params.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+				},
+			],
+			lineStart: 22,
+			lineEnd: 24,
+		} ]
+	);
+	const tokensVar = fs.readFileSync(
+		path.join( __dirname, './fixtures/tags-variable-exports.json' ),
+		'utf-8'
+	);
+	t.deepEqual(
+		getIntermediateRepresentation( null, JSON.parse( tokensVar ) ),
+		[ {
+			path: null,
+			name: 'THE_MEANING',
+			description: 'Constant to document the meaning of life,\nthe universe and everything else.',
+			tags: [
+				{
+					title: 'type',
+					description: null,
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+				},
+			],
+			lineStart: 7,
+			lineEnd: 7,
+		} ]
+	);
+	t.end();
+} );

From d4c1f807a74301feaa74b0d85e1ea2b61b24dfb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 11:28:52 +0100
Subject: [PATCH 183/213] Adapt formatter test to API

---
 packages/docgen/tests/test-formatter-markdown.js | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index e8933a7b6f9491..3443efa51e7a68 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -9,10 +9,11 @@ const test = require( 'tape' );
 const formatter = require( '../src/formatter' );
 
 test( 'Formatter - returns markdown', ( t ) => {
-	const docs = formatter( [ { description: 'My declaration example.', tags: [], name: 'myDeclaration' } ] );
+	const docPath = process.cwd();
+	const docs = formatter( docPath, docPath + '-api.md', [ { path: docPath + '-code.js', description: 'My declaration example.', tags: [], name: 'myDeclaration', lineStart: 1, lineEnd: 2 } ], 'API docs' );
 	t.equal(
 		docs,
-		'# API\n\n## myDeclaration\n\nMy declaration example.\n'
+		'# API docs\n\n## myDeclaration\n\n[docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2](docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2)\n\nMy declaration example.\n'
 	);
 	t.end();
 } );

From 8a0695ced32b1345176e94ac9e16db3f19eb18f9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 12:33:35 +0100
Subject: [PATCH 184/213] Move IR tests related to JSDoc to its own tester

---
 packages/docgen/package.json                  |  1 +
 .../test-get-intermediate-representation.js   | 90 ------------------
 .../docgen/tests/test-get-jsdoc-from-token.js | 92 +++++++++++++++++++
 3 files changed, 93 insertions(+), 90 deletions(-)
 create mode 100644 packages/docgen/tests/test-get-jsdoc-from-token.js

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 5704c0d0139228..f4072531adf29d 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -39,6 +39,7 @@
 		"test:engine": "tape tests/test-engine.js | faucet",
 		"test:formatter": "tape tests/test-formatter-markdown.js | faucet",
 		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
+		"test:get-jsdoc-from-token": "tape tests/test-get-jsdoc-from-token.js | faucet",
 		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet",
 		"test:get-type-as-string": "tape tests/test-get-type-as-string.js | faucet"
 	}
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
index 9a58b0c88464e8..376035a305ba4c 100644
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ b/packages/docgen/tests/test-get-intermediate-representation.js
@@ -408,93 +408,3 @@ test( 'IR - JSDoc in module dependency through import (named export)', function(
 	);
 	t.end();
 } );
-
-test( 'IR - tags are extracted properly', function( t ) {
-	const tokensFn = fs.readFileSync(
-		path.join( __dirname, './fixtures/tags-function-exports.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokensFn ) ),
-		[ {
-			path: null,
-			name: 'sum',
-			description: 'A function that adds two parameters.',
-			tags: [
-				{
-					title: 'deprecated',
-					description: 'Use native addition instead.',
-				},
-				{
-					title: 'since',
-					description: 'v2',
-				},
-				{
-					title: 'see',
-					description: 'addition',
-				},
-				{
-					title: 'link',
-					description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators',
-				},
-				{
-					title: 'param',
-					description: 'The first param to add.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
-					name: 'firstParam',
-				},
-				{
-					title: 'param',
-					description: 'The second param to add.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
-					name: 'secondParam',
-				},
-				{
-					title: 'example',
-					description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
-				},
-				{
-					title: 'return',
-					description: 'The result of adding the two params.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
-				},
-			],
-			lineStart: 22,
-			lineEnd: 24,
-		} ]
-	);
-	const tokensVar = fs.readFileSync(
-		path.join( __dirname, './fixtures/tags-variable-exports.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokensVar ) ),
-		[ {
-			path: null,
-			name: 'THE_MEANING',
-			description: 'Constant to document the meaning of life,\nthe universe and everything else.',
-			tags: [
-				{
-					title: 'type',
-					description: null,
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
-				},
-			],
-			lineStart: 7,
-			lineEnd: 7,
-		} ]
-	);
-	t.end();
-} );
diff --git a/packages/docgen/tests/test-get-jsdoc-from-token.js b/packages/docgen/tests/test-get-jsdoc-from-token.js
new file mode 100644
index 00000000000000..a1ba6827074a19
--- /dev/null
+++ b/packages/docgen/tests/test-get-jsdoc-from-token.js
@@ -0,0 +1,92 @@
+/**
+ * External dependencies.
+ */
+const test = require( 'tape' );
+
+/**
+ * Internal dependencies.
+ */
+const getJSDocFromToken = require( '../src/get-jsdoc-from-token' );
+
+test( 'JSDoc - extracts description and tags', function( t ) {
+	t.deepEqual(
+		getJSDocFromToken( {
+			leadingComments: [ {
+				value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ',
+			} ],
+		} ),
+		{
+			description: 'A function that adds two parameters.',
+			tags: [
+				{
+					title: 'deprecated',
+					description: 'Use native addition instead.',
+				},
+				{
+					title: 'since',
+					description: 'v2',
+				},
+				{
+					title: 'see',
+					description: 'addition',
+				},
+				{
+					title: 'link',
+					description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators',
+				},
+				{
+					title: 'param',
+					description: 'The first param to add.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+					name: 'firstParam',
+				},
+				{
+					title: 'param',
+					description: 'The second param to add.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+					name: 'secondParam',
+				},
+				{
+					title: 'example',
+					description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
+				},
+				{
+					title: 'return',
+					description: 'The result of adding the two params.',
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+				},
+			],
+		}
+	);
+
+	t.deepEqual(
+		getJSDocFromToken( {
+			leadingComments: [ {
+				value: '*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ',
+			} ],
+		} ),
+		{
+			description: 'Constant to document the meaning of life,\nthe universe and everything else.',
+			tags: [
+				{
+					title: 'type',
+					description: null,
+					type: {
+						type: 'NameExpression',
+						name: 'number',
+					},
+				},
+			],
+		}
+	);
+	t.end();
+} );

From d994a27fbe0b391bcf10e3ccdd4b97ad828cad96 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 13:02:00 +0100
Subject: [PATCH 185/213] get-jsdoc-from-token returns a human-readable type

---
 packages/docgen/TODO.md                       |  2 --
 packages/docgen/src/formatter.js              | 11 +++------
 packages/docgen/src/get-jsdoc-from-token.js   | 15 ++++++++++++
 .../docgen/tests/test-formatter-markdown.js   | 23 +++++++++++++++++--
 .../docgen/tests/test-get-jsdoc-from-token.js | 20 ++++------------
 .../docgen/tests/test-get-type-as-string.js   | 12 +++++-----
 6 files changed, 49 insertions(+), 34 deletions(-)

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index d9b83b190031cf..e4078feca9c415 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,7 +1,5 @@
 # TODO
 
-- [ ] IR: find alternative to `doctrine` and/or make it independent from its output.
-- [ ] IR: offer a better alternative to type description?
 - [ ] Markdown: implement token-based insertion.
 - [ ] Chore: register the package with lerna.
 - [ ] Chore: make a command available in the Gutenberg repo.
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index aa1940f2d46aa8..eea74fb987a73e 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -3,11 +3,6 @@
  */
 const path = require( 'path' );
 
-/**
- * Internal dependencies
- */
-const getType = require( './get-type-as-string' );
-
 const getTagsByName = ( tags, ...names ) => tags.filter( ( tag ) => names.some( ( name ) => name === tag.title ) );
 
 const cleanSpaces = ( paragraph ) =>
@@ -100,19 +95,19 @@ module.exports = function( rootDir, docPath, symbols, headingTitle ) {
 			formatTag(
 				'Type',
 				getTagsByName( symbol.tags, 'type' ),
-				( tag ) => `\n\`${ getType( tag ) }\` ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			formatTag(
 				'Parameters',
 				getTagsByName( symbol.tags, 'param' ),
-				( tag ) => `\n- **${ tag.name }** \`${ getType( tag ) }\`: ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n- **${ tag.name }** \`${ tag.type }\`: ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			formatTag(
 				'Returns',
 				getTagsByName( symbol.tags, 'return' ),
-				( tag ) => `\n\`${ getType( tag ) }\` ${ cleanSpaces( tag.description ) }`,
+				( tag ) => `\n\`${ tag.type }\` ${ cleanSpaces( tag.description ) }`,
 				docs
 			);
 			docs.push( '\n' );
diff --git a/packages/docgen/src/get-jsdoc-from-token.js b/packages/docgen/src/get-jsdoc-from-token.js
index af70d64af63a54..e888abc53d06ca 100644
--- a/packages/docgen/src/get-jsdoc-from-token.js
+++ b/packages/docgen/src/get-jsdoc-from-token.js
@@ -7,7 +7,16 @@ const doctrine = require( 'doctrine' );
  * Internal dependencies.
  */
 const getLeadingComments = require( './get-leading-comments' );
+const getTypeAsString = require( './get-type-as-string' );
 
+/**
+ * Function that takes an Espree token and returns
+ * a object representing the leading JSDoc comment of the token,
+ * if any.
+ *
+ * @param {Object} token Espree token.
+ * @return {Object} Object representing the JSDoc comment.
+ */
 module.exports = function( token ) {
 	let jsdoc;
 	const comments = getLeadingComments( token );
@@ -17,6 +26,12 @@ module.exports = function( token ) {
 			recoverable: true,
 			sloppy: true,
 		} );
+		jsdoc.tags = jsdoc.tags.map( ( tag ) => {
+			if ( tag.type ) {
+				tag.type = getTypeAsString( tag.type );
+			}
+			return tag;
+		} );
 	}
 	return jsdoc;
 };
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index 3443efa51e7a68..50b25b10bfc324 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -10,10 +10,29 @@ const formatter = require( '../src/formatter' );
 
 test( 'Formatter - returns markdown', ( t ) => {
 	const docPath = process.cwd();
-	const docs = formatter( docPath, docPath + '-api.md', [ { path: docPath + '-code.js', description: 'My declaration example.', tags: [], name: 'myDeclaration', lineStart: 1, lineEnd: 2 } ], 'API docs' );
+	const docs = formatter( docPath, docPath + '-api.md', [ {
+		path: docPath + '-code.js',
+		description: 'My declaration example.',
+		tags: [
+			{
+				title: 'param',
+				description: 'First declaration parameter.',
+				type: 'number',
+				name: 'firstParam',
+			},
+			{
+				title: 'return',
+				description: 'The result of the declaration.',
+				type: 'number',
+			},
+		],
+		name: 'myDeclaration',
+		lineStart: 1,
+		lineEnd: 2,
+	} ], 'API docs' );
 	t.equal(
 		docs,
-		'# API docs\n\n## myDeclaration\n\n[docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2](docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2)\n\nMy declaration example.\n'
+		'# API docs\n\n## myDeclaration\n\n[docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2](docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2)\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'
 	);
 	t.end();
 } );
diff --git a/packages/docgen/tests/test-get-jsdoc-from-token.js b/packages/docgen/tests/test-get-jsdoc-from-token.js
index a1ba6827074a19..e296ba1a6b7914 100644
--- a/packages/docgen/tests/test-get-jsdoc-from-token.js
+++ b/packages/docgen/tests/test-get-jsdoc-from-token.js
@@ -37,19 +37,13 @@ test( 'JSDoc - extracts description and tags', function( t ) {
 				{
 					title: 'param',
 					description: 'The first param to add.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
+					type: 'number',
 					name: 'firstParam',
 				},
 				{
 					title: 'param',
 					description: 'The second param to add.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
+					type: 'number',
 					name: 'secondParam',
 				},
 				{
@@ -59,10 +53,7 @@ test( 'JSDoc - extracts description and tags', function( t ) {
 				{
 					title: 'return',
 					description: 'The result of adding the two params.',
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
+					type: 'number',
 				},
 			],
 		}
@@ -80,10 +71,7 @@ test( 'JSDoc - extracts description and tags', function( t ) {
 				{
 					title: 'type',
 					description: null,
-					type: {
-						type: 'NameExpression',
-						name: 'number',
-					},
+					type: 'number',
 				},
 			],
 		}
diff --git a/packages/docgen/tests/test-get-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
index 049f15ffc89100..2b7e071ba621d5 100644
--- a/packages/docgen/tests/test-get-type-as-string.js
+++ b/packages/docgen/tests/test-get-type-as-string.js
@@ -8,7 +8,7 @@ const test = require( 'tape' );
  */
 const getType = require( '../src/get-type-as-string' );
 
-test( 'getType from NameExpression', ( t ) => {
+test( 'JSDoc - getType from NameExpression', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -22,7 +22,7 @@ test( 'getType from NameExpression', ( t ) => {
 	t.end();
 } );
 
-test( 'getType from AllLiteral', ( t ) => {
+test( 'JSDoc - getType from AllLiteral', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -35,7 +35,7 @@ test( 'getType from AllLiteral', ( t ) => {
 	t.end();
 } );
 
-test( 'getType with applications', ( t ) => {
+test( 'JSDoc - getType with applications', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -61,7 +61,7 @@ test( 'getType with applications', ( t ) => {
 	t.end();
 } );
 
-test( 'getType from NullableType', ( t ) => {
+test( 'JSDoc - getType from NullableType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -79,7 +79,7 @@ test( 'getType from NullableType', ( t ) => {
 	t.end();
 } );
 
-test( 'getType from RestType', ( t ) => {
+test( 'JSDoc - getType from RestType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',
@@ -96,7 +96,7 @@ test( 'getType from RestType', ( t ) => {
 	t.end();
 } );
 
-test( 'getType from RestType with UnionType', ( t ) => {
+test( 'JSDoc - getType from RestType with UnionType', ( t ) => {
 	const type = getType( {
 		title: 'param',
 		description: 'description',

From 284944002d7f869ccb1facee221ec8b669867690 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 18:23:54 +0100
Subject: [PATCH 186/213] Implement a token-based injection for Markdown

---
 packages/docgen/src/cli.js                    | 43 ++++++++++++++++---
 packages/docgen/src/embed.js                  | 15 +++++++
 .../docgen/tests/fixtures/markdown-code.js    | 24 +++++++++++
 .../docgen/tests/fixtures/markdown-input.md   | 13 ++++++
 .../docgen/tests/fixtures/markdown-output.md  | 41 ++++++++++++++++++
 5 files changed, 129 insertions(+), 7 deletions(-)
 create mode 100644 packages/docgen/src/embed.js
 create mode 100644 packages/docgen/tests/fixtures/markdown-code.js
 create mode 100644 packages/docgen/tests/fixtures/markdown-input.md
 create mode 100644 packages/docgen/tests/fixtures/markdown-output.md

diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 2659e086a25f61..3ecbc89a1f8dd4 100755
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -14,6 +14,7 @@ const inject = require( 'mdast-util-inject' );
  */
 const engine = require( './engine' );
 const formatter = require( './formatter' );
+const embed = require( './embed' );
 
 /**
  * Helpers functions.
@@ -85,19 +86,25 @@ const optionator = require( 'optionator' )( {
 	options: [ {
 		option: 'formatter',
 		type: 'String',
-		description: 'A custom function to format the generated documentation.',
+		description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.',
 	}, {
 		option: 'output',
 		type: 'String',
-		description: 'Output file to will contain the API documentation.',
+		description: 'Output file to contain the API documentation.',
 	}, {
 		option: 'ignore',
 		type: 'RegExp',
 		description: 'A regular expression used to ignore symbols whose name match it.',
 	}, {
-		option: 'append',
+		option: 'to-section',
 		type: 'String',
-		description: 'Markdown section title to append documentation to.',
+		description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
+	}, {
+		option: 'to-token',
+		type: 'Boolean',
+		description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
 	}, {
 		option: 'debug',
 		type: 'Boolean',
@@ -145,7 +152,7 @@ if ( result === undefined ) {
 	process.exit( 0 );
 }
 
-// wrap the inject utility as an remark plugin
+// wrap the inject utility as a remark plugin
 const appendContents = ( { heading, newContents } ) => {
 	return function transform( targetAst, file, next ) {
 		if ( ! inject( heading, targetAst, newContents ) ) {
@@ -155,12 +162,34 @@ const appendContents = ( { heading, newContents } ) => {
 	};
 };
 
-if ( options.append ) {
+// wrap the embed utility as a remark plugin
+const embedContents = ( { newContents } ) => {
+	return function transform( targetAst, file, next ) {
+		if ( ! embed( targetAst, newContents ) ) {
+			return next( new Error( `Token not found.` ) );
+		}
+		next();
+	};
+};
+
+if ( options.toSection ) {
+	const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
+	const contentsAST = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
+	remark()
+		.use( { settings: { commonmark: true } } )
+		.use( appendContents, { heading: options.toSection, newContents: contentsAST } )
+		.process( currentReadmeFile, function( err, file ) {
+			if ( err ) {
+				throw err;
+			}
+			fs.writeFileSync( doc, file );
+		} );
+} else if ( options.toToken ) {
 	const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
 	const contentsAST = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
 	remark()
 		.use( { settings: { commonmark: true } } )
-		.use( appendContents, { heading: options.append, newContents: contentsAST } )
+		.use( embedContents, { newContents: contentsAST } )
 		.process( currentReadmeFile, function( err, file ) {
 			if ( err ) {
 				throw err;
diff --git a/packages/docgen/src/embed.js b/packages/docgen/src/embed.js
new file mode 100644
index 00000000000000..f05b9bb32e8310
--- /dev/null
+++ b/packages/docgen/src/embed.js
@@ -0,0 +1,15 @@
+const embed = function( targetAst, newContents ) {
+	const startIndex = targetAst.children.findIndex(
+		( node ) => node.type === 'html' && node.value === '<!-- Autogenerated API docs start -->'
+	);
+	const endIndex = targetAst.children.findIndex(
+		( node ) => node.type === 'html' && node.value === '<!-- Autogenerated API docs end -->'
+	);
+	if ( startIndex !== -1 && endIndex !== -1 && startIndex < endIndex ) {
+		targetAst.children.splice( startIndex + 1, endIndex - startIndex - 1, newContents );
+		return true;
+	}
+	return false;
+};
+
+module.exports = embed;
diff --git a/packages/docgen/tests/fixtures/markdown-code.js b/packages/docgen/tests/fixtures/markdown-code.js
new file mode 100644
index 00000000000000..8d4261e0f63289
--- /dev/null
+++ b/packages/docgen/tests/fixtures/markdown-code.js
@@ -0,0 +1,24 @@
+/**
+ * A function that adds two parameters.
+ *
+ * @deprecated Use native addition instead.
+ * @since v2
+ *
+ * @see addition
+ * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators
+ *
+ * @param {number} firstParam The first param to add.
+ * @param {number} secondParam The second param to add.
+ *
+ *  @example
+ *
+ * ```js
+ * const addResult = sum( 1, 3 );
+ * console.log( addResult ); // will yield 4
+ * ```
+ *
+ * @return {number} The result of adding the two params.
+ */
+export const sum = ( firstParam, secondParam ) => {
+	return firstParam + secondParam;
+};
diff --git a/packages/docgen/tests/fixtures/markdown-input.md b/packages/docgen/tests/fixtures/markdown-input.md
new file mode 100644
index 00000000000000..f1247f9f4c16d0
--- /dev/null
+++ b/packages/docgen/tests/fixtures/markdown-input.md
@@ -0,0 +1,13 @@
+# Package docs
+
+This is some package docs.
+
+## API Docs
+
+<!-- Autogenerated API docs start -->
+
+Content to be replaced.
+
+<!-- Autogenerated API docs end -->
+
+After token content.
diff --git a/packages/docgen/tests/fixtures/markdown-output.md b/packages/docgen/tests/fixtures/markdown-output.md
new file mode 100644
index 00000000000000..c1415f4790129c
--- /dev/null
+++ b/packages/docgen/tests/fixtures/markdown-output.md
@@ -0,0 +1,41 @@
+# Package docs
+
+This is some package docs.
+
+## API Docs
+
+<!-- Autogenerated API docs start -->
+
+## sum
+
+[markdown-code.js#L22-L24](markdown-code.js#L22-L24)
+
+> **Deprecated** Use native addition instead.
+
+A function that adds two parameters.
+
+**Related**
+
+-   addition
+-   <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators>
+
+**Usage**
+
+```js
+const addResult = sum( 1, 3 );
+console.log( addResult ); // will yield 4
+```
+
+**Parameters**
+
+-   **firstParam** `number`: The first param to add.
+-   **secondParam** `number`: The second param to add.
+
+**Returns**
+
+`number` The result of adding the two params.
+
+
+<!-- Autogenerated API docs end -->
+
+After token content.

From 3d5b911d923ad111eca25e7c333264e17063df64 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 18:27:47 +0100
Subject: [PATCH 187/213] Add embed JSDoc

---
 packages/docgen/src/embed.js | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/packages/docgen/src/embed.js b/packages/docgen/src/embed.js
index f05b9bb32e8310..1b57191b6ef2d3 100644
--- a/packages/docgen/src/embed.js
+++ b/packages/docgen/src/embed.js
@@ -1,3 +1,10 @@
+/**
+ * Inserts new contents within the token boundaries.
+ *
+ * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded.
+ * @param {Object} newContents The new contents to be embedded in remark AST format.
+ * @return {boolean} Whether the contents were embedded or not.
+ */
 const embed = function( targetAst, newContents ) {
 	const startIndex = targetAst.children.findIndex(
 		( node ) => node.type === 'html' && node.value === '<!-- Autogenerated API docs start -->'

From 287a1fb45475cd73ee13947ec632ebe65b433c11 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 18:52:28 +0100
Subject: [PATCH 188/213] Formatter: let heading index be configurable

---
 packages/docgen/src/formatter.js | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/formatter.js
index eea74fb987a73e..d9e41536f2f9a0 100644
--- a/packages/docgen/src/formatter.js
+++ b/packages/docgen/src/formatter.js
@@ -53,10 +53,16 @@ const formatDescription = ( description, docs ) => {
 	docs.push( description );
 };
 
-module.exports = function( rootDir, docPath, symbols, headingTitle ) {
+const getHeading = ( index, text ) => {
+	return '#'.repeat( index ) + ' ' + text;
+};
+
+module.exports = function( rootDir, docPath, symbols, headingTitle, headingStartIndex ) {
 	const docs = [ ];
+	let headingIndex = headingStartIndex || 1;
 	if ( headingTitle ) {
-		docs.push( `# ${ headingTitle }` );
+		docs.push( getHeading( headingIndex, `${ headingTitle }` ) );
+		headingIndex++;
 	}
 	docs.push( '\n' );
 	docs.push( '\n' );
@@ -81,7 +87,7 @@ module.exports = function( rootDir, docPath, symbols, headingTitle ) {
 				path.basename( symbol.path ),
 			);
 			const symbolPathWithLines = `${ symbolPath }#L${ symbol.lineStart }-L${ symbol.lineEnd }`;
-			docs.push( `## ${ symbol.name }` );
+			docs.push( getHeading( headingIndex, `${ symbol.name }` ) );
 			docs.push( `\n\n[${ symbolPathWithLines }](${ symbolPathWithLines })` );
 			formatDeprecated( getTagsByName( symbol.tags, 'deprecated' ), docs );
 			formatDescription( symbol.description, docs );

From 5e224386cd6758de79339f228478c0700ac9ad4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 25 Feb 2019 19:15:37 +0100
Subject: [PATCH 189/213] Use proper heading when embedding content within
 token

---
 packages/docgen/TODO.md                       |  3 ++
 packages/docgen/src/embed.js                  | 36 ++++++++++++++++---
 .../{markdown-output.md => markdown-docs.md}  |  6 ++--
 .../docgen/tests/fixtures/markdown-input.md   | 13 -------
 4 files changed, 37 insertions(+), 21 deletions(-)
 rename packages/docgen/tests/fixtures/{markdown-output.md => markdown-docs.md} (86%)
 delete mode 100644 packages/docgen/tests/fixtures/markdown-input.md

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index e4078feca9c415..6fa8b1fa1ed696 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,6 +1,9 @@
 # TODO
 
 - [ ] Markdown: implement token-based insertion.
+  - [x] Use proper headings (--to-token)
+  - [ ] Use proper heading (--to-section)
+  - [ ] Review newlines
 - [ ] Chore: register the package with lerna.
 - [ ] Chore: make a command available in the Gutenberg repo.
 - [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/src/embed.js b/packages/docgen/src/embed.js
index 1b57191b6ef2d3..5b1c334b921833 100644
--- a/packages/docgen/src/embed.js
+++ b/packages/docgen/src/embed.js
@@ -1,19 +1,45 @@
+/**
+ * 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' );
+	return lastHeading ? lastHeading.depth : 1;
+};
+
 /**
  * Inserts new contents within the token boundaries.
  *
  * @param {Object} targetAst The remark AST of the file where the new contents are to be embedded.
- * @param {Object} newContents The new contents to be embedded in remark AST format.
+ * @param {Object} newContentAst The new contents to be embedded in remark AST format.
  * @return {boolean} Whether the contents were embedded or not.
  */
-const embed = function( targetAst, newContents ) {
+const embed = function( targetAst, newContentAst ) {
+	let headingIndex = -1;
+
 	const startIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === '<!-- Autogenerated API docs start -->'
+		( node ) => node.type === 'html' && node.value === '<!-- START TOKEN(Autogenerated API docs) -->'
 	);
+	if ( startIndex === -1 ) {
+		return false;
+	}
 	const endIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === '<!-- Autogenerated API docs end -->'
+		( node ) => node.type === 'html' && node.value === '<!-- END TOKEN(Autogenerated API docs) -->'
 	);
+	if ( endIndex === -1 ) {
+		return false;
+	}
+
 	if ( startIndex !== -1 && endIndex !== -1 && startIndex < endIndex ) {
-		targetAst.children.splice( startIndex + 1, endIndex - startIndex - 1, newContents );
+		headingIndex = getHeadingIndex( targetAst, startIndex );
+		newContentAst.children.forEach( ( node ) => {
+			if ( node.type === 'heading' ) {
+				node.depth = headingIndex + 1;
+			}
+		} );
+		targetAst.children.splice( startIndex + 1, endIndex - startIndex - 1, newContentAst );
 		return true;
 	}
 	return false;
diff --git a/packages/docgen/tests/fixtures/markdown-output.md b/packages/docgen/tests/fixtures/markdown-docs.md
similarity index 86%
rename from packages/docgen/tests/fixtures/markdown-output.md
rename to packages/docgen/tests/fixtures/markdown-docs.md
index c1415f4790129c..05e43204772e73 100644
--- a/packages/docgen/tests/fixtures/markdown-output.md
+++ b/packages/docgen/tests/fixtures/markdown-docs.md
@@ -4,9 +4,9 @@ This is some package docs.
 
 ## API Docs
 
-<!-- Autogenerated API docs start -->
+<!-- START TOKEN(Autogenerated API docs) -->
 
-## sum
+### sum
 
 [markdown-code.js#L22-L24](markdown-code.js#L22-L24)
 
@@ -36,6 +36,6 @@ console.log( addResult ); // will yield 4
 `number` The result of adding the two params.
 
 
-<!-- Autogenerated API docs end -->
+<!-- END TOKEN(Autogenerated API docs) -->
 
 After token content.
diff --git a/packages/docgen/tests/fixtures/markdown-input.md b/packages/docgen/tests/fixtures/markdown-input.md
deleted file mode 100644
index f1247f9f4c16d0..00000000000000
--- a/packages/docgen/tests/fixtures/markdown-input.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Package docs
-
-This is some package docs.
-
-## API Docs
-
-<!-- Autogenerated API docs start -->
-
-Content to be replaced.
-
-<!-- Autogenerated API docs end -->
-
-After token content.

From 25b0898504aaae06132ab7176ad451ee155b4caf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 26 Feb 2019 17:20:40 +0100
Subject: [PATCH 190/213] Move default markdown code to own folder

---
 packages/docgen/TODO.md                       |  4 --
 packages/docgen/src/cli.js                    | 62 ++-----------------
 packages/docgen/src/{ => markdown}/embed.js   |  0
 .../docgen/src/{ => markdown}/formatter.js    |  0
 packages/docgen/src/markdown/index.js         | 44 +++++++++++++
 .../docgen/tests/test-formatter-markdown.js   |  2 +-
 6 files changed, 51 insertions(+), 61 deletions(-)
 rename packages/docgen/src/{ => markdown}/embed.js (100%)
 rename packages/docgen/src/{ => markdown}/formatter.js (100%)
 create mode 100644 packages/docgen/src/markdown/index.js

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 6fa8b1fa1ed696..9c6bc144b2f702 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,9 +1,5 @@
 # TODO
 
-- [ ] Markdown: implement token-based insertion.
-  - [x] Use proper headings (--to-token)
-  - [ ] Use proper heading (--to-section)
-  - [ ] Review newlines
 - [ ] Chore: register the package with lerna.
 - [ ] Chore: make a command available in the Gutenberg repo.
 - [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
index 3ecbc89a1f8dd4..7a79e66159c82c 100755
--- a/packages/docgen/src/cli.js
+++ b/packages/docgen/src/cli.js
@@ -4,17 +4,12 @@
 const fs = require( 'fs' );
 const path = require( 'path' );
 const { last } = require( 'lodash' );
-const remark = require( 'remark' );
-const unified = require( 'unified' );
-const remarkParser = require( 'remark-parse' );
-const inject = require( 'mdast-util-inject' );
 
 /**
  * Internal dependencies
  */
 const engine = require( './engine' );
-const formatter = require( './formatter' );
-const embed = require( './embed' );
+const defaultMarkdownFormatter = require( './markdown' );
 
 /**
  * Helpers functions.
@@ -68,7 +63,8 @@ const processFile = ( rootDir, inputFile ) => {
 const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, headingTitle ) => {
 	try {
 		const customFormatter = require( customFormatterFile );
-		return customFormatter( rootDir, doc, symbols, headingTitle );
+		const output = customFormatter( rootDir, doc, symbols, headingTitle );
+		fs.writeFileSync( doc, output );
 	} catch ( e ) {
 		process.stdout.write( `\n${ e }` );
 		process.stdout.write( '\n\n' );
@@ -152,56 +148,10 @@ if ( result === undefined ) {
 	process.exit( 0 );
 }
 
-// wrap the inject utility as a remark plugin
-const appendContents = ( { heading, newContents } ) => {
-	return function transform( targetAst, file, next ) {
-		if ( ! inject( heading, targetAst, newContents ) ) {
-			return next( new Error( `Heading ${ heading } not found.` ) );
-		}
-		next();
-	};
-};
-
-// wrap the embed utility as a remark plugin
-const embedContents = ( { newContents } ) => {
-	return function transform( targetAst, file, next ) {
-		if ( ! embed( targetAst, newContents ) ) {
-			return next( new Error( `Token not found.` ) );
-		}
-		next();
-	};
-};
-
-if ( options.toSection ) {
-	const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
-	const contentsAST = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
-	remark()
-		.use( { settings: { commonmark: true } } )
-		.use( appendContents, { heading: options.toSection, newContents: contentsAST } )
-		.process( currentReadmeFile, function( err, file ) {
-			if ( err ) {
-				throw err;
-			}
-			fs.writeFileSync( doc, file );
-		} );
-} else if ( options.toToken ) {
-	const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
-	const contentsAST = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
-	remark()
-		.use( { settings: { commonmark: true } } )
-		.use( embedContents, { newContents: contentsAST } )
-		.process( currentReadmeFile, function( err, file ) {
-			if ( err ) {
-				throw err;
-			}
-			fs.writeFileSync( doc, file );
-		} );
+if ( options.formatter ) {
+	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' );
 } else {
-	const outputContents = options.formatter ?
-		runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' ) :
-		formatter( processDir, doc, filteredIr, 'API' );
-
-	fs.writeFileSync( doc, outputContents );
+	defaultMarkdownFormatter( options, processDir, doc, filteredIr, 'API' );
 }
 
 if ( debugMode ) {
diff --git a/packages/docgen/src/embed.js b/packages/docgen/src/markdown/embed.js
similarity index 100%
rename from packages/docgen/src/embed.js
rename to packages/docgen/src/markdown/embed.js
diff --git a/packages/docgen/src/formatter.js b/packages/docgen/src/markdown/formatter.js
similarity index 100%
rename from packages/docgen/src/formatter.js
rename to packages/docgen/src/markdown/formatter.js
diff --git a/packages/docgen/src/markdown/index.js b/packages/docgen/src/markdown/index.js
new file mode 100644
index 00000000000000..479e8816250653
--- /dev/null
+++ b/packages/docgen/src/markdown/index.js
@@ -0,0 +1,44 @@
+/**
+ * External dependencies.
+ */
+const remark = require( 'remark' );
+const unified = require( 'unified' );
+const remarkParser = require( 'remark-parse' );
+const inject = require( 'mdast-util-inject' );
+const fs = require( 'fs' );
+
+/**
+ * Internal dependencies.
+ */
+const formatter = require( './formatter' );
+const embed = require( './embed' );
+
+const appendOrEmbedContents = ( { options, newContents } ) => {
+	return function transform( targetAst, file, next ) {
+		if ( options.toSection && ! inject( options.toSection, targetAst, newContents ) ) {
+			return next( new Error( `Heading ${ options.toSection } not found.` ) );
+		} else if ( options.toToken && ! embed( targetAst, newContents ) ) {
+			return next( new Error( `Token not found.` ) );
+		}
+		next();
+	};
+};
+
+module.exports = function( options, processDir, doc, filteredIr, headingTitle ) {
+	if ( options.toSection || options.toToken ) {
+		const currentReadmeFile = fs.readFileSync( options.output, 'utf8' );
+		const newContents = unified().use( remarkParser ).parse( formatter( processDir, doc, filteredIr, null ) );
+		remark()
+			.use( { settings: { commonmark: true } } )
+			.use( appendOrEmbedContents, { options, newContents } )
+			.process( currentReadmeFile, function( err, file ) {
+				if ( err ) {
+					throw err;
+				}
+				fs.writeFileSync( doc, file );
+			} );
+	} else {
+		const output = formatter( processDir, doc, filteredIr, headingTitle );
+		fs.writeFileSync( doc, output );
+	}
+};
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
index 50b25b10bfc324..15e0c67b8fb6b6 100644
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ b/packages/docgen/tests/test-formatter-markdown.js
@@ -6,7 +6,7 @@ const test = require( 'tape' );
 /**
  * Internal dependencies.
  */
-const formatter = require( '../src/formatter' );
+const formatter = require( '../src/markdown/formatter' );
 
 test( 'Formatter - returns markdown', ( t ) => {
 	const docPath = process.cwd();

From 59d5f19419cd95be0e5c29edfa182504775f36a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 26 Feb 2019 18:22:36 +0100
Subject: [PATCH 191/213] Migrate engine tests to jest

---
 packages/docgen/src/test/engine.js   | 11 +++++++++++
 packages/docgen/tests/test-engine.js | 15 ---------------
 2 files changed, 11 insertions(+), 15 deletions(-)
 create mode 100644 packages/docgen/src/test/engine.js
 delete mode 100644 packages/docgen/tests/test-engine.js

diff --git a/packages/docgen/src/test/engine.js b/packages/docgen/src/test/engine.js
new file mode 100644
index 00000000000000..3a9efc921a2f01
--- /dev/null
+++ b/packages/docgen/src/test/engine.js
@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies.
+ */
+const engine = require( '../engine' );
+
+describe( 'Engine', () => {
+	it( 'should return a void IR for undefined code', () => {
+		const { ir } = engine( undefined );
+		expect( ir ).toHaveLength( 0 );
+	} );
+} );
diff --git a/packages/docgen/tests/test-engine.js b/packages/docgen/tests/test-engine.js
deleted file mode 100644
index 07a2608e39c9c5..00000000000000
--- a/packages/docgen/tests/test-engine.js
+++ /dev/null
@@ -1,15 +0,0 @@
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const engine = require( '../src/engine' );
-
-test( 'Engine - undefined code', ( t ) => {
-	const { ir } = engine( undefined );
-	t.deepEqual( ir, [ ] );
-	t.end();
-} );

From a58775ba63664a1be1ee1857e61b21c5f7dff02d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:02:32 +0100
Subject: [PATCH 192/213] Reorganize fixtures

---
 .../fixtures/default-class-anonymous/code.js} |  0
 .../default-class-anonymous/exports.json}     |  0
 .../fixtures/default-class-named/code.js}     |  0
 .../default-class-named/exports.json}         |  0
 .../default-function-anonymous/code.js}       |  0
 .../default-function-anonymous/exports.json}  |  0
 .../fixtures/default-function-named/ast.json} |  0
 .../fixtures/default-function-named/code.js}  |  0
 .../default-function-named/exports.json}      |  0
 .../fixtures/default-function-named/ir.json}  |  0
 .../fixtures/default-identifier/ast.json}     |  0
 .../test/fixtures/default-identifier/code.js} |  0
 .../fixtures/default-identifier/exports.json} |  0
 .../fixtures/default-import-default/ast.json} |  0
 .../fixtures/default-import-default/code.js}  |  2 +-
 .../default-import-default/exports.json}      |  0
 .../default-import-default/module-code.js}    |  0
 .../default-import-default/module-ir.json}    |  0
 .../fixtures/default-import-named/ast.json}   |  0
 .../fixtures/default-import-named/code.js     |  6 +++++
 .../default-import-named/exports.json}        |  0
 .../default-import-named/module-code.js}      |  0
 .../default-import-named/module-ir.json}      |  0
 .../fixtures/default-named-export/ast.json}   |  0
 .../fixtures/default-named-export/code.js}    |  0
 .../default-named-export/exports.json}        |  0
 .../default-undocumented-nocomments/code.js}  |  0
 .../exports.json}                             |  0
 .../default-undocumented-oneliner/code.js}    |  0
 .../exports.json}                             |  0
 .../test/fixtures/default-variable/code.js}   |  0
 .../fixtures/default-variable/exports.json}   |  0
 .../test/fixtures/markdown/code.js}           |  0
 .../test/fixtures/markdown/docs.md}           |  0
 .../test/fixtures/named-class/code.js}        |  0
 .../test/fixtures/named-class/exports.json}   |  0
 .../fixtures/named-default-exported/code.js}  |  0
 .../named-default-exported/exports.json}      |  0
 .../named-default-exported/module-code.js}    |  0
 .../named-default-exported/module-ir.json}    |  0
 .../src/test/fixtures/named-default/code.js   |  1 +
 .../test/fixtures/named-default/exports.json} |  0
 .../fixtures/named-default/module-code.js     |  4 ++++
 .../fixtures/named-default/module-ir.json     |  5 +++++
 .../test/fixtures/named-function/code.js}     |  0
 .../fixtures/named-function/exports.json}     |  0
 .../test/fixtures/named-function/ir.json}     |  0
 .../named-identifier-destructuring/ast.json}  |  0
 .../named-identifier-destructuring/code.js}   |  0
 .../exports.json}                             |  0
 .../test/fixtures/named-identifier/ast.json}  |  0
 .../test/fixtures/named-identifier/code.js}   |  0
 .../fixtures/named-identifier/exports.json}   |  0
 .../named-identifiers-and-inline/ast.json}    |  0
 .../named-identifiers-and-inline/code.js}     |  0
 .../exports.json}                             |  0
 .../test/fixtures/named-identifiers/ast.json} |  0
 .../test/fixtures/named-identifiers/code.js}  |  0
 .../fixtures/named-identifiers/exports.json}  |  0
 .../test/fixtures/named-identifiers/ir.json}  |  0
 .../test/fixtures/named-import-named/code.js} |  0
 .../fixtures/named-import-named/exports.json} |  0
 .../fixtures/named-import-namespace/ast.json} |  0
 .../fixtures/named-import-namespace/code.js}  |  0
 .../named-import-namespace/exports.json}      |  0
 .../named-import-namespace/module-code.js}    |  0
 .../module-exports.json}                      |  0
 .../named-import-namespace/module-ir.json}    |  0
 .../test/fixtures/named-variable/code.js}     |  0
 .../fixtures/named-variable/exports.json}     |  0
 .../test/fixtures/named-variables/code.js}    |  0
 .../fixtures/named-variables/exports.json}    |  0
 .../fixtures/namespace-commented/code.js}     |  0
 .../namespace-commented/exports.json}         |  0
 .../namespace-commented/module-ir.json}       |  0
 .../fixtures/namespace-commented/module.js}   |  0
 .../test/fixtures/namespace/code.js}          |  0
 .../test/fixtures/namespace/exports.json}     |  0
 .../test/fixtures/namespace/module-ir.json    | 22 +++++++++++++++++++
 .../src/test/fixtures/namespace/module.js     | 19 ++++++++++++++++
 .../test/fixtures/tags-function/code.js}      |  0
 .../test/fixtures/tags-function/exports.json} |  0
 .../test/fixtures/tags-variable/code.js}      |  0
 .../test/fixtures/tags-variable/exports.json} |  0
 .../tests/fixtures/default-import-named.js    |  6 -----
 .../docgen/tests/fixtures/named-default.js    |  1 -
 86 files changed, 58 insertions(+), 8 deletions(-)
 rename packages/docgen/{tests/fixtures/default-class-anonymous.js => src/test/fixtures/default-class-anonymous/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-class-anonymous.json => src/test/fixtures/default-class-anonymous/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-class-named.js => src/test/fixtures/default-class-named/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-class-named.json => src/test/fixtures/default-class-named/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-function-anonymous.js => src/test/fixtures/default-function-anonymous/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-function-anonymous.json => src/test/fixtures/default-function-anonymous/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-function-named-ast.json => src/test/fixtures/default-function-named/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/default-function-named.js => src/test/fixtures/default-function-named/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-function-named.json => src/test/fixtures/default-function-named/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-function-named-ir.json => src/test/fixtures/default-function-named/ir.json} (100%)
 rename packages/docgen/{tests/fixtures/default-identifier-ast.json => src/test/fixtures/default-identifier/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/default-identifier.js => src/test/fixtures/default-identifier/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-identifier.json => src/test/fixtures/default-identifier/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-import-default-ast.json => src/test/fixtures/default-import-default/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/default-import-default.js => src/test/fixtures/default-import-default/code.js} (51%)
 rename packages/docgen/{tests/fixtures/default-import-default.json => src/test/fixtures/default-import-default/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-import-default-module.js => src/test/fixtures/default-import-default/module-code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-import-default-module-ir.json => src/test/fixtures/default-import-default/module-ir.json} (100%)
 rename packages/docgen/{tests/fixtures/default-import-named-ast.json => src/test/fixtures/default-import-named/ast.json} (100%)
 create mode 100644 packages/docgen/src/test/fixtures/default-import-named/code.js
 rename packages/docgen/{tests/fixtures/default-import-named.json => src/test/fixtures/default-import-named/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-import-named-module.js => src/test/fixtures/default-import-named/module-code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-import-named-module-ir.json => src/test/fixtures/default-import-named/module-ir.json} (100%)
 rename packages/docgen/{tests/fixtures/default-named-export-ast.json => src/test/fixtures/default-named-export/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/default-named-export.js => src/test/fixtures/default-named-export/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-named-export.json => src/test/fixtures/default-named-export/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-undocumented-nocomments.js => src/test/fixtures/default-undocumented-nocomments/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-undocumented-nocomments.json => src/test/fixtures/default-undocumented-nocomments/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-undocumented-oneliner.js => src/test/fixtures/default-undocumented-oneliner/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-undocumented-oneliner.json => src/test/fixtures/default-undocumented-oneliner/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/default-variable.js => src/test/fixtures/default-variable/code.js} (100%)
 rename packages/docgen/{tests/fixtures/default-variable.json => src/test/fixtures/default-variable/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/markdown-code.js => src/test/fixtures/markdown/code.js} (100%)
 rename packages/docgen/{tests/fixtures/markdown-docs.md => src/test/fixtures/markdown/docs.md} (100%)
 rename packages/docgen/{tests/fixtures/named-class.js => src/test/fixtures/named-class/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-class.json => src/test/fixtures/named-class/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-default-exported.js => src/test/fixtures/named-default-exported/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-default-exported.json => src/test/fixtures/named-default-exported/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-default-module.js => src/test/fixtures/named-default-exported/module-code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-default-module-ir.json => src/test/fixtures/named-default-exported/module-ir.json} (100%)
 create mode 100644 packages/docgen/src/test/fixtures/named-default/code.js
 rename packages/docgen/{tests/fixtures/named-default.json => src/test/fixtures/named-default/exports.json} (100%)
 create mode 100644 packages/docgen/src/test/fixtures/named-default/module-code.js
 create mode 100644 packages/docgen/src/test/fixtures/named-default/module-ir.json
 rename packages/docgen/{tests/fixtures/named-function.js => src/test/fixtures/named-function/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-function.json => src/test/fixtures/named-function/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-function-ir.json => src/test/fixtures/named-function/ir.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier-destructuring-ast.json => src/test/fixtures/named-identifier-destructuring/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier-destructuring.js => src/test/fixtures/named-identifier-destructuring/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier-destructuring.json => src/test/fixtures/named-identifier-destructuring/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier-ast.json => src/test/fixtures/named-identifier/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier.js => src/test/fixtures/named-identifier/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-identifier.json => src/test/fixtures/named-identifier/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers-and-inline-ast.json => src/test/fixtures/named-identifiers-and-inline/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers-and-inline.js => src/test/fixtures/named-identifiers-and-inline/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers-and-inline.json => src/test/fixtures/named-identifiers-and-inline/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers-ast.json => src/test/fixtures/named-identifiers/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers.js => src/test/fixtures/named-identifiers/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers.json => src/test/fixtures/named-identifiers/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-identifiers-ir.json => src/test/fixtures/named-identifiers/ir.json} (100%)
 rename packages/docgen/{tests/fixtures/named-import-named.js => src/test/fixtures/named-import-named/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-import-named.json => src/test/fixtures/named-import-named/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace-ast.json => src/test/fixtures/named-import-namespace/ast.json} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace.js => src/test/fixtures/named-import-namespace/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace.json => src/test/fixtures/named-import-namespace/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace-module.js => src/test/fixtures/named-import-namespace/module-code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace-module.json => src/test/fixtures/named-import-namespace/module-exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-import-namespace-module-ir.json => src/test/fixtures/named-import-namespace/module-ir.json} (100%)
 rename packages/docgen/{tests/fixtures/named-variable.js => src/test/fixtures/named-variable/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-variable.json => src/test/fixtures/named-variable/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/named-variables.js => src/test/fixtures/named-variables/code.js} (100%)
 rename packages/docgen/{tests/fixtures/named-variables.json => src/test/fixtures/named-variables/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/namespace-commented.js => src/test/fixtures/namespace-commented/code.js} (100%)
 rename packages/docgen/{tests/fixtures/namespace-commented.json => src/test/fixtures/namespace-commented/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/namespace-module-ir.json => src/test/fixtures/namespace-commented/module-ir.json} (100%)
 rename packages/docgen/{tests/fixtures/namespace-module.js => src/test/fixtures/namespace-commented/module.js} (100%)
 rename packages/docgen/{tests/fixtures/namespace.js => src/test/fixtures/namespace/code.js} (100%)
 rename packages/docgen/{tests/fixtures/namespace.json => src/test/fixtures/namespace/exports.json} (100%)
 create mode 100644 packages/docgen/src/test/fixtures/namespace/module-ir.json
 create mode 100644 packages/docgen/src/test/fixtures/namespace/module.js
 rename packages/docgen/{tests/fixtures/tags-function.js => src/test/fixtures/tags-function/code.js} (100%)
 rename packages/docgen/{tests/fixtures/tags-function-exports.json => src/test/fixtures/tags-function/exports.json} (100%)
 rename packages/docgen/{tests/fixtures/tags-variable.js => src/test/fixtures/tags-variable/code.js} (100%)
 rename packages/docgen/{tests/fixtures/tags-variable-exports.json => src/test/fixtures/tags-variable/exports.json} (100%)
 delete mode 100644 packages/docgen/tests/fixtures/default-import-named.js
 delete mode 100644 packages/docgen/tests/fixtures/named-default.js

diff --git a/packages/docgen/tests/fixtures/default-class-anonymous.js b/packages/docgen/src/test/fixtures/default-class-anonymous/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-class-anonymous.js
rename to packages/docgen/src/test/fixtures/default-class-anonymous/code.js
diff --git a/packages/docgen/tests/fixtures/default-class-anonymous.json b/packages/docgen/src/test/fixtures/default-class-anonymous/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-class-anonymous.json
rename to packages/docgen/src/test/fixtures/default-class-anonymous/exports.json
diff --git a/packages/docgen/tests/fixtures/default-class-named.js b/packages/docgen/src/test/fixtures/default-class-named/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-class-named.js
rename to packages/docgen/src/test/fixtures/default-class-named/code.js
diff --git a/packages/docgen/tests/fixtures/default-class-named.json b/packages/docgen/src/test/fixtures/default-class-named/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-class-named.json
rename to packages/docgen/src/test/fixtures/default-class-named/exports.json
diff --git a/packages/docgen/tests/fixtures/default-function-anonymous.js b/packages/docgen/src/test/fixtures/default-function-anonymous/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-anonymous.js
rename to packages/docgen/src/test/fixtures/default-function-anonymous/code.js
diff --git a/packages/docgen/tests/fixtures/default-function-anonymous.json b/packages/docgen/src/test/fixtures/default-function-anonymous/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-anonymous.json
rename to packages/docgen/src/test/fixtures/default-function-anonymous/exports.json
diff --git a/packages/docgen/tests/fixtures/default-function-named-ast.json b/packages/docgen/src/test/fixtures/default-function-named/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-named-ast.json
rename to packages/docgen/src/test/fixtures/default-function-named/ast.json
diff --git a/packages/docgen/tests/fixtures/default-function-named.js b/packages/docgen/src/test/fixtures/default-function-named/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-named.js
rename to packages/docgen/src/test/fixtures/default-function-named/code.js
diff --git a/packages/docgen/tests/fixtures/default-function-named.json b/packages/docgen/src/test/fixtures/default-function-named/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-named.json
rename to packages/docgen/src/test/fixtures/default-function-named/exports.json
diff --git a/packages/docgen/tests/fixtures/default-function-named-ir.json b/packages/docgen/src/test/fixtures/default-function-named/ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-function-named-ir.json
rename to packages/docgen/src/test/fixtures/default-function-named/ir.json
diff --git a/packages/docgen/tests/fixtures/default-identifier-ast.json b/packages/docgen/src/test/fixtures/default-identifier/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-identifier-ast.json
rename to packages/docgen/src/test/fixtures/default-identifier/ast.json
diff --git a/packages/docgen/tests/fixtures/default-identifier.js b/packages/docgen/src/test/fixtures/default-identifier/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-identifier.js
rename to packages/docgen/src/test/fixtures/default-identifier/code.js
diff --git a/packages/docgen/tests/fixtures/default-identifier.json b/packages/docgen/src/test/fixtures/default-identifier/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-identifier.json
rename to packages/docgen/src/test/fixtures/default-identifier/exports.json
diff --git a/packages/docgen/tests/fixtures/default-import-default-ast.json b/packages/docgen/src/test/fixtures/default-import-default/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-default-ast.json
rename to packages/docgen/src/test/fixtures/default-import-default/ast.json
diff --git a/packages/docgen/tests/fixtures/default-import-default.js b/packages/docgen/src/test/fixtures/default-import-default/code.js
similarity index 51%
rename from packages/docgen/tests/fixtures/default-import-default.js
rename to packages/docgen/src/test/fixtures/default-import-default/code.js
index 073e3dde436f43..70619a579c57bf 100644
--- a/packages/docgen/tests/fixtures/default-import-default.js
+++ b/packages/docgen/src/test/fixtures/default-import-default/code.js
@@ -1,6 +1,6 @@
 /**
  * Internal dependencies
  */
-import fnDeclaration from './default-import-default-module';
+import fnDeclaration from './module-code';
 
 export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import-default.json b/packages/docgen/src/test/fixtures/default-import-default/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-default.json
rename to packages/docgen/src/test/fixtures/default-import-default/exports.json
diff --git a/packages/docgen/tests/fixtures/default-import-default-module.js b/packages/docgen/src/test/fixtures/default-import-default/module-code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-default-module.js
rename to packages/docgen/src/test/fixtures/default-import-default/module-code.js
diff --git a/packages/docgen/tests/fixtures/default-import-default-module-ir.json b/packages/docgen/src/test/fixtures/default-import-default/module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-default-module-ir.json
rename to packages/docgen/src/test/fixtures/default-import-default/module-ir.json
diff --git a/packages/docgen/tests/fixtures/default-import-named-ast.json b/packages/docgen/src/test/fixtures/default-import-named/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-named-ast.json
rename to packages/docgen/src/test/fixtures/default-import-named/ast.json
diff --git a/packages/docgen/src/test/fixtures/default-import-named/code.js b/packages/docgen/src/test/fixtures/default-import-named/code.js
new file mode 100644
index 00000000000000..b8e89023444b51
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/default-import-named/code.js
@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { functionDeclaration as fnDeclaration } from './module-code';
+
+export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/default-import-named.json b/packages/docgen/src/test/fixtures/default-import-named/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-named.json
rename to packages/docgen/src/test/fixtures/default-import-named/exports.json
diff --git a/packages/docgen/tests/fixtures/default-import-named-module.js b/packages/docgen/src/test/fixtures/default-import-named/module-code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-named-module.js
rename to packages/docgen/src/test/fixtures/default-import-named/module-code.js
diff --git a/packages/docgen/tests/fixtures/default-import-named-module-ir.json b/packages/docgen/src/test/fixtures/default-import-named/module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-import-named-module-ir.json
rename to packages/docgen/src/test/fixtures/default-import-named/module-ir.json
diff --git a/packages/docgen/tests/fixtures/default-named-export-ast.json b/packages/docgen/src/test/fixtures/default-named-export/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-named-export-ast.json
rename to packages/docgen/src/test/fixtures/default-named-export/ast.json
diff --git a/packages/docgen/tests/fixtures/default-named-export.js b/packages/docgen/src/test/fixtures/default-named-export/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-named-export.js
rename to packages/docgen/src/test/fixtures/default-named-export/code.js
diff --git a/packages/docgen/tests/fixtures/default-named-export.json b/packages/docgen/src/test/fixtures/default-named-export/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-named-export.json
rename to packages/docgen/src/test/fixtures/default-named-export/exports.json
diff --git a/packages/docgen/tests/fixtures/default-undocumented-nocomments.js b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-undocumented-nocomments.js
rename to packages/docgen/src/test/fixtures/default-undocumented-nocomments/code.js
diff --git a/packages/docgen/tests/fixtures/default-undocumented-nocomments.json b/packages/docgen/src/test/fixtures/default-undocumented-nocomments/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-undocumented-nocomments.json
rename to packages/docgen/src/test/fixtures/default-undocumented-nocomments/exports.json
diff --git a/packages/docgen/tests/fixtures/default-undocumented-oneliner.js b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-undocumented-oneliner.js
rename to packages/docgen/src/test/fixtures/default-undocumented-oneliner/code.js
diff --git a/packages/docgen/tests/fixtures/default-undocumented-oneliner.json b/packages/docgen/src/test/fixtures/default-undocumented-oneliner/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-undocumented-oneliner.json
rename to packages/docgen/src/test/fixtures/default-undocumented-oneliner/exports.json
diff --git a/packages/docgen/tests/fixtures/default-variable.js b/packages/docgen/src/test/fixtures/default-variable/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/default-variable.js
rename to packages/docgen/src/test/fixtures/default-variable/code.js
diff --git a/packages/docgen/tests/fixtures/default-variable.json b/packages/docgen/src/test/fixtures/default-variable/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/default-variable.json
rename to packages/docgen/src/test/fixtures/default-variable/exports.json
diff --git a/packages/docgen/tests/fixtures/markdown-code.js b/packages/docgen/src/test/fixtures/markdown/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/markdown-code.js
rename to packages/docgen/src/test/fixtures/markdown/code.js
diff --git a/packages/docgen/tests/fixtures/markdown-docs.md b/packages/docgen/src/test/fixtures/markdown/docs.md
similarity index 100%
rename from packages/docgen/tests/fixtures/markdown-docs.md
rename to packages/docgen/src/test/fixtures/markdown/docs.md
diff --git a/packages/docgen/tests/fixtures/named-class.js b/packages/docgen/src/test/fixtures/named-class/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-class.js
rename to packages/docgen/src/test/fixtures/named-class/code.js
diff --git a/packages/docgen/tests/fixtures/named-class.json b/packages/docgen/src/test/fixtures/named-class/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-class.json
rename to packages/docgen/src/test/fixtures/named-class/exports.json
diff --git a/packages/docgen/tests/fixtures/named-default-exported.js b/packages/docgen/src/test/fixtures/named-default-exported/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-default-exported.js
rename to packages/docgen/src/test/fixtures/named-default-exported/code.js
diff --git a/packages/docgen/tests/fixtures/named-default-exported.json b/packages/docgen/src/test/fixtures/named-default-exported/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-default-exported.json
rename to packages/docgen/src/test/fixtures/named-default-exported/exports.json
diff --git a/packages/docgen/tests/fixtures/named-default-module.js b/packages/docgen/src/test/fixtures/named-default-exported/module-code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-default-module.js
rename to packages/docgen/src/test/fixtures/named-default-exported/module-code.js
diff --git a/packages/docgen/tests/fixtures/named-default-module-ir.json b/packages/docgen/src/test/fixtures/named-default-exported/module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-default-module-ir.json
rename to packages/docgen/src/test/fixtures/named-default-exported/module-ir.json
diff --git a/packages/docgen/src/test/fixtures/named-default/code.js b/packages/docgen/src/test/fixtures/named-default/code.js
new file mode 100644
index 00000000000000..441f6e366117f8
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/named-default/code.js
@@ -0,0 +1 @@
+export { default } from './module-code';
diff --git a/packages/docgen/tests/fixtures/named-default.json b/packages/docgen/src/test/fixtures/named-default/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-default.json
rename to packages/docgen/src/test/fixtures/named-default/exports.json
diff --git a/packages/docgen/src/test/fixtures/named-default/module-code.js b/packages/docgen/src/test/fixtures/named-default/module-code.js
new file mode 100644
index 00000000000000..92127f1f850593
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/named-default/module-code.js
@@ -0,0 +1,4 @@
+/**
+ * Module declaration.
+ */
+export default function( ) {}
diff --git a/packages/docgen/src/test/fixtures/named-default/module-ir.json b/packages/docgen/src/test/fixtures/named-default/module-ir.json
new file mode 100644
index 00000000000000..9e9b2ce30509ed
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/named-default/module-ir.json
@@ -0,0 +1,5 @@
+[{
+	"name": "default",
+	"description": "Module declaration.",
+	"tags": []
+}]
\ No newline at end of file
diff --git a/packages/docgen/tests/fixtures/named-function.js b/packages/docgen/src/test/fixtures/named-function/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function.js
rename to packages/docgen/src/test/fixtures/named-function/code.js
diff --git a/packages/docgen/tests/fixtures/named-function.json b/packages/docgen/src/test/fixtures/named-function/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function.json
rename to packages/docgen/src/test/fixtures/named-function/exports.json
diff --git a/packages/docgen/tests/fixtures/named-function-ir.json b/packages/docgen/src/test/fixtures/named-function/ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-function-ir.json
rename to packages/docgen/src/test/fixtures/named-function/ir.json
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json b/packages/docgen/src/test/fixtures/named-identifier-destructuring/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-destructuring-ast.json
rename to packages/docgen/src/test/fixtures/named-identifier-destructuring/ast.json
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring.js b/packages/docgen/src/test/fixtures/named-identifier-destructuring/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-destructuring.js
rename to packages/docgen/src/test/fixtures/named-identifier-destructuring/code.js
diff --git a/packages/docgen/tests/fixtures/named-identifier-destructuring.json b/packages/docgen/src/test/fixtures/named-identifier-destructuring/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-destructuring.json
rename to packages/docgen/src/test/fixtures/named-identifier-destructuring/exports.json
diff --git a/packages/docgen/tests/fixtures/named-identifier-ast.json b/packages/docgen/src/test/fixtures/named-identifier/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier-ast.json
rename to packages/docgen/src/test/fixtures/named-identifier/ast.json
diff --git a/packages/docgen/tests/fixtures/named-identifier.js b/packages/docgen/src/test/fixtures/named-identifier/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier.js
rename to packages/docgen/src/test/fixtures/named-identifier/code.js
diff --git a/packages/docgen/tests/fixtures/named-identifier.json b/packages/docgen/src/test/fixtures/named-identifier/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifier.json
rename to packages/docgen/src/test/fixtures/named-identifier/exports.json
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers-and-inline-ast.json
rename to packages/docgen/src/test/fixtures/named-identifiers-and-inline/ast.json
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline.js b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers-and-inline.js
rename to packages/docgen/src/test/fixtures/named-identifiers-and-inline/code.js
diff --git a/packages/docgen/tests/fixtures/named-identifiers-and-inline.json b/packages/docgen/src/test/fixtures/named-identifiers-and-inline/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers-and-inline.json
rename to packages/docgen/src/test/fixtures/named-identifiers-and-inline/exports.json
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ast.json b/packages/docgen/src/test/fixtures/named-identifiers/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers-ast.json
rename to packages/docgen/src/test/fixtures/named-identifiers/ast.json
diff --git a/packages/docgen/tests/fixtures/named-identifiers.js b/packages/docgen/src/test/fixtures/named-identifiers/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers.js
rename to packages/docgen/src/test/fixtures/named-identifiers/code.js
diff --git a/packages/docgen/tests/fixtures/named-identifiers.json b/packages/docgen/src/test/fixtures/named-identifiers/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers.json
rename to packages/docgen/src/test/fixtures/named-identifiers/exports.json
diff --git a/packages/docgen/tests/fixtures/named-identifiers-ir.json b/packages/docgen/src/test/fixtures/named-identifiers/ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-identifiers-ir.json
rename to packages/docgen/src/test/fixtures/named-identifiers/ir.json
diff --git a/packages/docgen/tests/fixtures/named-import-named.js b/packages/docgen/src/test/fixtures/named-import-named/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-named.js
rename to packages/docgen/src/test/fixtures/named-import-named/code.js
diff --git a/packages/docgen/tests/fixtures/named-import-named.json b/packages/docgen/src/test/fixtures/named-import-named/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-named.json
rename to packages/docgen/src/test/fixtures/named-import-named/exports.json
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-ast.json b/packages/docgen/src/test/fixtures/named-import-namespace/ast.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace-ast.json
rename to packages/docgen/src/test/fixtures/named-import-namespace/ast.json
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.js b/packages/docgen/src/test/fixtures/named-import-namespace/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace.js
rename to packages/docgen/src/test/fixtures/named-import-namespace/code.js
diff --git a/packages/docgen/tests/fixtures/named-import-namespace.json b/packages/docgen/src/test/fixtures/named-import-namespace/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace.json
rename to packages/docgen/src/test/fixtures/named-import-namespace/exports.json
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module.js b/packages/docgen/src/test/fixtures/named-import-namespace/module-code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace-module.js
rename to packages/docgen/src/test/fixtures/named-import-namespace/module-code.js
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module.json b/packages/docgen/src/test/fixtures/named-import-namespace/module-exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace-module.json
rename to packages/docgen/src/test/fixtures/named-import-namespace/module-exports.json
diff --git a/packages/docgen/tests/fixtures/named-import-namespace-module-ir.json b/packages/docgen/src/test/fixtures/named-import-namespace/module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-import-namespace-module-ir.json
rename to packages/docgen/src/test/fixtures/named-import-namespace/module-ir.json
diff --git a/packages/docgen/tests/fixtures/named-variable.js b/packages/docgen/src/test/fixtures/named-variable/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-variable.js
rename to packages/docgen/src/test/fixtures/named-variable/code.js
diff --git a/packages/docgen/tests/fixtures/named-variable.json b/packages/docgen/src/test/fixtures/named-variable/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-variable.json
rename to packages/docgen/src/test/fixtures/named-variable/exports.json
diff --git a/packages/docgen/tests/fixtures/named-variables.js b/packages/docgen/src/test/fixtures/named-variables/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/named-variables.js
rename to packages/docgen/src/test/fixtures/named-variables/code.js
diff --git a/packages/docgen/tests/fixtures/named-variables.json b/packages/docgen/src/test/fixtures/named-variables/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/named-variables.json
rename to packages/docgen/src/test/fixtures/named-variables/exports.json
diff --git a/packages/docgen/tests/fixtures/namespace-commented.js b/packages/docgen/src/test/fixtures/namespace-commented/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace-commented.js
rename to packages/docgen/src/test/fixtures/namespace-commented/code.js
diff --git a/packages/docgen/tests/fixtures/namespace-commented.json b/packages/docgen/src/test/fixtures/namespace-commented/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace-commented.json
rename to packages/docgen/src/test/fixtures/namespace-commented/exports.json
diff --git a/packages/docgen/tests/fixtures/namespace-module-ir.json b/packages/docgen/src/test/fixtures/namespace-commented/module-ir.json
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace-module-ir.json
rename to packages/docgen/src/test/fixtures/namespace-commented/module-ir.json
diff --git a/packages/docgen/tests/fixtures/namespace-module.js b/packages/docgen/src/test/fixtures/namespace-commented/module.js
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace-module.js
rename to packages/docgen/src/test/fixtures/namespace-commented/module.js
diff --git a/packages/docgen/tests/fixtures/namespace.js b/packages/docgen/src/test/fixtures/namespace/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace.js
rename to packages/docgen/src/test/fixtures/namespace/code.js
diff --git a/packages/docgen/tests/fixtures/namespace.json b/packages/docgen/src/test/fixtures/namespace/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/namespace.json
rename to packages/docgen/src/test/fixtures/namespace/exports.json
diff --git a/packages/docgen/src/test/fixtures/namespace/module-ir.json b/packages/docgen/src/test/fixtures/namespace/module-ir.json
new file mode 100644
index 00000000000000..7798095b482fac
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/namespace/module-ir.json
@@ -0,0 +1,22 @@
+[
+	{
+		"name": "default",
+		"description": "Default variable declaration.",
+		"tags": []
+	},
+	{
+		"name": "MyClass",
+		"description": "Named class.",
+		"tags": []
+	},
+	{
+		"name": "myFunction",
+		"description": "Named function.",
+		"tags": []
+	},
+	{
+		"name": "myVariable",
+		"description": "Named variable.",
+		"tags": []
+	}
+]
\ No newline at end of file
diff --git a/packages/docgen/src/test/fixtures/namespace/module.js b/packages/docgen/src/test/fixtures/namespace/module.js
new file mode 100644
index 00000000000000..1ff51c686236af
--- /dev/null
+++ b/packages/docgen/src/test/fixtures/namespace/module.js
@@ -0,0 +1,19 @@
+/**
+ * Named variable.
+ */
+export const myVariable = true;
+
+/**
+ * Named function.
+ */
+export const myFunction = () => {};
+
+/**
+ * Named class.
+ */
+export class MyClass {}
+
+/**
+ * Default variable declaration.
+ */
+export default 42;
diff --git a/packages/docgen/tests/fixtures/tags-function.js b/packages/docgen/src/test/fixtures/tags-function/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/tags-function.js
rename to packages/docgen/src/test/fixtures/tags-function/code.js
diff --git a/packages/docgen/tests/fixtures/tags-function-exports.json b/packages/docgen/src/test/fixtures/tags-function/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/tags-function-exports.json
rename to packages/docgen/src/test/fixtures/tags-function/exports.json
diff --git a/packages/docgen/tests/fixtures/tags-variable.js b/packages/docgen/src/test/fixtures/tags-variable/code.js
similarity index 100%
rename from packages/docgen/tests/fixtures/tags-variable.js
rename to packages/docgen/src/test/fixtures/tags-variable/code.js
diff --git a/packages/docgen/tests/fixtures/tags-variable-exports.json b/packages/docgen/src/test/fixtures/tags-variable/exports.json
similarity index 100%
rename from packages/docgen/tests/fixtures/tags-variable-exports.json
rename to packages/docgen/src/test/fixtures/tags-variable/exports.json
diff --git a/packages/docgen/tests/fixtures/default-import-named.js b/packages/docgen/tests/fixtures/default-import-named.js
deleted file mode 100644
index b7f4609237c6c0..00000000000000
--- a/packages/docgen/tests/fixtures/default-import-named.js
+++ /dev/null
@@ -1,6 +0,0 @@
-/**
- * Internal dependencies
- */
-import { functionDeclaration as fnDeclaration } from './default-import-named-module';
-
-export default fnDeclaration;
diff --git a/packages/docgen/tests/fixtures/named-default.js b/packages/docgen/tests/fixtures/named-default.js
deleted file mode 100644
index 3cca6a9d490692..00000000000000
--- a/packages/docgen/tests/fixtures/named-default.js
+++ /dev/null
@@ -1 +0,0 @@
-export { default } from './named-default-module';

From 62878c69b2e5284c6813ffbe8e608fca7954ce92 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:09:00 +0100
Subject: [PATCH 193/213] Migrate export tests to jest

---
 .../docgen/src/test/get-export-entries.js     | 352 ++++++++++++++++++
 .../docgen/tests/test-get-export-entries.js   | 343 -----------------
 2 files changed, 352 insertions(+), 343 deletions(-)
 create mode 100644 packages/docgen/src/test/get-export-entries.js
 delete mode 100644 packages/docgen/tests/test-get-export-entries.js

diff --git a/packages/docgen/src/test/get-export-entries.js b/packages/docgen/src/test/get-export-entries.js
new file mode 100644
index 00000000000000..b1e06f9d145a9c
--- /dev/null
+++ b/packages/docgen/src/test/get-export-entries.js
@@ -0,0 +1,352 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies.
+ */
+const getExportEntries = require( '../get-export-entries' );
+
+describe( 'Export entries', function() {
+	it( 'default class (anonymous)', () => {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-class-anonymous/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: '*default*',
+			exportName: 'default',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'default class (named)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-class-named/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'ClassDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'default function (anonymous)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-function-anonymous/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: '*default*',
+			exportName: 'default',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'default function (named)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-function-named/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'myDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'default identifier', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-identifier/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'ClassDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 6,
+			lineEnd: 6,
+		} );
+	} );
+
+	it( 'default import (named)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-import-named/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'fnDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 3,
+			lineEnd: 3,
+		} );
+	} );
+
+	it( 'default import (default)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-import-default/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'fnDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 3,
+			lineEnd: 3,
+		} );
+	} );
+
+	it( 'default named export', function() {
+		const tokens = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-named-export/exports.json' ),
+			'utf-8'
+		);
+		const namedExport = getExportEntries( JSON.parse( tokens )[ 0 ] );
+		expect( namedExport ).toHaveLength( 1 );
+		expect( namedExport[ 0 ] ).toEqual( {
+			localName: 'functionDeclaration',
+			exportName: 'functionDeclaration',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+		const defaultExport = getExportEntries( JSON.parse( tokens )[ 1 ] );
+		expect( defaultExport ).toHaveLength( 1 );
+		expect( defaultExport[ 0 ] ).toEqual( {
+			localName: 'functionDeclaration',
+			exportName: 'default',
+			module: null,
+			lineStart: 6,
+			lineEnd: 6,
+		} );
+	} );
+
+	it( 'default variable', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-variable/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: '*default*',
+			exportName: 'default',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'named class', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-class/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'MyDeclaration',
+			exportName: 'MyDeclaration',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'named default', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-default/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'default',
+			exportName: 'default',
+			module: './named-default-module',
+			lineStart: 1,
+			lineEnd: 1,
+		} );
+	} );
+
+	it( 'named default (exported)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-default-exported/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'default',
+			exportName: 'moduleName',
+			module: './named-default-module',
+			lineStart: 1,
+			lineEnd: 1,
+		} );
+	} );
+
+	it( 'named function', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-function/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'myDeclaration',
+			exportName: 'myDeclaration',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'named identifier', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-identifier/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'myDeclaration',
+			exportName: 'myDeclaration',
+			module: null,
+			lineStart: 6,
+			lineEnd: 6,
+		} );
+		const tokenObject = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-identifier-destructuring/exports.json' ),
+			'utf-8'
+		);
+		const nameObject = getExportEntries( JSON.parse( tokenObject ) );
+		expect( nameObject ).toHaveLength( 1 );
+		expect( nameObject[ 0 ] ).toEqual( {
+			localName: 'someDeclaration',
+			exportName: 'myDeclaration',
+			module: null,
+			lineStart: 6,
+			lineEnd: 6,
+		} );
+	} );
+
+	it( 'named identifiers', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-identifiers/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 3 );
+		expect( name[ 0 ] ).toEqual(
+			{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 16, lineEnd: 16 }
+		);
+		expect( name[ 1 ] ).toEqual(
+			{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
+		);
+		expect( name[ 2 ] ).toEqual(
+			{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 16, lineEnd: 16 },
+		);
+		const tokenIdentifiersAndInline = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-identifiers-and-inline/exports.json' ),
+			'utf-8'
+		);
+		const nameInline0 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 0 ] );
+		expect( nameInline0 ).toHaveLength( 2 );
+		expect( nameInline0[ 0 ] ).toEqual(
+			{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 11, lineEnd: 11 },
+		);
+		expect( nameInline0[ 1 ] ).toEqual(
+			{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 11, lineEnd: 11 },
+		);
+		const nameInline1 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 1 ] );
+		expect( nameInline1 ).toHaveLength( 1 );
+		expect( nameInline1[ 0 ] ).toEqual(
+			{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
+		);
+	} );
+
+	it( 'named import namespace', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-import-namespace/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual(
+			{ localName: 'variables', exportName: 'variables', module: null, lineStart: 3, lineEnd: 3 },
+		);
+	} );
+
+	it( 'named variable', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-variable/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: 'myDeclaration',
+			exportName: 'myDeclaration',
+			module: null,
+			lineStart: 4,
+			lineEnd: 4,
+		} );
+	} );
+
+	it( 'named variables', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/named-variables/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 2 );
+		expect( name[ 0 ] ).toEqual(
+			{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null, lineStart: 4, lineEnd: 5 },
+		);
+		expect( name[ 1 ] ).toEqual(
+			{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null, lineStart: 4, lineEnd: 5 },
+		);
+	} );
+
+	it( 'namespace (*)', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/namespace/exports.json' ),
+			'utf-8'
+		);
+		const name = getExportEntries( JSON.parse( token ) );
+		expect( name ).toHaveLength( 1 );
+		expect( name[ 0 ] ).toEqual( {
+			localName: '*',
+			exportName: null,
+			module: './namespace-module',
+			lineStart: 1,
+			lineEnd: 1,
+		} );
+	} );
+} );
diff --git a/packages/docgen/tests/test-get-export-entries.js b/packages/docgen/tests/test-get-export-entries.js
deleted file mode 100644
index 03057dcca87efe..00000000000000
--- a/packages/docgen/tests/test-get-export-entries.js
+++ /dev/null
@@ -1,343 +0,0 @@
-/**
- * Node dependencies.
- */
-const fs = require( 'fs' );
-const path = require( 'path' );
-
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const getExportEntries = require( '../src/get-export-entries' );
-
-test( 'Export entries - default class (anonymous)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: '*default*',
-		exportName: 'default',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default class (named)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-named.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'ClassDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default function (anonymous)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: '*default*',
-		exportName: 'default',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default function (named)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-named.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'myDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default identifier', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'ClassDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default import (named)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'fnDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 3,
-		lineEnd: 3,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default import (default)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'fnDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 3,
-		lineEnd: 3,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default named export', function( t ) {
-	const tokens = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-named-export.json' ),
-		'utf-8'
-	);
-	const namedExport = getExportEntries( JSON.parse( tokens )[ 0 ] );
-	t.deepEqual( namedExport, [ {
-		localName: 'functionDeclaration',
-		exportName: 'functionDeclaration',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const defaultExport = getExportEntries( JSON.parse( tokens )[ 1 ] );
-	t.deepEqual( defaultExport, [ {
-		localName: 'functionDeclaration',
-		exportName: 'default',
-		module: null,
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - default variable', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: '*default*',
-		exportName: 'default',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named class', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-class.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'MyDeclaration',
-		exportName: 'MyDeclaration',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named default', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'default',
-		exportName: 'default',
-		module: './named-default-module',
-		lineStart: 1,
-		lineEnd: 1,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named default (exported)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default-exported.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'default',
-		exportName: 'moduleName',
-		module: './named-default-module',
-		lineStart: 1,
-		lineEnd: 1,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named function', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'myDeclaration',
-		exportName: 'myDeclaration',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named identifier', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'myDeclaration',
-		exportName: 'myDeclaration',
-		module: null,
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	const tokenObject = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
-		'utf-8'
-	);
-	const nameObject = getExportEntries( JSON.parse( tokenObject ) );
-	t.deepEqual( nameObject, [ {
-		localName: 'someDeclaration',
-		exportName: 'myDeclaration',
-		module: null,
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named identifiers', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [
-		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 16, lineEnd: 16 },
-		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
-		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 16, lineEnd: 16 },
-	] );
-	const tokenIdentifiersAndInline = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
-		'utf-8'
-	);
-	const name0 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 0 ] );
-	t.deepEqual( name0, [
-		{ localName: 'functionDeclaration', exportName: 'functionDeclaration', module: null, lineStart: 11, lineEnd: 11 },
-		{ localName: 'ClassDeclaration', exportName: 'ClassDeclaration', module: null, lineStart: 11, lineEnd: 11 },
-	] );
-	const name1 = getExportEntries( JSON.parse( tokenIdentifiersAndInline )[ 1 ] );
-	t.deepEqual( name1, [
-		{ localName: 'variableDeclaration', exportName: 'variableDeclaration', module: null, lineStart: 16, lineEnd: 16 },
-	] );
-	t.end();
-} );
-
-test( 'Export entries - named import namespace', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-namespace.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [
-		{ localName: 'variables', exportName: 'variables', module: null, lineStart: 3, lineEnd: 3 },
-	] );
-	t.end();
-} );
-
-test( 'Export entries - named variable', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variable.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: 'myDeclaration',
-		exportName: 'myDeclaration',
-		module: null,
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'Export entries - named variables', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variables.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [
-		{ localName: 'firstDeclaration', exportName: 'firstDeclaration', module: null, lineStart: 4, lineEnd: 5 },
-		{ localName: 'secondDeclaration', exportName: 'secondDeclaration', module: null, lineStart: 4, lineEnd: 5 },
-	] );
-	t.end();
-} );
-
-test( 'Export entries - namespace (*)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/namespace.json' ),
-		'utf-8'
-	);
-	const name = getExportEntries( JSON.parse( token ) );
-	t.deepEqual( name, [ {
-		localName: '*',
-		exportName: null,
-		module: './namespace-module',
-		lineStart: 1,
-		lineEnd: 1,
-	} ] );
-	t.end();
-} );

From ba86e53bbbe4b44add85a6a783f04af1f55ca7e8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:14:04 +0100
Subject: [PATCH 194/213] Migrate getTypeFromJSDoc tests to jest

---
 .../docgen/src/test/get-type-as-string.js     | 108 ++++++++++++++++
 .../docgen/tests/test-get-type-as-string.js   | 117 ------------------
 2 files changed, 108 insertions(+), 117 deletions(-)
 create mode 100644 packages/docgen/src/test/get-type-as-string.js
 delete mode 100644 packages/docgen/tests/test-get-type-as-string.js

diff --git a/packages/docgen/src/test/get-type-as-string.js b/packages/docgen/src/test/get-type-as-string.js
new file mode 100644
index 00000000000000..6ba09acd33df18
--- /dev/null
+++ b/packages/docgen/src/test/get-type-as-string.js
@@ -0,0 +1,108 @@
+/**
+ * Internal dependencies.
+ */
+const getType = require( '../get-type-as-string' );
+
+describe( 'getType from JSDoc', () => {
+	it( 'NameExpression', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'NameExpression',
+				name: 'Array',
+			},
+			name: 'paramName',
+		} );
+		expect( type ).toBe( 'Array' );
+	} );
+
+	it( 'AllLiteral', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'AllLiteral',
+			},
+			name: 'paramName',
+		} );
+		expect( type ).toBe( '*' );
+	} );
+
+	it( 'Applications', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'TypeApplication',
+				expression: {
+					type: 'NameExpression',
+					name: 'Array',
+				},
+				applications: [
+					{
+						type: 'NameExpression',
+						name: 'Object',
+					},
+					{
+						type: 'NameExpression',
+						name: 'String',
+					},
+				],
+			},
+		} );
+		expect( type ).toBe( 'Array<Object,String>' );
+	} );
+
+	it( 'NullableType', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'NullableType',
+				expression: {
+					type: 'NameExpression',
+					name: 'string',
+				},
+				prefix: true,
+			},
+			name: 'paramName',
+		} );
+		expect( type ).toBe( '?string' );
+	} );
+
+	it( 'RestType', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'RestType',
+				expression: {
+					type: 'NameExpression',
+					name: 'Function',
+				},
+			},
+			name: 'paramName',
+		} );
+		expect( type ).toBe( '...Function' );
+	} );
+
+	it( 'RestType with UnionType', () => {
+		const type = getType( {
+			title: 'param',
+			description: 'description',
+			type: {
+				type: 'RestType',
+				expression: {
+					type: 'UnionType',
+					elements: [
+						{ type: 'NameExpression', name: 'Object' },
+						{ type: 'NameExpression', name: 'string' },
+					],
+				},
+			},
+			name: 'paramName',
+		} );
+		expect( type ).toBe( '...(Object|string)' );
+	} );
+} );
diff --git a/packages/docgen/tests/test-get-type-as-string.js b/packages/docgen/tests/test-get-type-as-string.js
deleted file mode 100644
index 2b7e071ba621d5..00000000000000
--- a/packages/docgen/tests/test-get-type-as-string.js
+++ /dev/null
@@ -1,117 +0,0 @@
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const getType = require( '../src/get-type-as-string' );
-
-test( 'JSDoc - getType from NameExpression', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'NameExpression',
-			name: 'Array',
-		},
-		name: 'paramName',
-	} );
-	t.equal( type, 'Array' );
-	t.end();
-} );
-
-test( 'JSDoc - getType from AllLiteral', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'AllLiteral',
-		},
-		name: 'paramName',
-	} );
-	t.equal( type, '*' );
-	t.end();
-} );
-
-test( 'JSDoc - getType with applications', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'TypeApplication',
-			expression: {
-				type: 'NameExpression',
-				name: 'Array',
-			},
-			applications: [
-				{
-					type: 'NameExpression',
-					name: 'Object',
-				},
-				{
-					type: 'NameExpression',
-					name: 'String',
-				},
-			],
-		},
-	} );
-	t.equal( type, 'Array<Object,String>' );
-	t.end();
-} );
-
-test( 'JSDoc - getType from NullableType', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'NullableType',
-			expression: {
-				type: 'NameExpression',
-				name: 'string',
-			},
-			prefix: true,
-		},
-		name: 'paramName',
-	} );
-	t.equal( type, '?string' );
-	t.end();
-} );
-
-test( 'JSDoc - getType from RestType', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'RestType',
-			expression: {
-				type: 'NameExpression',
-				name: 'Function',
-			},
-		},
-		name: 'paramName',
-	} );
-	t.equal( type, '...Function' );
-	t.end();
-} );
-
-test( 'JSDoc - getType from RestType with UnionType', ( t ) => {
-	const type = getType( {
-		title: 'param',
-		description: 'description',
-		type: {
-			type: 'RestType',
-			expression: {
-				type: 'UnionType',
-				elements: [
-					{ type: 'NameExpression', name: 'Object' },
-					{ type: 'NameExpression', name: 'string' },
-				],
-			},
-		},
-		name: 'paramName',
-	} );
-	t.equal( type, '...(Object|string)' );
-	t.end();
-} );

From a4af39dc21865358646c9ecfb79f04077baabe25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:20:41 +0100
Subject: [PATCH 195/213] Migrate getJSDocFromToken tests to jest

---
 .../docgen/src/test/get-jsdoc-from-token.js   | 78 ++++++++++++++++++
 .../docgen/tests/test-get-jsdoc-from-token.js | 80 -------------------
 2 files changed, 78 insertions(+), 80 deletions(-)
 create mode 100644 packages/docgen/src/test/get-jsdoc-from-token.js
 delete mode 100644 packages/docgen/tests/test-get-jsdoc-from-token.js

diff --git a/packages/docgen/src/test/get-jsdoc-from-token.js b/packages/docgen/src/test/get-jsdoc-from-token.js
new file mode 100644
index 00000000000000..335d63e7935ac8
--- /dev/null
+++ b/packages/docgen/src/test/get-jsdoc-from-token.js
@@ -0,0 +1,78 @@
+/**
+ * Internal dependencies.
+ */
+const getJSDocFromToken = require( '../get-jsdoc-from-token' );
+
+describe( 'JSDoc', () => {
+	it( 'extracts description and tags', () => {
+		expect(
+			getJSDocFromToken( {
+				leadingComments: [ {
+					value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ',
+				} ],
+			} )
+		).toEqual(
+			{
+				description: 'A function that adds two parameters.',
+				tags: [
+					{
+						title: 'deprecated',
+						description: 'Use native addition instead.',
+					},
+					{
+						title: 'since',
+						description: 'v2',
+					},
+					{
+						title: 'see',
+						description: 'addition',
+					},
+					{
+						title: 'link',
+						description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators',
+					},
+					{
+						title: 'param',
+						description: 'The first param to add.',
+						type: 'number',
+						name: 'firstParam',
+					},
+					{
+						title: 'param',
+						description: 'The second param to add.',
+						type: 'number',
+						name: 'secondParam',
+					},
+					{
+						title: 'example',
+						description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
+					},
+					{
+						title: 'return',
+						description: 'The result of adding the two params.',
+						type: 'number',
+					},
+				],
+			}
+		);
+
+		expect(
+			getJSDocFromToken( {
+				leadingComments: [ {
+					value: '*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ',
+				} ],
+			} )
+		).toEqual(
+			{
+				description: 'Constant to document the meaning of life,\nthe universe and everything else.',
+				tags: [
+					{
+						title: 'type',
+						description: null,
+						type: 'number',
+					},
+				],
+			}
+		);
+	} );
+} );
diff --git a/packages/docgen/tests/test-get-jsdoc-from-token.js b/packages/docgen/tests/test-get-jsdoc-from-token.js
deleted file mode 100644
index e296ba1a6b7914..00000000000000
--- a/packages/docgen/tests/test-get-jsdoc-from-token.js
+++ /dev/null
@@ -1,80 +0,0 @@
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const getJSDocFromToken = require( '../src/get-jsdoc-from-token' );
-
-test( 'JSDoc - extracts description and tags', function( t ) {
-	t.deepEqual(
-		getJSDocFromToken( {
-			leadingComments: [ {
-				value: '*\n * A function that adds two parameters.\n *\n * @deprecated Use native addition instead.\n * @since v2\n *\n * @see addition\n * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators\n *\n * @param {number} firstParam The first param to add.\n * @param {number} secondParam The second param to add.\n *\n *  @example\n *\n * ```js\n * const addResult = sum( 1, 3 );\n * console.log( addResult ); // will yield 4\n * ```\n *\n * @return {number} The result of adding the two params.\n ',
-			} ],
-		} ),
-		{
-			description: 'A function that adds two parameters.',
-			tags: [
-				{
-					title: 'deprecated',
-					description: 'Use native addition instead.',
-				},
-				{
-					title: 'since',
-					description: 'v2',
-				},
-				{
-					title: 'see',
-					description: 'addition',
-				},
-				{
-					title: 'link',
-					description: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Arithmetic_Operators',
-				},
-				{
-					title: 'param',
-					description: 'The first param to add.',
-					type: 'number',
-					name: 'firstParam',
-				},
-				{
-					title: 'param',
-					description: 'The second param to add.',
-					type: 'number',
-					name: 'secondParam',
-				},
-				{
-					title: 'example',
-					description: '```js\nconst addResult = sum( 1, 3 );\nconsole.log( addResult ); // will yield 4\n```',
-				},
-				{
-					title: 'return',
-					description: 'The result of adding the two params.',
-					type: 'number',
-				},
-			],
-		}
-	);
-
-	t.deepEqual(
-		getJSDocFromToken( {
-			leadingComments: [ {
-				value: '*\n * Constant to document the meaning of life,\n * the universe and everything else.\n *\n * @type {number}\n ',
-			} ],
-		} ),
-		{
-			description: 'Constant to document the meaning of life,\nthe universe and everything else.',
-			tags: [
-				{
-					title: 'type',
-					description: null,
-					type: 'number',
-				},
-			],
-		}
-	);
-	t.end();
-} );

From 99a41f3e831bb71f19424cde0f6fed4b2dc960c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:55:55 +0100
Subject: [PATCH 196/213] Migrate getIntermediateRepresentation tests to jest

---
 .../test/get-intermediate-representation.js   | 454 ++++++++++++++++++
 .../test-get-intermediate-representation.js   | 410 ----------------
 2 files changed, 454 insertions(+), 410 deletions(-)
 create mode 100644 packages/docgen/src/test/get-intermediate-representation.js
 delete mode 100644 packages/docgen/tests/test-get-intermediate-representation.js

diff --git a/packages/docgen/src/test/get-intermediate-representation.js b/packages/docgen/src/test/get-intermediate-representation.js
new file mode 100644
index 00000000000000..53cb937a2be518
--- /dev/null
+++ b/packages/docgen/src/test/get-intermediate-representation.js
@@ -0,0 +1,454 @@
+/**
+ * Node dependencies.
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Internal dependencies.
+ */
+const getIntermediateRepresentation = require( '../get-intermediate-representation' );
+
+describe( 'Intermediate Representation', function() {
+	it( 'undocumented', function() {
+		const token = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-undocumented-nocomments/exports.json' ),
+			'utf-8'
+		);
+		const ir = getIntermediateRepresentation( null, JSON.parse( token ) );
+		expect( ir ).toHaveLength( 1 );
+		expect( ir[ 0 ] ).toEqual( {
+			path: null,
+			name: 'default',
+			description: 'Undocumented declaration.',
+			tags: [],
+			lineStart: 3,
+			lineEnd: 3,
+		} );
+		const tokenOneliner = fs.readFileSync(
+			path.join( __dirname, './fixtures/default-undocumented-oneliner/exports.json' ),
+			'utf-8'
+		);
+		const irOneliner = getIntermediateRepresentation( null, JSON.parse( tokenOneliner ) );
+		expect( irOneliner ).toHaveLength( 1 );
+		expect( irOneliner[ 0 ] ).toEqual( {
+			path: null,
+			name: 'default',
+			description: 'Undocumented declaration.',
+			tags: [],
+			lineStart: 2,
+			lineEnd: 2,
+		} );
+	} );
+
+	describe( 'JSDoc in export statement', function() {
+		it( 'default export', function() {
+			const tokenClassAnonymous = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-class-anonymous/exports.json' ),
+				'utf-8'
+			);
+			const irClassAnonymous = getIntermediateRepresentation( null, JSON.parse( tokenClassAnonymous ) );
+			expect( irClassAnonymous ).toHaveLength( 1 );
+			expect( irClassAnonymous[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Class declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenClassNamed = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-class-named/exports.json' ),
+				'utf-8'
+			);
+			const irClassNamed = getIntermediateRepresentation( null, JSON.parse( tokenClassNamed ) );
+			expect( irClassNamed ).toHaveLength( 1 );
+			expect( irClassNamed[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Class declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenFnAnonymous = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-function-anonymous/exports.json' ),
+				'utf-8'
+			);
+			const irFnAnonymous = getIntermediateRepresentation( null, JSON.parse( tokenFnAnonymous ) );
+			expect( irFnAnonymous ).toHaveLength( 1 );
+			expect( irFnAnonymous[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Function declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenFnNamed = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-function-named/exports.json' ),
+				'utf-8'
+			);
+			const irFnNamed = getIntermediateRepresentation( null, JSON.parse( tokenFnNamed ) );
+			expect( irFnNamed[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Function declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenVariable = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-variable/exports.json' ),
+				'utf-8'
+			);
+			const irVar = getIntermediateRepresentation( null, JSON.parse( tokenVariable ) );
+			expect( irVar[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Variable declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+		} );
+		it( 'named export', function() {
+			const tokenClass = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-class/exports.json' ),
+				'utf-8'
+			);
+			const irNamedClass = getIntermediateRepresentation( null, JSON.parse( tokenClass ) );
+			expect( irNamedClass ).toHaveLength( 1 );
+			expect( irNamedClass[ 0 ] ).toEqual( {
+				path: null,
+				name: 'MyDeclaration',
+				description: 'My declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenFn = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-function/exports.json' ),
+				'utf-8'
+			);
+			const irNamedFn = getIntermediateRepresentation( null, JSON.parse( tokenFn ) );
+			expect( irNamedFn ).toHaveLength( 1 );
+			expect( irNamedFn[ 0 ] ).toEqual( {
+				path: null,
+				name: 'myDeclaration',
+				description: 'My declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenVariable = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-variable/exports.json' ),
+				'utf-8'
+			);
+			const irNamedVar = getIntermediateRepresentation( null, JSON.parse( tokenVariable ) );
+			expect( irNamedVar ).toHaveLength( 1 );
+			expect( irNamedVar[ 0 ] ).toEqual( {
+				path: null,
+				name: 'myDeclaration',
+				description: 'My declaration example.',
+				tags: [],
+				lineStart: 4,
+				lineEnd: 4,
+			} );
+			const tokenVariables = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-variables/exports.json' ),
+				'utf-8'
+			);
+			const irNamedVars = getIntermediateRepresentation( null, JSON.parse( tokenVariables ) );
+			expect( irNamedVars ).toHaveLength( 2 );
+			expect( irNamedVars[ 0 ] ).toEqual(
+				{ path: null, name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
+			);
+			expect( irNamedVars[ 1 ] ).toEqual(
+				{ path: null, name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
+			);
+		} );
+	} );
+
+	describe( 'JSDoc in same file', function() {
+		it( 'default export', function() {
+			const token = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-identifier/exports.json' ),
+				'utf-8'
+			);
+			const ast = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-identifier/ast.json' ),
+				'utf-8'
+			);
+			const irDefaultId = getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) );
+			expect( irDefaultId ).toHaveLength( 1 );
+			expect( irDefaultId[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Class declaration example.',
+				tags: [],
+				lineStart: 6,
+				lineEnd: 6,
+			} );
+			const namedExport = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-named-export/exports.json' ),
+				'utf-8'
+			);
+			const namedExportAST = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-named-export/ast.json' ),
+				'utf-8'
+			);
+			const irDefaultNamed0 = getIntermediateRepresentation( null, JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) );
+			expect( irDefaultNamed0 ).toHaveLength( 1 );
+			expect( irDefaultNamed0[ 0 ] ).toEqual(
+				{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 }
+			);
+			const irDefaultNamed1 = getIntermediateRepresentation( null, JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) );
+			expect( irDefaultNamed1[ 0 ] ).toEqual(
+				{ path: null, name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 }
+			);
+		} );
+
+		it( 'named export', function() {
+			const token = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifier/exports.json' ),
+				'utf-8'
+			);
+			const ast = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifier/ast.json' ),
+				'utf-8'
+			);
+			const irNamedId = getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) );
+			expect( irNamedId ).toHaveLength( 1 );
+			expect( irNamedId[ 0 ] ).toEqual( {
+				path: null,
+				name: 'myDeclaration',
+				description: 'My declaration example.',
+				tags: [],
+				lineStart: 6,
+				lineEnd: 6,
+			} );
+			const tokenObject = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifier-destructuring/exports.json' ),
+				'utf-8'
+			);
+			const astObject = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifier-destructuring/ast.json' ),
+				'utf-8'
+			);
+			const irNamedIdDestructuring = getIntermediateRepresentation( null, JSON.parse( tokenObject ), JSON.parse( astObject ) );
+			expect( irNamedIdDestructuring ).toHaveLength( 1 );
+			expect( irNamedIdDestructuring[ 0 ] ).toEqual( {
+				path: null,
+				name: 'myDeclaration',
+				description: 'My declaration example.',
+				tags: [],
+				lineStart: 6,
+				lineEnd: 6,
+			} );
+			const tokens = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifiers/exports.json' ),
+				'utf-8'
+			);
+			const asts = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifiers/ast.json' ),
+				'utf-8'
+			);
+			const irIds = getIntermediateRepresentation( null, JSON.parse( tokens ), JSON.parse( asts ) );
+			expect( irIds ).toHaveLength( 3 );
+			expect( irIds[ 0 ] ).toEqual(
+				{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 }
+			);
+			expect( irIds[ 1 ] ).toEqual(
+				{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 }
+			);
+			expect( irIds[ 2 ] ).toEqual(
+				{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 }
+			);
+			const foo = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifiers-and-inline/exports.json' ),
+				'utf-8'
+			);
+			const bar = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifiers-and-inline/ast.json' ),
+				'utf-8'
+			);
+			const irIdInline0 = getIntermediateRepresentation( null, JSON.parse( foo )[ 0 ], JSON.parse( bar ) );
+			expect( irIdInline0 ).toHaveLength( 2 );
+			expect( irIdInline0[ 0 ] ).toEqual(
+				{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 }
+			);
+			expect( irIdInline0[ 1 ] ).toEqual(
+				{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 }
+			);
+			const irIdInline1 = getIntermediateRepresentation( null, JSON.parse( foo )[ 1 ], JSON.parse( bar ) );
+			expect( irIdInline1[ 0 ] ).toEqual(
+				{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 }
+			);
+		} );
+	} );
+
+	describe( 'JSDoc in module dependency', function() {
+		it( 'named export', function() {
+			const tokenImportNamed = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-import-named/exports.json' ),
+				'utf-8'
+			);
+			const getModuleImportNamed = () => JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/named-identifiers/ir.json' ),
+				'utf-8'
+			) );
+			const ir = getIntermediateRepresentation( null, JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed );
+			expect( ir ).toHaveLength( 3 );
+			expect( ir[ 0 ] ).toEqual(
+				{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 }
+			);
+			expect( ir[ 1 ] ).toEqual(
+				{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 }
+			);
+			expect( ir[ 2 ] ).toEqual(
+				{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 }
+
+			);
+		} );
+
+		it( 'named default export', function() {
+			const tokenDefault = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-default/exports.json' ),
+				'utf-8'
+			);
+			const getModule = () => JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/named-default/module-ir.json' ),
+				'utf-8'
+			) );
+			const irNamedDefault = getIntermediateRepresentation( null, JSON.parse( tokenDefault ), { body: [] }, getModule );
+			expect( irNamedDefault ).toHaveLength( 1 );
+			expect( irNamedDefault[ 0 ] ).toEqual(
+				{ path: null, name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 }
+			);
+			const tokenDefaultExported = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-default-exported/exports.json' ),
+				'utf-8'
+			);
+			const irNamedDefaultExported = getIntermediateRepresentation( null, JSON.parse( tokenDefaultExported ), { body: [] }, getModule );
+			expect( irNamedDefaultExported ).toHaveLength( 1 );
+			expect( irNamedDefaultExported[ 0 ] ).toEqual(
+				{ path: null, name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 }
+			);
+		} );
+
+		it( 'namespace export', function() {
+			const token = fs.readFileSync(
+				path.join( __dirname, './fixtures/namespace/exports.json' ),
+				'utf-8'
+			);
+			const getModule = () => JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/namespace/module-ir.json' ),
+				'utf-8'
+			) );
+			const irNamespace = getIntermediateRepresentation( null, JSON.parse( token ), { body: [] }, getModule );
+			expect( irNamespace ).toHaveLength( 3 );
+			expect( irNamespace[ 0 ] ).toEqual(
+				{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 }
+			);
+			expect( irNamespace[ 1 ] ).toEqual(
+				{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 }
+			);
+			expect( irNamespace[ 2 ] ).toEqual(
+				{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 }
+			);
+			const tokenCommented = fs.readFileSync(
+				path.join( __dirname, './fixtures/namespace-commented/exports.json' ),
+				'utf-8'
+			);
+			const irNamespaceCommented = getIntermediateRepresentation( null, JSON.parse( tokenCommented ), { body: [] }, getModule );
+			expect( irNamespaceCommented ).toHaveLength( 3 );
+			expect( irNamespaceCommented[ 0 ] ).toEqual(
+				{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 }
+			);
+			expect( irNamespaceCommented[ 1 ] ).toEqual(
+				{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 }
+			);
+			expect( irNamespaceCommented[ 2 ] ).toEqual(
+				{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 }
+			);
+		} );
+	} );
+
+	describe( 'JSDoc in module dependency through import', function() {
+		it( 'default export', function() {
+			const tokenDefault = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-default/exports.json' ),
+				'utf-8'
+			);
+			const astDefault = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-default/ast.json' ),
+				'utf-8'
+			);
+			const getModuleDefault = () => JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-default/module-ir.json' ),
+				'utf-8'
+			) );
+			const irDefault = getIntermediateRepresentation( null, JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault );
+			expect( irDefault ).toHaveLength( 1 );
+			expect( irDefault[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Function declaration.',
+				tags: [],
+				lineStart: 3,
+				lineEnd: 3,
+			} );
+			const tokenNamed = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-named/exports.json' ),
+				'utf-8'
+			);
+			const astNamed = fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-named/ast.json' ),
+				'utf-8'
+			);
+			const getModuleNamed = () => JSON.parse( fs.readFileSync(
+				path.join( __dirname, './fixtures/default-import-named/module-ir.json' ),
+				'utf-8'
+			) );
+			const irNamed = getIntermediateRepresentation( null, JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed );
+			expect( irNamed ).toHaveLength( 1 );
+			expect( irNamed[ 0 ] ).toEqual( {
+				path: null,
+				name: 'default',
+				description: 'Function declaration.',
+				tags: [],
+				lineStart: 3,
+				lineEnd: 3,
+			} );
+		} );
+
+		it( 'named export', function() {
+			const tokenImportNamespace = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-import-namespace/exports.json' ),
+				'utf-8'
+			);
+			const astImportNamespace = fs.readFileSync(
+				path.join( __dirname, './fixtures/named-import-namespace/ast.json' ),
+				'utf-8'
+			);
+			const getModuleImportNamespace = ( filePath ) => {
+				if ( filePath === './named-import-namespace-module' ) {
+					return JSON.parse( fs.readFileSync(
+						path.join( __dirname, './fixtures/named-import-namespace/module-ir.json' ),
+						'utf-8'
+					) );
+				}
+				return JSON.parse( fs.readFileSync(
+					path.join( __dirname, './fixtures/default-function/ir.json' ),
+					'utf-8'
+				) );
+			};
+			const ir = getIntermediateRepresentation( null, JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace );
+			expect( ir ).toHaveLength( 1 );
+			expect( ir[ 0 ] ).toEqual(
+				{ path: null, name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 }
+			);
+		} );
+	} );
+} );
diff --git a/packages/docgen/tests/test-get-intermediate-representation.js b/packages/docgen/tests/test-get-intermediate-representation.js
deleted file mode 100644
index 376035a305ba4c..00000000000000
--- a/packages/docgen/tests/test-get-intermediate-representation.js
+++ /dev/null
@@ -1,410 +0,0 @@
-/**
- * Node dependencies.
- */
-const fs = require( 'fs' );
-const path = require( 'path' );
-
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const getIntermediateRepresentation = require( '../src/get-intermediate-representation' );
-
-test( 'IR - undocumented', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-undocumented-nocomments.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Undocumented declaration.',
-		tags: [],
-		lineStart: 3,
-		lineEnd: 3,
-	} ] );
-	const tokenOneliner = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-undocumented-oneliner.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenOneliner ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Undocumented declaration.',
-		tags: [],
-		lineStart: 2,
-		lineEnd: 2,
-	} ] );
-	t.end();
-} );
-
-test( 'IR - JSDoc in export statement (default export)', function( t ) {
-	const tokenClassAnonymous = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-anonymous.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClassAnonymous ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Class declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenClassNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-class-named.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClassNamed ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Class declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenFnAnonymous = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-anonymous.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFnAnonymous ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Function declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenFnNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-function-named.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFnNamed ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Function declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenVariable = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-variable.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Variable declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	t.end();
-} );
-
-test( 'IR - JSDoc in export statement (named export)', function( t ) {
-	const tokenClass = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-class.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenClass ) ), [ {
-		path: null,
-		name: 'MyDeclaration',
-		description: 'My declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenFn = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-function.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenFn ) ), [ {
-		path: null,
-		name: 'myDeclaration',
-		description: 'My declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenVariable = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variable.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariable ) ), [ {
-		path: null,
-		name: 'myDeclaration',
-		description: 'My declaration example.',
-		tags: [],
-		lineStart: 4,
-		lineEnd: 4,
-	} ] );
-	const tokenVariables = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-variables.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenVariables ) ), [
-		{ path: null, name: 'firstDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
-		{ path: null, name: 'secondDeclaration', description: 'My declaration example.', tags: [], lineStart: 4, lineEnd: 5 },
-	] );
-	t.end();
-} );
-
-test( 'IR - JSDoc in same file (default export)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier.json' ),
-		'utf-8'
-	);
-	const ast = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-identifier-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ), [ {
-		path: null,
-		name: 'default',
-		description: 'Class declaration example.',
-		tags: [],
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	const namedExport = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-named-export.json' ),
-		'utf-8'
-	);
-	const namedExportAST = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-named-export-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( namedExport )[ 0 ], JSON.parse( namedExportAST ) ),
-		[ { path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 4, lineEnd: 4 } ]
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( namedExport )[ 1 ], JSON.parse( namedExportAST ) ),
-		[ { path: null, name: 'default', description: 'Function declaration example.', tags: [], lineStart: 6, lineEnd: 6 } ]
-	);
-	t.end();
-} );
-
-test( 'IR - JSDoc in same file (named export)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier.json' ),
-		'utf-8'
-	);
-	const ast = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( token ), JSON.parse( ast ) ), [ {
-		path: null,
-		name: 'myDeclaration',
-		description: 'My declaration example.',
-		tags: [],
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	const tokenObject = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-destructuring.json' ),
-		'utf-8'
-	);
-	const astObject = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifier-destructuring-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokenObject ), JSON.parse( astObject ) ), [ {
-		path: null,
-		name: 'myDeclaration',
-		description: 'My declaration example.',
-		tags: [],
-		lineStart: 6,
-		lineEnd: 6,
-	} ] );
-	const tokens = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers.json' ),
-		'utf-8'
-	);
-	const asts = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( tokens ), JSON.parse( asts ) ), [
-		{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-		{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-		{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-	] );
-	const foo = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers-and-inline.json' ),
-		'utf-8'
-	);
-	const bar = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers-and-inline-ast.json' ),
-		'utf-8'
-	);
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( foo )[ 0 ], JSON.parse( bar ) ), [
-		{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
-		{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 11, lineEnd: 11 },
-	] );
-	t.deepEqual( getIntermediateRepresentation( null, JSON.parse( foo )[ 1 ], JSON.parse( bar ) ), [
-		{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 16, lineEnd: 16 },
-	] );
-	t.end();
-} );
-
-test( 'IR - JSDoc in module dependency (named export)', function( t ) {
-	const tokenImportNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-named.json' ),
-		'utf-8'
-	);
-	const getModuleImportNamed = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/named-identifiers-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenImportNamed ), { body: [] }, getModuleImportNamed ),
-		[
-			{ path: null, name: 'functionDeclaration', description: 'Function declaration example.', tags: [], lineStart: 2, lineEnd: 2 },
-			{ path: null, name: 'variableDeclaration', description: 'Variable declaration example.', tags: [], lineStart: 3, lineEnd: 3 },
-			{ path: null, name: 'ClassDeclaration', description: 'Class declaration example.', tags: [], lineStart: 4, lineEnd: 4 },
-		]
-	);
-	t.end();
-} );
-
-test( 'IR - JSDoc in module dependency (named default export)', function( t ) {
-	const tokenDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default.json' ),
-		'utf-8'
-	);
-	const getModule = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenDefault ), { body: [] }, getModule ),
-		[ { path: null, name: 'default', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
-	);
-	const tokenDefaultExported = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-default-exported.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenDefaultExported ), { body: [] }, getModule ),
-		[ { path: null, name: 'moduleName', description: 'Module declaration.', tags: [], lineStart: 1, lineEnd: 1 } ]
-	);
-
-	t.end();
-} );
-
-test( 'IR - JSDoc in module dependency (namespace export)', function( t ) {
-	const token = fs.readFileSync(
-		path.join( __dirname, './fixtures/namespace.json' ),
-		'utf-8'
-	);
-	const getModule = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/namespace-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( token ), { body: [] }, getModule ),
-		[
-			{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 1, lineEnd: 1 },
-			{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 1, lineEnd: 1 },
-			{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 1, lineEnd: 1 },
-		]
-	);
-	const tokenCommented = fs.readFileSync(
-		path.join( __dirname, './fixtures/namespace-commented.json' ),
-		'utf-8'
-	);
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenCommented ), { body: [] }, getModule ),
-		[
-			{ path: null, name: 'MyClass', description: 'Named class.', tags: [], lineStart: 4, lineEnd: 4 },
-			{ path: null, name: 'myFunction', description: 'Named function.', tags: [], lineStart: 4, lineEnd: 4 },
-			{ path: null, name: 'myVariable', description: 'Named variable.', tags: [], lineStart: 4, lineEnd: 4 },
-		]
-	);
-	t.end();
-} );
-
-test( 'IR - JSDoc in module dependency through import (default export)', function( t ) {
-	const tokenDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default.json' ),
-		'utf-8'
-	);
-	const astDefault = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default-ast.json' ),
-		'utf-8'
-	);
-	const getModuleDefault = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-default-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenDefault ), JSON.parse( astDefault ), getModuleDefault ),
-		[ {
-			path: null,
-			name: 'default',
-			description: 'Function declaration.',
-			tags: [],
-			lineStart: 3,
-			lineEnd: 3,
-		} ]
-	);
-	const tokenNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named.json' ),
-		'utf-8'
-	);
-	const astNamed = fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named-ast.json' ),
-		'utf-8'
-	);
-	const getModuleNamed = () => JSON.parse( fs.readFileSync(
-		path.join( __dirname, './fixtures/default-import-named-module-ir.json' ),
-		'utf-8'
-	) );
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenNamed ), JSON.parse( astNamed ), getModuleNamed ),
-		[ {
-			path: null,
-			name: 'default',
-			description: 'Function declaration.',
-			tags: [],
-			lineStart: 3,
-			lineEnd: 3,
-		} ]
-	);
-	t.end();
-} );
-
-test( 'IR - JSDoc in module dependency through import (named export)', function( t ) {
-	const tokenImportNamespace = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-namespace.json' ),
-		'utf-8'
-	);
-	const astImportNamespace = fs.readFileSync(
-		path.join( __dirname, './fixtures/named-import-namespace-ast.json' ),
-		'utf-8'
-	);
-	const getModuleImportNamespace = ( filePath ) => {
-		if ( filePath === './named-import-namespace-module' ) {
-			return JSON.parse( fs.readFileSync(
-				path.join( __dirname, './fixtures/named-import-namespace-module-ir.json' ),
-				'utf-8'
-			) );
-		}
-		return JSON.parse( fs.readFileSync(
-			path.join( __dirname, './fixtures/default-function-ir.json' ),
-			'utf-8'
-		) );
-	};
-	t.deepEqual(
-		getIntermediateRepresentation( null, JSON.parse( tokenImportNamespace ), JSON.parse( astImportNamespace ), getModuleImportNamespace ),
-		[ { path: null, name: 'variables', description: 'Undocumented declaration.', tags: [], lineStart: 3, lineEnd: 3 } ]
-	);
-	t.end();
-} );

From 7e68a46d70e7a79036faae4f70027c54556c86b3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 10:59:36 +0100
Subject: [PATCH 197/213] Migrate Markdown formatter tests to jest

---
 packages/docgen/TODO.md                       |  6 ++-
 .../docgen/src/test/formatter-markdown.js     | 33 ++++++++++++++++
 .../docgen/tests/test-formatter-markdown.js   | 38 -------------------
 3 files changed, 37 insertions(+), 40 deletions(-)
 create mode 100644 packages/docgen/src/test/formatter-markdown.js
 delete mode 100644 packages/docgen/tests/test-formatter-markdown.js

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 9c6bc144b2f702..77675506479d9a 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,5 +1,7 @@
 # TODO
 
-- [ ] Chore: register the package with lerna.
-- [ ] Chore: make a command available in the Gutenberg repo.
+- [ ] Chore: make docgen play nicely with lerna?
+  - [ ] Install dependencies?
+  - [ ] Command across packages to build docs?
+- [ ] Chore: use tokens in README?
 - [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js
new file mode 100644
index 00000000000000..1370185b19f722
--- /dev/null
+++ b/packages/docgen/src/test/formatter-markdown.js
@@ -0,0 +1,33 @@
+/**
+ * Internal dependencies.
+ */
+const formatter = require( '../markdown/formatter' );
+
+describe( 'Formatter', () => {
+	it( 'returns markdown', () => {
+		const docPath = process.cwd();
+		const docs = formatter( docPath, docPath + '-api.md', [ {
+			path: docPath + '-code.js',
+			description: 'My declaration example.',
+			tags: [
+				{
+					title: 'param',
+					description: 'First declaration parameter.',
+					type: 'number',
+					name: 'firstParam',
+				},
+				{
+					title: 'return',
+					description: 'The result of the declaration.',
+					type: 'number',
+				},
+			],
+			name: 'myDeclaration',
+			lineStart: 1,
+			lineEnd: 2,
+		} ], 'API docs' );
+		expect( docs ).toBe(
+			'# API docs\n\n## myDeclaration\n\n[gutenberg/home/andres/src/gutenberg-code.js#L1-L2](gutenberg/home/andres/src/gutenberg-code.js#L1-L2)\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'
+		);
+	} );
+} );
diff --git a/packages/docgen/tests/test-formatter-markdown.js b/packages/docgen/tests/test-formatter-markdown.js
deleted file mode 100644
index 15e0c67b8fb6b6..00000000000000
--- a/packages/docgen/tests/test-formatter-markdown.js
+++ /dev/null
@@ -1,38 +0,0 @@
-/**
- * External dependencies.
- */
-const test = require( 'tape' );
-
-/**
- * Internal dependencies.
- */
-const formatter = require( '../src/markdown/formatter' );
-
-test( 'Formatter - returns markdown', ( t ) => {
-	const docPath = process.cwd();
-	const docs = formatter( docPath, docPath + '-api.md', [ {
-		path: docPath + '-code.js',
-		description: 'My declaration example.',
-		tags: [
-			{
-				title: 'param',
-				description: 'First declaration parameter.',
-				type: 'number',
-				name: 'firstParam',
-			},
-			{
-				title: 'return',
-				description: 'The result of the declaration.',
-				type: 'number',
-			},
-		],
-		name: 'myDeclaration',
-		lineStart: 1,
-		lineEnd: 2,
-	} ], 'API docs' );
-	t.equal(
-		docs,
-		'# API docs\n\n## myDeclaration\n\n[docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2](docgen/home/andres/src/gutenberg/packages/docgen-code.js#L1-L2)\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'
-	);
-	t.end();
-} );

From 71a64d6fe784f7616d884fe0e7597be68899ce02 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 12:18:03 +0100
Subject: [PATCH 198/213] Extract bin/cli utility

---
 packages/docgen/bin/cli.js   |  38 +++++++++
 packages/docgen/package.json |   2 +-
 packages/docgen/src/cli.js   | 161 -----------------------------------
 packages/docgen/src/index.js | 126 +++++++++++++++++++++++++++
 4 files changed, 165 insertions(+), 162 deletions(-)
 create mode 100755 packages/docgen/bin/cli.js
 delete mode 100755 packages/docgen/src/cli.js
 create mode 100644 packages/docgen/src/index.js

diff --git a/packages/docgen/bin/cli.js b/packages/docgen/bin/cli.js
new file mode 100755
index 00000000000000..f5bdb94f55b859
--- /dev/null
+++ b/packages/docgen/bin/cli.js
@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const docgen = require( '../src' );
+
+const optionator = require( 'optionator' )( {
+	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
+	options: [ {
+		option: 'formatter',
+		type: 'String',
+		description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.',
+	}, {
+		option: 'output',
+		type: 'String',
+		description: 'Output file to contain the API documentation.',
+	}, {
+		option: 'ignore',
+		type: 'RegExp',
+		description: 'A regular expression used to ignore symbols whose name match it.',
+	}, {
+		option: 'to-section',
+		type: 'String',
+		description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
+	}, {
+		option: 'to-token',
+		type: 'Boolean',
+		description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.',
+		dependsOn: 'output',
+	}, {
+		option: 'debug',
+		type: 'Boolean',
+		default: false,
+		description: 'Run in debug mode, which outputs some intermediate files useful for debugging.',
+	} ],
+} );
+
+const options = optionator.parseArgv( process.argv );
+docgen( options._[ 0 ], options );
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index f4072531adf29d..df396e316803cf 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -18,7 +18,7 @@
 		"url": "https://github.com/WordPress/gutenberg/issues"
 	},
 	"bin": {
-		"docgen": "./src/cli.js"
+		"docgen": "./bin/cli.js"
 	},
 	"dependencies": {
 		"optionator": "0.8.2"
diff --git a/packages/docgen/src/cli.js b/packages/docgen/src/cli.js
deleted file mode 100755
index 7a79e66159c82c..00000000000000
--- a/packages/docgen/src/cli.js
+++ /dev/null
@@ -1,161 +0,0 @@
-/**
- * External dependencies
- */
-const fs = require( 'fs' );
-const path = require( 'path' );
-const { last } = require( 'lodash' );
-
-/**
- * Internal dependencies
- */
-const engine = require( './engine' );
-const defaultMarkdownFormatter = require( './markdown' );
-
-/**
- * Helpers functions.
- */
-
-const relativeToAbsolute = ( basePath, relativePath ) => {
-	const target = path.join( path.dirname( basePath ), relativePath );
-	if ( path.extname( target ) === '.js' ) {
-		return target;
-	}
-	let targetFile = target + '.js';
-	if ( fs.existsSync( targetFile ) ) {
-		return targetFile;
-	}
-	targetFile = path.join( target, 'index.js' );
-	if ( fs.existsSync( targetFile ) ) {
-		return targetFile;
-	}
-	process.stdout.write( '\nRelative path does not exists.' );
-	process.stdout.write( '\n' );
-	process.stdout.write( `\nBase: ${ basePath }` );
-	process.stdout.write( `\nRelative: ${ relativePath }` );
-	process.stdout.write( '\n\n' );
-	process.exit( 1 );
-};
-
-const getIRFromRelativePath = ( rootDir, basePath ) => ( relativePath ) => {
-	if ( ! relativePath.startsWith( '.' ) ) {
-		return [];
-	}
-	const absolutePath = relativeToAbsolute( basePath, relativePath );
-	const result = processFile( rootDir, absolutePath );
-	return result.ir || undefined;
-};
-
-const processFile = ( rootDir, inputFile ) => {
-	try {
-		const data = fs.readFileSync( inputFile, 'utf8' );
-		currentFileStack.push( inputFile );
-		const relativePath = path.relative( rootDir, inputFile );
-		const result = engine( relativePath, data, getIRFromRelativePath( rootDir, last( currentFileStack ) ) );
-		currentFileStack.pop( inputFile );
-		return result;
-	} catch ( e ) {
-		process.stdout.write( `\n${ e }` );
-		process.stdout.write( '\n\n' );
-		process.exit( 1 );
-	}
-};
-
-const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, headingTitle ) => {
-	try {
-		const customFormatter = require( customFormatterFile );
-		const output = customFormatter( rootDir, doc, symbols, headingTitle );
-		fs.writeFileSync( doc, output );
-	} catch ( e ) {
-		process.stdout.write( `\n${ e }` );
-		process.stdout.write( '\n\n' );
-		process.exit( 1 );
-	}
-	return 'custom formatter';
-};
-
-/**
- * Start up processing.
- */
-
-const optionator = require( 'optionator' )( {
-	prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>',
-	options: [ {
-		option: 'formatter',
-		type: 'String',
-		description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.',
-	}, {
-		option: 'output',
-		type: 'String',
-		description: 'Output file to contain the API documentation.',
-	}, {
-		option: 'ignore',
-		type: 'RegExp',
-		description: 'A regular expression used to ignore symbols whose name match it.',
-	}, {
-		option: 'to-section',
-		type: 'String',
-		description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.',
-		dependsOn: 'output',
-	}, {
-		option: 'to-token',
-		type: 'Boolean',
-		description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.',
-		dependsOn: 'output',
-	}, {
-		option: 'debug',
-		type: 'Boolean',
-		default: false,
-		description: 'Run in debug mode, which outputs some intermediate files useful for debugging.',
-	} ],
-} );
-
-const options = optionator.parseArgv( process.argv );
-
-// Input: process CLI args, prepare files, etc
-const processDir = process.cwd();
-let sourceFile = options._[ 0 ];
-if ( sourceFile === undefined ) {
-	process.stdout.write( '\n' );
-	process.stdout.write( optionator.generateHelp() );
-	process.stdout.write( '\n\n' );
-	process.exit( 1 );
-}
-sourceFile = path.join( processDir, sourceFile );
-
-const debugMode = options.debug ? true : false;
-
-const inputBase = path.join(
-	path.dirname( sourceFile ),
-	path.basename( sourceFile, path.extname( sourceFile ) )
-);
-const ast = inputBase + '-ast.json';
-const tokens = inputBase + '-exports.json';
-const ir = inputBase + '-ir.json';
-const doc = options.output ?
-	path.join( processDir, options.output ) :
-	inputBase + '-api.md';
-
-// Process
-const currentFileStack = []; // To keep track of file being processed.
-const result = processFile( processDir, sourceFile );
-const filteredIr = result.ir.filter( ( { name } ) => options.ignore ? ! name.match( options.ignore ) : true );
-
-// Ouput
-if ( result === undefined ) {
-	process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' );
-	process.stdout.write( `\n${ sourceFile }` );
-	process.stdout.write( '\n\n' );
-	process.exit( 0 );
-}
-
-if ( options.formatter ) {
-	runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' );
-} else {
-	defaultMarkdownFormatter( options, processDir, doc, filteredIr, 'API' );
-}
-
-if ( debugMode ) {
-	fs.writeFileSync( ir, JSON.stringify( result.ir ) );
-	fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
-	fs.writeFileSync( ast, JSON.stringify( result.ast ) );
-}
diff --git a/packages/docgen/src/index.js b/packages/docgen/src/index.js
new file mode 100644
index 00000000000000..1bc2e71a37897a
--- /dev/null
+++ b/packages/docgen/src/index.js
@@ -0,0 +1,126 @@
+/**
+ * External dependencies
+ */
+const fs = require( 'fs' );
+const path = require( 'path' );
+const { last } = require( 'lodash' );
+
+/**
+ * Internal dependencies
+ */
+const engine = require( './engine' );
+const defaultMarkdownFormatter = require( './markdown' );
+
+/**
+ * Helpers functions.
+ */
+
+const relativeToAbsolute = ( basePath, relativePath ) => {
+	const target = path.join( path.dirname( basePath ), relativePath );
+	if ( path.extname( target ) === '.js' ) {
+		return target;
+	}
+	let targetFile = target + '.js';
+	if ( fs.existsSync( targetFile ) ) {
+		return targetFile;
+	}
+	targetFile = path.join( target, 'index.js' );
+	if ( fs.existsSync( targetFile ) ) {
+		return targetFile;
+	}
+	process.stdout.write( '\nRelative path does not exists.' );
+	process.stdout.write( '\n' );
+	process.stdout.write( `\nBase: ${ basePath }` );
+	process.stdout.write( `\nRelative: ${ relativePath }` );
+	process.stdout.write( '\n\n' );
+	process.exit( 1 );
+};
+
+const getIRFromRelativePath = ( rootDir, basePath ) => ( relativePath ) => {
+	if ( ! relativePath.startsWith( '.' ) ) {
+		return [];
+	}
+	const absolutePath = relativeToAbsolute( basePath, relativePath );
+	const result = processFile( rootDir, absolutePath );
+	return result.ir || undefined;
+};
+
+const processFile = ( rootDir, inputFile ) => {
+	try {
+		const data = fs.readFileSync( inputFile, 'utf8' );
+		currentFileStack.push( inputFile );
+		const relativePath = path.relative( rootDir, inputFile );
+		const result = engine( relativePath, data, getIRFromRelativePath( rootDir, last( currentFileStack ) ) );
+		currentFileStack.pop( inputFile );
+		return result;
+	} catch ( e ) {
+		process.stdout.write( `\n${ e }` );
+		process.stdout.write( '\n\n' );
+		process.exit( 1 );
+	}
+};
+
+const runCustomFormatter = ( customFormatterFile, rootDir, doc, symbols, headingTitle ) => {
+	try {
+		const customFormatter = require( customFormatterFile );
+		const output = customFormatter( rootDir, doc, symbols, headingTitle );
+		fs.writeFileSync( doc, output );
+	} catch ( e ) {
+		process.stdout.write( `\n${ e }` );
+		process.stdout.write( '\n\n' );
+		process.exit( 1 );
+	}
+	return 'custom formatter';
+};
+
+// To keep track of file being processed.
+const currentFileStack = [];
+
+module.exports = function( sourceFile, options ) {
+	// Input: process CLI args, prepare files, etc
+	const processDir = process.cwd();
+	if ( sourceFile === undefined ) {
+		process.stdout.write( '\n' );
+		process.stdout.write( 'No source file provided' );
+		process.stdout.write( '\n\n' );
+		process.exit( 1 );
+	}
+	sourceFile = path.join( processDir, sourceFile );
+
+	const debugMode = options.debug ? true : false;
+
+	const inputBase = path.join(
+		path.dirname( sourceFile ),
+		path.basename( sourceFile, path.extname( sourceFile ) )
+	);
+	const ast = inputBase + '-ast.json';
+	const tokens = inputBase + '-exports.json';
+	const ir = inputBase + '-ir.json';
+	const doc = options.output ?
+		path.join( processDir, options.output ) :
+		inputBase + '-api.md';
+
+	// Process
+	const result = processFile( processDir, sourceFile );
+	const filteredIr = result.ir.filter( ( { name } ) => options.ignore ? ! name.match( options.ignore ) : true );
+
+	// Ouput
+	if ( result === undefined ) {
+		process.stdout.write( '\nFile was processed, but contained no ES6 module exports:' );
+		process.stdout.write( `\n${ sourceFile }` );
+		process.stdout.write( '\n\n' );
+		process.exit( 0 );
+	}
+
+	if ( options.formatter ) {
+		runCustomFormatter( path.join( processDir, options.formatter ), processDir, doc, filteredIr, 'API' );
+	} else {
+		defaultMarkdownFormatter( options, processDir, doc, filteredIr, 'API' );
+	}
+
+	if ( debugMode ) {
+		fs.writeFileSync( ir, JSON.stringify( result.ir ) );
+		fs.writeFileSync( tokens, JSON.stringify( result.tokens ) );
+		fs.writeFileSync( ast, JSON.stringify( result.ast ) );
+	}
+};

From 95239cbe1552709457d8555ceafb98bc5151b273 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 12:37:42 +0100
Subject: [PATCH 199/213] Uninstall no longer needed dev deps

---
 packages/docgen/package.json | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index df396e316803cf..5693dc222b98e0 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -24,23 +24,12 @@
 		"optionator": "0.8.2"
 	},
 	"devDependencies": {
-		"faucet": "0.0.1",
 		"mdast-util-inject": "1.1.0",
 		"remark": "9.0.0",
 		"remark-parse": "6.0.3",
-		"tape": "4.9.2",
 		"unified": "7.1.0"
 	},
 	"publishConfig": {
 		"access": "public"
-	},
-	"scripts": {
-		"test": "tape tests/test-*.js | faucet",
-		"test:engine": "tape tests/test-engine.js | faucet",
-		"test:formatter": "tape tests/test-formatter-markdown.js | faucet",
-		"test:get-export-entries": "tape tests/test-get-export-entries.js | faucet",
-		"test:get-jsdoc-from-token": "tape tests/test-get-jsdoc-from-token.js | faucet",
-		"test:get-intermediate-representation": "tape tests/test-get-intermediate-representation.js | faucet",
-		"test:get-type-as-string": "tape tests/test-get-type-as-string.js | faucet"
 	}
 }

From 94411faa1fc2bed1b78cc3ae0195578fc7dd5ee6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 12:40:05 +0100
Subject: [PATCH 200/213] Fix docgen dependencies

---
 package-lock.json            | 56 +++++++++++++++++++-----------------
 packages/docgen/TODO.md      |  1 -
 packages/docgen/package.json |  6 ++--
 3 files changed, 31 insertions(+), 32 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index f5054836d4ae28..dbd2813a0d8852 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -2705,7 +2705,11 @@
 			"version": "file:packages/docgen",
 			"dev": true,
 			"requires": {
-				"optionator": "0.8.2"
+				"mdast-util-inject": "1.1.0",
+				"optionator": "0.8.2",
+				"remark": "10.0.1",
+				"remark-parse": "6.0.3",
+				"unified": "7.1.0"
 			}
 		},
 		"@wordpress/dom": {
@@ -8705,8 +8709,7 @@
 				"ansi-regex": {
 					"version": "2.1.1",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"aproba": {
 					"version": "1.2.0",
@@ -8734,7 +8737,6 @@
 					"version": "1.1.11",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"balanced-match": "^1.0.0",
 						"concat-map": "0.0.1"
@@ -8749,8 +8751,7 @@
 				"code-point-at": {
 					"version": "1.1.0",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"concat-map": {
 					"version": "0.0.1",
@@ -8761,8 +8762,7 @@
 				"console-control-strings": {
 					"version": "1.1.0",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"core-util-is": {
 					"version": "1.0.2",
@@ -8879,8 +8879,7 @@
 				"inherits": {
 					"version": "2.0.3",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"ini": {
 					"version": "1.3.5",
@@ -8892,7 +8891,6 @@
 					"version": "1.0.0",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"number-is-nan": "^1.0.0"
 					}
@@ -8907,7 +8905,6 @@
 					"version": "3.0.4",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"brace-expansion": "^1.1.7"
 					}
@@ -8915,14 +8912,12 @@
 				"minimist": {
 					"version": "0.0.8",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"minipass": {
 					"version": "2.2.4",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"safe-buffer": "^5.1.1",
 						"yallist": "^3.0.0"
@@ -8941,7 +8936,6 @@
 					"version": "0.5.1",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"minimist": "0.0.8"
 					}
@@ -9022,8 +9016,7 @@
 				"number-is-nan": {
 					"version": "1.0.1",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"object-assign": {
 					"version": "4.1.1",
@@ -9035,7 +9028,6 @@
 					"version": "1.4.0",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"wrappy": "1"
 					}
@@ -9121,8 +9113,7 @@
 				"safe-buffer": {
 					"version": "5.1.1",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"safer-buffer": {
 					"version": "2.1.2",
@@ -9158,7 +9149,6 @@
 					"version": "1.0.2",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"code-point-at": "^1.0.0",
 						"is-fullwidth-code-point": "^1.0.0",
@@ -9178,7 +9168,6 @@
 					"version": "3.0.1",
 					"bundled": true,
 					"dev": true,
-					"optional": true,
 					"requires": {
 						"ansi-regex": "^2.0.0"
 					}
@@ -9222,14 +9211,12 @@
 				"wrappy": {
 					"version": "1.0.2",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				},
 				"yallist": {
 					"version": "3.0.2",
 					"bundled": true,
-					"dev": true,
-					"optional": true
+					"dev": true
 				}
 			}
 		},
@@ -13872,6 +13859,21 @@
 				"unist-util-visit": "^1.1.0"
 			}
 		},
+		"mdast-util-inject": {
+			"version": "1.1.0",
+			"resolved": "https://registry.npmjs.org/mdast-util-inject/-/mdast-util-inject-1.1.0.tgz",
+			"integrity": "sha1-2wa4tYW+lZotzS+H9HK6m3VvNnU=",
+			"dev": true,
+			"requires": {
+				"mdast-util-to-string": "^1.0.0"
+			}
+		},
+		"mdast-util-to-string": {
+			"version": "1.0.5",
+			"resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-1.0.5.tgz",
+			"integrity": "sha512-2qLt/DEOo5F6nc2VFScQiHPzQ0XXcabquRJxKMhKte8nt42o08HUxNDPk7tt0YPxnWjAT11I1SYi0X0iPnfI5A==",
+			"dev": true
+		},
 		"mdn-data": {
 			"version": "1.1.4",
 			"resolved": "https://registry.npmjs.org/mdn-data/-/mdn-data-1.1.4.tgz",
diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 77675506479d9a..8efdc8d836e597 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,7 +1,6 @@
 # TODO
 
 - [ ] Chore: make docgen play nicely with lerna?
-  - [ ] Install dependencies?
   - [ ] Command across packages to build docs?
 - [ ] Chore: use tokens in README?
 - [ ] See [coverage](coverage.md#TODO)
diff --git a/packages/docgen/package.json b/packages/docgen/package.json
index 5693dc222b98e0..a73ed098f3142b 100644
--- a/packages/docgen/package.json
+++ b/packages/docgen/package.json
@@ -21,11 +21,9 @@
 		"docgen": "./bin/cli.js"
 	},
 	"dependencies": {
-		"optionator": "0.8.2"
-	},
-	"devDependencies": {
 		"mdast-util-inject": "1.1.0",
-		"remark": "9.0.0",
+		"optionator": "0.8.2",
+		"remark": "10.0.1",
 		"remark-parse": "6.0.3",
 		"unified": "7.1.0"
 	},

From 1f617be9a36f8296a6885e8bf8c60b0e5d294192 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 12:48:18 +0100
Subject: [PATCH 201/213] Add command to generate docs

- Add command for e2e-test-utils
- Add command in top-level package.json as to simplify executing
  across packages without lerna knowledge.
---
 package.json                         |  1 +
 packages/docgen/TODO.md              |  5 +-
 packages/e2e-test-utils/README.md    | 87 +++++++++++++++++-----------
 packages/e2e-test-utils/package.json |  6 ++
 4 files changed, 61 insertions(+), 38 deletions(-)

diff --git a/package.json b/package.json
index 3185071be7171c..b0965325aa435e 100644
--- a/package.json
+++ b/package.json
@@ -162,6 +162,7 @@
 		"dev": "npm run build:packages && concurrently \"wp-scripts start\" \"npm run dev:packages\"",
 		"dev:packages": "node ./bin/packages/watch.js",
 		"docs:build": "node docs/tool",
+		"docs:generate": "lerna run docs:generate",
 		"fixtures:clean": "rimraf \"packages/e2e-tests/fixtures/blocks/*.+(json|serialized.html)\"",
 		"fixtures:server-registered": "docker-compose run -w /var/www/html/wp-content/plugins/gutenberg --rm wordpress ./bin/get-server-blocks.php > test/integration/full-content/server-registered.json",
 		"fixtures:generate": "npm run fixtures:server-registered && cross-env GENERATE_MISSING_FIXTURES=y npm run test-unit",
diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
index 8efdc8d836e597..62ec867f9d5004 100644
--- a/packages/docgen/TODO.md
+++ b/packages/docgen/TODO.md
@@ -1,6 +1,3 @@
 # TODO
 
-- [ ] Chore: make docgen play nicely with lerna?
-  - [ ] Command across packages to build docs?
-- [ ] Chore: use tokens in README?
-- [ ] See [coverage](coverage.md#TODO)
+- [ ] Chore: document and update README.
diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md
index 6743b099d8abb1..4958201be72972 100644
--- a/packages/e2e-test-utils/README.md
+++ b/packages/e2e-test-utils/README.md
@@ -12,6 +12,8 @@ npm install @wordpress/e2e-test-utils --save-dev
 
 ## API
 
+<!-- START TOKEN(Autogenerated API docs) -->
+
 ### activatePlugin
 
 [src/index.js#L1-L1](src/index.js#L1-L1)
@@ -76,7 +78,7 @@ Clicks on More Menu item, searches for the button with the text provided and cli
 
 ### createEmbeddingMatcher
 
-[src/index.js#L45-L45](src/index.js#L45-L45)
+[src/index.js#L46-L46](src/index.js#L46-L46)
 
 Creates a function to determine if a request is embedding a certain URL.
 
@@ -90,7 +92,7 @@ Creates a function to determine if a request is embedding a certain URL.
 
 ### createJSONResponse
 
-[src/index.js#L45-L45](src/index.js#L45-L45)
+[src/index.js#L46-L46](src/index.js#L46-L46)
 
 Respond to a request with a JSON response.
 
@@ -129,7 +131,7 @@ Creates new URL by parsing base URL, WPPath and query string.
 
 ### createURLMatcher
 
-[src/index.js#L45-L45](src/index.js#L45-L45)
+[src/index.js#L46-L46](src/index.js#L46-L46)
 
 Creates a function to determine if a request is calling a URL with the substring present.
 
@@ -180,7 +182,7 @@ Verifies that the edit post sidebar is opened, and if it is not, opens it.
 
 `Promise` Promise resolving once the edit post sidebar is opened.
 
-### findSidebarPanelWithTitle
+### findSidebarPanelToggleButtonWithTitle
 
 [src/index.js#L15-L15](src/index.js#L15-L15)
 
@@ -194,10 +196,24 @@ Finds a sidebar panel with the provided title.
 
 `?ElementHandle` Object that represents an in-page DOM element.
 
-### getAllBlocks
+### findSidebarPanelWithTitle
 
 [src/index.js#L16-L16](src/index.js#L16-L16)
 
+Finds the button responsible for toggling the sidebar panel with the provided title.
+
+**Parameters**
+
+-   **panelTitle** `string`: The name of sidebar panel.
+
+**Returns**
+
+`?ElementHandle` Object that represents an in-page DOM element.
+
+### getAllBlocks
+
+[src/index.js#L17-L17](src/index.js#L17-L17)
+
 Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/editor' ).getBlocks();
 
 **Returns**
@@ -206,7 +222,7 @@ Returns an array with all blocks; Equivalent to calling wp.data.select( 'core/ed
 
 ### getAvailableBlockTransforms
 
-[src/index.js#L17-L17](src/index.js#L17-L17)
+[src/index.js#L18-L18](src/index.js#L18-L18)
 
 Returns an array of strings with all block titles,
 that the current selected block can be transformed into.
@@ -217,7 +233,7 @@ that the current selected block can be transformed into.
 
 ### getEditedPostContent
 
-[src/index.js#L18-L18](src/index.js#L18-L18)
+[src/index.js#L19-L19](src/index.js#L19-L19)
 
 Returns a promise which resolves with the edited post content (HTML string).
 
@@ -227,7 +243,7 @@ Returns a promise which resolves with the edited post content (HTML string).
 
 ### hasBlockSwitcher
 
-[src/index.js#L19-L19](src/index.js#L19-L19)
+[src/index.js#L20-L20](src/index.js#L20-L20)
 
 Returns a boolean indicating if the current selected block has a block switcher or not.
 
@@ -237,7 +253,7 @@ Returns a boolean indicating if the current selected block has a block switcher
 
 ### insertBlock
 
-[src/index.js#L20-L20](src/index.js#L20-L20)
+[src/index.js#L21-L21](src/index.js#L21-L21)
 
 Opens the inserter, searches for the given term, then selects the first
 result that appears.
@@ -249,7 +265,7 @@ result that appears.
 
 ### installPlugin
 
-[src/index.js#L21-L21](src/index.js#L21-L21)
+[src/index.js#L22-L22](src/index.js#L22-L22)
 
 Installs a plugin from the WP.org repository.
 
@@ -260,7 +276,7 @@ Installs a plugin from the WP.org repository.
 
 ### isCurrentURL
 
-[src/index.js#L22-L22](src/index.js#L22-L22)
+[src/index.js#L23-L23](src/index.js#L23-L23)
 
 Checks if current URL is a WordPress path.
 
@@ -275,7 +291,7 @@ Checks if current URL is a WordPress path.
 
 ### loginUser
 
-[src/index.js#L23-L23](src/index.js#L23-L23)
+[src/index.js#L24-L24](src/index.js#L24-L24)
 
 Performs log in with specified username and password.
 
@@ -286,7 +302,7 @@ Performs log in with specified username and password.
 
 ### mockOrTransform
 
-[src/index.js#L45-L45](src/index.js#L45-L45)
+[src/index.js#L46-L46](src/index.js#L46-L46)
 
 Mocks a request with the supplied mock object, or allows it to run with an optional transform, based on the
 deserialised JSON response for the request.
@@ -303,26 +319,26 @@ deserialised JSON response for the request.
 
 ### observeFocusLoss
 
-[src/index.js#L24-L24](src/index.js#L24-L24)
+[src/index.js#L25-L25](src/index.js#L25-L25)
 
 Binds to the document on page load which throws an error if a `focusout`
 event occurs without a related target (i.e. focus loss).
 
 ### openDocumentSettingsSidebar
 
-[src/index.js#L25-L25](src/index.js#L25-L25)
+[src/index.js#L26-L26](src/index.js#L26-L26)
 
 Clicks on the button in the header which opens Document Settings sidebar when it is closed.
 
 ### openPublishPanel
 
-[src/index.js#L26-L26](src/index.js#L26-L26)
+[src/index.js#L27-L27](src/index.js#L27-L27)
 
 Opens the publish panel.
 
 ### pressKeyTimes
 
-[src/index.js#L27-L27](src/index.js#L27-L27)
+[src/index.js#L28-L28](src/index.js#L28-L28)
 
 Presses the given keyboard key a number of times in sequence.
 
@@ -337,7 +353,7 @@ Presses the given keyboard key a number of times in sequence.
 
 ### pressKeyWithModifier
 
-[src/index.js#L28-L28](src/index.js#L28-L28)
+[src/index.js#L29-L29](src/index.js#L29-L29)
 
 Performs a key press with modifier (Shift, Control, Meta, Alt), where each modifier
 is normalized to platform-specific modifier.
@@ -349,7 +365,7 @@ is normalized to platform-specific modifier.
 
 ### publishPost
 
-[src/index.js#L29-L29](src/index.js#L29-L29)
+[src/index.js#L30-L30](src/index.js#L30-L30)
 
 Publishes the post, resolving once the request is complete (once a notice
 is displayed).
@@ -360,7 +376,7 @@ is displayed).
 
 ### publishPostWithPrePublishChecksDisabled
 
-[src/index.js#L30-L30](src/index.js#L30-L30)
+[src/index.js#L31-L31](src/index.js#L31-L31)
 
 Publishes the post without the pre-publish checks,
 resolving once the request is complete (once a notice is displayed).
@@ -371,7 +387,7 @@ resolving once the request is complete (once a notice is displayed).
 
 ### saveDraft
 
-[src/index.js#L31-L31](src/index.js#L31-L31)
+[src/index.js#L32-L32](src/index.js#L32-L32)
 
 Saves the post as a draft, resolving once the request is complete (once the
 "Saved" indicator is displayed).
@@ -382,7 +398,7 @@ Saves the post as a draft, resolving once the request is complete (once the
 
 ### searchForBlock
 
-[src/index.js#L32-L32](src/index.js#L32-L32)
+[src/index.js#L33-L33](src/index.js#L33-L33)
 
 Search for block in the global inserter
 
@@ -392,7 +408,7 @@ Search for block in the global inserter
 
 ### selectBlockByClientId
 
-[src/index.js#L33-L33](src/index.js#L33-L33)
+[src/index.js#L34-L34](src/index.js#L34-L34)
 
 Given the clientId of a block, selects the block on the editor.
 
@@ -402,7 +418,7 @@ Given the clientId of a block, selects the block on the editor.
 
 ### setBrowserViewport
 
-[src/index.js#L34-L34](src/index.js#L34-L34)
+[src/index.js#L35-L35](src/index.js#L35-L35)
 
 Sets browser viewport to specified type.
 
@@ -412,7 +428,7 @@ Sets browser viewport to specified type.
 
 ### setPostContent
 
-[src/index.js#L35-L35](src/index.js#L35-L35)
+[src/index.js#L36-L36](src/index.js#L36-L36)
 
 Sets code editor content
 
@@ -426,7 +442,7 @@ Sets code editor content
 
 ### setUpResponseMocking
 
-[src/index.js#L45-L45](src/index.js#L45-L45)
+[src/index.js#L46-L46](src/index.js#L46-L46)
 
 Sets up mock checks and responses. Accepts a list of mock settings with the following properties:
 
@@ -457,7 +473,7 @@ If none of the mock settings match the request, the request is allowed to contin
 
 ### switchEditorModeTo
 
-[src/index.js#L36-L36](src/index.js#L36-L36)
+[src/index.js#L37-L37](src/index.js#L37-L37)
 
 Switches editor mode.
 
@@ -467,21 +483,21 @@ Switches editor mode.
 
 ### switchUserToAdmin
 
-[src/index.js#L37-L37](src/index.js#L37-L37)
+[src/index.js#L38-L38](src/index.js#L38-L38)
 
 Switches the current user to the admin user (if the user
 running the test is not already the admin user).
 
 ### switchUserToTest
 
-[src/index.js#L38-L38](src/index.js#L38-L38)
+[src/index.js#L39-L39](src/index.js#L39-L39)
 
 Switches the current user to whichever user we should be
 running the tests as (if we're not already that user).
 
 ### toggleScreenOption
 
-[src/index.js#L39-L39](src/index.js#L39-L39)
+[src/index.js#L40-L40](src/index.js#L40-L40)
 
 Toggles the screen option with the given label.
 
@@ -492,7 +508,7 @@ Toggles the screen option with the given label.
 
 ### transformBlockTo
 
-[src/index.js#L40-L40](src/index.js#L40-L40)
+[src/index.js#L41-L41](src/index.js#L41-L41)
 
 Converts editor's block type.
 
@@ -502,7 +518,7 @@ Converts editor's block type.
 
 ### uninstallPlugin
 
-[src/index.js#L41-L41](src/index.js#L41-L41)
+[src/index.js#L42-L42](src/index.js#L42-L42)
 
 Uninstalls a plugin.
 
@@ -512,7 +528,7 @@ Uninstalls a plugin.
 
 ### visitAdminPage
 
-[src/index.js#L42-L42](src/index.js#L42-L42)
+[src/index.js#L43-L43](src/index.js#L43-L43)
 
 Visits admin page; if user is not logged in then it logging in it first, then visits admin page.
 
@@ -523,7 +539,7 @@ Visits admin page; if user is not logged in then it logging in it first, then vi
 
 ### waitForWindowDimensions
 
-[src/index.js#L43-L43](src/index.js#L43-L43)
+[src/index.js#L44-L44](src/index.js#L44-L44)
 
 Function that waits until the page viewport has the required dimensions.
 It is being used to address a problem where after using setViewport the execution may continue,
@@ -535,4 +551,7 @@ without the new dimensions being applied.
 -   **width** `number`: Width of the window.
 -   **height** `height`: Height of the window.
 
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/e2e-test-utils/package.json b/packages/e2e-test-utils/package.json
index f31d67677475e2..0a6871bff1d76c 100644
--- a/packages/e2e-test-utils/package.json
+++ b/packages/e2e-test-utils/package.json
@@ -33,11 +33,17 @@
 		"lodash": "^4.17.11",
 		"node-fetch": "^1.7.3"
 	},
+	"devDependencies": {
+		"@wordpress/docgen": "file:../docgen"
+	},
 	"peerDependencies": {
 		"jest": ">=24",
 		"puppeteer": ">=1.6"
 	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"scripts": {
+		"docs:generate": "docgen ./src/index.js --output ./README.md --to-token"
 	}
 }

From 996e65a6d4e0e2cb9c2a8128d4657168304b2e3e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 12:57:39 +0100
Subject: [PATCH 202/213] Update docs

---
 packages/docgen/README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 45c858085e6c77..f1ded76208a05f 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -31,8 +31,9 @@ This command will generate a file named `entry-point-api.md` containing all the
   * *symbols* `(Array)`: the symbols found.
 * **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it.
 * **--output** `(String)`: Output file that will contain the API documentation.
+* **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any.
+* **--to-token**: Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any.
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
-* **--append** `(String)`: Title of the Markdown section to append the generated documentation to. It takes precedence over and bypasses the *--formatter* option.
 
 ## Examples
 

From ae3cf05a23df67060f1620efb9e610af0592942c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 13:00:54 +0100
Subject: [PATCH 203/213] Update README

---
 packages/docgen/README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index f1ded76208a05f..01944a75a7e2d1 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -32,7 +32,9 @@ This command will generate a file named `entry-point-api.md` containing all the
 * **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it.
 * **--output** `(String)`: Output file that will contain the API documentation.
 * **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any.
-* **--to-token**: Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any.
+* **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any.
+  * Start token: `<!-- START TOKEN(Autogenerated API Docs) -->`
+  * End token: `<!-- END TOKEN(Autogenerated API Docs) -->`
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
 
 ## Examples

From 3e842bc41c40559ec92e6bcc16ea938ab2486aa6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 13:20:55 +0100
Subject: [PATCH 204/213] Add --use-token option

---
 packages/docgen/README.md                          | 5 +++--
 packages/docgen/bin/cli.js                         | 6 ++++++
 packages/docgen/src/markdown/embed.js              | 7 ++++---
 packages/docgen/src/markdown/index.js              | 4 ++--
 packages/docgen/src/test/fixtures/markdown/docs.md | 2 +-
 5 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 01944a75a7e2d1..c59b0c7fa19bfe 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -33,8 +33,9 @@ This command will generate a file named `entry-point-api.md` containing all the
 * **--output** `(String)`: Output file that will contain the API documentation.
 * **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any.
 * **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any.
-  * Start token: `<!-- START TOKEN(Autogenerated API Docs) -->`
-  * End token: `<!-- END TOKEN(Autogenerated API Docs) -->`
+  * Start token: `<!-- START TOKEN(Autogenerated API docs) -->`
+  * End token: `<!-- END TOKEN(Autogenerated API docs) -->`
+* **--use-token** `(String)`: This options allows to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `<!-- START TOKEN(my-api) -->` and the end token `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`.
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
 
 ## Examples
diff --git a/packages/docgen/bin/cli.js b/packages/docgen/bin/cli.js
index f5bdb94f55b859..bcc1a6f1e245d0 100755
--- a/packages/docgen/bin/cli.js
+++ b/packages/docgen/bin/cli.js
@@ -26,6 +26,12 @@ const optionator = require( 'optionator' )( {
 		type: 'Boolean',
 		description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.',
 		dependsOn: 'output',
+	}, {
+		option: 'use-token',
+		type: 'String',
+		default: 'Autogenerated API docs',
+		description: 'Add this string to the start/end tokens.',
+		dependsOn: 'to-token',
 	}, {
 		option: 'debug',
 		type: 'Boolean',
diff --git a/packages/docgen/src/markdown/embed.js b/packages/docgen/src/markdown/embed.js
index 5b1c334b921833..5545832e7f4341 100644
--- a/packages/docgen/src/markdown/embed.js
+++ b/packages/docgen/src/markdown/embed.js
@@ -12,21 +12,22 @@ 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 {Object} newContentAst The new contents to be embedded in remark AST format.
  * @return {boolean} Whether the contents were embedded or not.
  */
-const embed = function( targetAst, newContentAst ) {
+const embed = function( token, targetAst, newContentAst ) {
 	let headingIndex = -1;
 
 	const startIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === '<!-- START TOKEN(Autogenerated API docs) -->'
+		( node ) => node.type === 'html' && node.value === `<!-- START TOKEN(${ token }) -->`
 	);
 	if ( startIndex === -1 ) {
 		return false;
 	}
 	const endIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === '<!-- END TOKEN(Autogenerated API docs) -->'
+		( node ) => node.type === 'html' && node.value === `<!-- END TOKEN(${ token }) -->`
 	);
 	if ( endIndex === -1 ) {
 		return false;
diff --git a/packages/docgen/src/markdown/index.js b/packages/docgen/src/markdown/index.js
index 479e8816250653..499e211e1873a4 100644
--- a/packages/docgen/src/markdown/index.js
+++ b/packages/docgen/src/markdown/index.js
@@ -17,8 +17,8 @@ const appendOrEmbedContents = ( { options, newContents } ) => {
 	return function transform( targetAst, file, next ) {
 		if ( options.toSection && ! inject( options.toSection, targetAst, newContents ) ) {
 			return next( new Error( `Heading ${ options.toSection } not found.` ) );
-		} else if ( options.toToken && ! embed( targetAst, newContents ) ) {
-			return next( new Error( `Token not found.` ) );
+		} else if ( options.toToken && ! embed( options.useToken, targetAst, newContents ) ) {
+			return next( new Error( `Start and/or end tokens for ${ options.useToken } not found.` ) );
 		}
 		next();
 	};
diff --git a/packages/docgen/src/test/fixtures/markdown/docs.md b/packages/docgen/src/test/fixtures/markdown/docs.md
index 05e43204772e73..12baa9046d0280 100644
--- a/packages/docgen/src/test/fixtures/markdown/docs.md
+++ b/packages/docgen/src/test/fixtures/markdown/docs.md
@@ -8,7 +8,7 @@ This is some package docs.
 
 ### sum
 
-[markdown-code.js#L22-L24](markdown-code.js#L22-L24)
+[code.js#L22-L24](code.js#L22-L24)
 
 > **Deprecated** Use native addition instead.
 

From 8429aa276c2bd3d86eac005ffa57d901e4edd96a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 13:29:43 +0100
Subject: [PATCH 205/213] Extract constants

---
 packages/docgen/TODO.md               | 3 ---
 packages/docgen/src/markdown/embed.js | 6 ++++--
 2 files changed, 4 insertions(+), 5 deletions(-)
 delete mode 100644 packages/docgen/TODO.md

diff --git a/packages/docgen/TODO.md b/packages/docgen/TODO.md
deleted file mode 100644
index 62ec867f9d5004..00000000000000
--- a/packages/docgen/TODO.md
+++ /dev/null
@@ -1,3 +0,0 @@
-# TODO
-
-- [ ] Chore: document and update README.
diff --git a/packages/docgen/src/markdown/embed.js b/packages/docgen/src/markdown/embed.js
index 5545832e7f4341..9b52064c3377a4 100644
--- a/packages/docgen/src/markdown/embed.js
+++ b/packages/docgen/src/markdown/embed.js
@@ -20,14 +20,16 @@ const getHeadingIndex = ( ast, index ) => {
 const embed = function( token, targetAst, newContentAst ) {
 	let headingIndex = -1;
 
+	const START_TOKEN = `<!-- START TOKEN(${ token }) -->`;
+	const END_TOKEN = `<!-- END TOKEN(${ token }) -->`;
 	const startIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === `<!-- START TOKEN(${ token }) -->`
+		( node ) => node.type === 'html' && node.value === START_TOKEN
 	);
 	if ( startIndex === -1 ) {
 		return false;
 	}
 	const endIndex = targetAst.children.findIndex(
-		( node ) => node.type === 'html' && node.value === `<!-- END TOKEN(${ token }) -->`
+		( node ) => node.type === 'html' && node.value === END_TOKEN
 	);
 	if ( endIndex === -1 ) {
 		return false;

From 5c30f1ca832aa665735eae316e4f14a7c5630ce2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 14:02:46 +0100
Subject: [PATCH 206/213] Update README

---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index c59b0c7fa19bfe..bc641726a1cba5 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -18,7 +18,7 @@ npm install @wordpress/docgen --save-dev
 ## Usage
 
 ```bash
-node src/cli.js <entry-point.js>
+npx docgen <entry-point.js>
 ```
 
 This command will generate a file named `entry-point-api.md` containing all the exports and its JSDoc comments.

From fb03ec9fbeaeddff48dbaa030cace3bc20638a46 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 14:16:20 +0100
Subject: [PATCH 207/213] Make formatter-markdown test be deterministic

---
 packages/docgen/src/test/formatter-markdown.js | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js
index 1370185b19f722..a683e841155f32 100644
--- a/packages/docgen/src/test/formatter-markdown.js
+++ b/packages/docgen/src/test/formatter-markdown.js
@@ -5,8 +5,9 @@ const formatter = require( '../markdown/formatter' );
 
 describe( 'Formatter', () => {
 	it( 'returns markdown', () => {
-		const docPath = process.cwd();
-		const docs = formatter( docPath, docPath + '-api.md', [ {
+		const rootDir = '/home/my-path';
+		const docPath = 'docs';
+		const docs = formatter( rootDir, docPath + '-api.md', [ {
 			path: docPath + '-code.js',
 			description: 'My declaration example.',
 			tags: [
@@ -27,7 +28,7 @@ describe( 'Formatter', () => {
 			lineEnd: 2,
 		} ], 'API docs' );
 		expect( docs ).toBe(
-			'# API docs\n\n## myDeclaration\n\n[gutenberg/home/andres/src/gutenberg-code.js#L1-L2](gutenberg/home/andres/src/gutenberg-code.js#L1-L2)\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'
+			'# API docs\n\n## myDeclaration\n\n[../../../my-path/docs-code.js#L1-L2](../../../my-path/docs-code.js#L1-L2)\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'
 		);
 	} );
 } );

From 77e3d8efbaeae3fe06f2082364f34ad4d983201e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 16:41:45 +0100
Subject: [PATCH 208/213] Make formatter-markdown test be deterministic

---
 packages/docgen/src/test/formatter-markdown.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/docgen/src/test/formatter-markdown.js b/packages/docgen/src/test/formatter-markdown.js
index a683e841155f32..cd7e66a12e2678 100644
--- a/packages/docgen/src/test/formatter-markdown.js
+++ b/packages/docgen/src/test/formatter-markdown.js
@@ -6,7 +6,7 @@ const formatter = require( '../markdown/formatter' );
 describe( 'Formatter', () => {
 	it( 'returns markdown', () => {
 		const rootDir = '/home/my-path';
-		const docPath = 'docs';
+		const docPath = '/home/my-path/docs';
 		const docs = formatter( rootDir, docPath + '-api.md', [ {
 			path: docPath + '-code.js',
 			description: 'My declaration example.',
@@ -28,7 +28,7 @@ describe( 'Formatter', () => {
 			lineEnd: 2,
 		} ], 'API docs' );
 		expect( docs ).toBe(
-			'# API docs\n\n## myDeclaration\n\n[../../../my-path/docs-code.js#L1-L2](../../../my-path/docs-code.js#L1-L2)\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'
+			'# API docs\n\n## myDeclaration\n\n[home/my-path/docs-code.js#L1-L2](home/my-path/docs-code.js#L1-L2)\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'
 		);
 	} );
 } );

From f2553041cd8876f4ee8637faa05cc8318cf06958 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 27 Feb 2019 18:35:02 +0100
Subject: [PATCH 209/213] Update packages/docgen/README.md

Co-Authored-By: nosolosw <nosolosw@users.noreply.github.com>
---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index bc641726a1cba5..6b0e917c4e1175 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -21,7 +21,7 @@ npm install @wordpress/docgen --save-dev
 npx docgen <entry-point.js>
 ```
 
-This command will generate a file named `entry-point-api.md` containing all the exports and its JSDoc comments.
+This command will generate a file named `entry-point-api.md` containing all the exports and their JSDoc comments.
 
 ### CLI options
 

From 6616bc083b31970d894cee8acae795bd9bb525f9 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 27 Feb 2019 18:35:15 +0100
Subject: [PATCH 210/213] Update packages/docgen/README.md

Co-Authored-By: nosolosw <nosolosw@users.noreply.github.com>
---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 6b0e917c4e1175..094ff8af264213 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -35,7 +35,7 @@ This command will generate a file named `entry-point-api.md` containing all the
 * **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any.
   * Start token: `<!-- START TOKEN(Autogenerated API docs) -->`
   * End token: `<!-- END TOKEN(Autogenerated API docs) -->`
-* **--use-token** `(String)`: This options allows to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `<!-- START TOKEN(my-api) -->` and the end token `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`.
+* **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `<!-- START TOKEN(my-api) -->` and the end token `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`.
 * **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
 
 ## Examples

From c8fcab7a70350efe14deb5f293dd70b48194fa36 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 27 Feb 2019 18:35:30 +0100
Subject: [PATCH 211/213] Update packages/docgen/README.md

Co-Authored-By: nosolosw <nosolosw@users.noreply.github.com>
---
 packages/docgen/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 094ff8af264213..39e568ba3f0f59 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -36,7 +36,7 @@ This command will generate a file named `entry-point-api.md` containing all the
   * Start token: `<!-- START TOKEN(Autogenerated API docs) -->`
   * End token: `<!-- END TOKEN(Autogenerated API docs) -->`
 * **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `<!-- START TOKEN(my-api) -->` and the end token `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`.
-* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging
+* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging.
 
 ## Examples
 

From 47b78e36558cc11d40ab5ca45c7bcb8e9fa36b37 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 27 Feb 2019 18:45:57 +0100
Subject: [PATCH 212/213] Add command in the examples

---
 packages/docgen/README.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/docgen/README.md b/packages/docgen/README.md
index 39e568ba3f0f59..c62b96fc4e44b4 100644
--- a/packages/docgen/README.md
+++ b/packages/docgen/README.md
@@ -42,7 +42,7 @@ This command will generate a file named `entry-point-api.md` containing all the
 
 ### Default export
 
-Entry point:
+Entry point `index.js`:
 
 ```js
 /**
@@ -57,7 +57,7 @@ export default function addition( term1, term2 ) {
 }
 ```
 
-Output:
+Output of `npx docgen index.js` would be `index-api.js`:
 
 ```markdown
 # API
@@ -80,7 +80,7 @@ Adds two numbers.
 
 ### Named export
 
-Entry point:
+Entry point `index.js`:
 
 ```js
 /**
@@ -110,7 +110,7 @@ function count( term1, term2 ) {
 export { count, addition };
 ```
 
-Output:
+Output of `npx docgen index.js` would be `index-api.js`:
 
 ```markdown
 # API
@@ -150,7 +150,7 @@ Adds two numbers.
 
 ### Namespace export
 
-Let the entry point be:
+Let the entry point be `index.js`:
 
 ```js
 export * from './count';
@@ -197,7 +197,7 @@ export function addition( term1, term2 ) {
 }
 ```
 
-Output would be:
+Output of `npx docgen index.js` would be `index-api.js`:
 
 ````markdown
 # API

From 2610e872559974ec5c1d3c803ec87a4c49ed95e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 1 Mar 2019 17:45:14 +0100
Subject: [PATCH 213/213] Update package-lock using the latest npm

---
 package-lock.json | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index dbd2813a0d8852..2f0d39cd7a38c8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -8709,7 +8709,8 @@
 				"ansi-regex": {
 					"version": "2.1.1",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"aproba": {
 					"version": "1.2.0",
@@ -8737,6 +8738,7 @@
 					"version": "1.1.11",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"balanced-match": "^1.0.0",
 						"concat-map": "0.0.1"
@@ -8751,7 +8753,8 @@
 				"code-point-at": {
 					"version": "1.1.0",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"concat-map": {
 					"version": "0.0.1",
@@ -8762,7 +8765,8 @@
 				"console-control-strings": {
 					"version": "1.1.0",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"core-util-is": {
 					"version": "1.0.2",
@@ -8879,7 +8883,8 @@
 				"inherits": {
 					"version": "2.0.3",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"ini": {
 					"version": "1.3.5",
@@ -8891,6 +8896,7 @@
 					"version": "1.0.0",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"number-is-nan": "^1.0.0"
 					}
@@ -8905,6 +8911,7 @@
 					"version": "3.0.4",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"brace-expansion": "^1.1.7"
 					}
@@ -8912,12 +8919,14 @@
 				"minimist": {
 					"version": "0.0.8",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"minipass": {
 					"version": "2.2.4",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"safe-buffer": "^5.1.1",
 						"yallist": "^3.0.0"
@@ -8936,6 +8945,7 @@
 					"version": "0.5.1",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"minimist": "0.0.8"
 					}
@@ -9016,7 +9026,8 @@
 				"number-is-nan": {
 					"version": "1.0.1",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"object-assign": {
 					"version": "4.1.1",
@@ -9028,6 +9039,7 @@
 					"version": "1.4.0",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"wrappy": "1"
 					}
@@ -9113,7 +9125,8 @@
 				"safe-buffer": {
 					"version": "5.1.1",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"safer-buffer": {
 					"version": "2.1.2",
@@ -9149,6 +9162,7 @@
 					"version": "1.0.2",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"code-point-at": "^1.0.0",
 						"is-fullwidth-code-point": "^1.0.0",
@@ -9168,6 +9182,7 @@
 					"version": "3.0.1",
 					"bundled": true,
 					"dev": true,
+					"optional": true,
 					"requires": {
 						"ansi-regex": "^2.0.0"
 					}
@@ -9211,12 +9226,14 @@
 				"wrappy": {
 					"version": "1.0.2",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				},
 				"yallist": {
 					"version": "3.0.2",
 					"bundled": true,
-					"dev": true
+					"dev": true,
+					"optional": true
 				}
 			}
 		},