Fix npm run docs:build on Windows environments (#16029)

* Fix `npm run docs:build` on Windows environments

Windows environments do not support shebang (#!) scripts. This caused
`npm run docs:build` to error when running it on Windows. The fix is to
run `node docs/tool/update-data.js` instead of running
`./docs/tool/update-data.js`.

Similarly, running `node path/to/directory` can cause problems, so we
update the docs:build task to use `node path/to/directory/index.js`.

docs:build: Use the .js extension in the filename

* docgen: Correctly handle docblocks with CRLF line endings

This allows `npm run docs:build` to generate docs on Windows
environments.

* Use explicit paths as to prevent errors in Windows machines

* Remove shebang notation in update-readmes.js

so it works consistently in Windows machines.

* Add comment

Author: noisysocks

bin/update-readmes.js

@@ -1,5 +1,6 @@
-#!/usr/bin/env node
-
+/**
+ * Node dependencies.
+ */
 const { join } = require( 'path' );
 const spawnSync = require( 'child_process' ).spawnSync;
 

docs/tool/index.js

@@ -3,7 +3,7 @@
  */
 const fs = require( 'fs' );
 const { join } = require( 'path' );
-const { execSync } = require( 'child_process' );
+const { execFileSync } = require( 'child_process' );
 const path = require( 'path' );
 
 /**
@@ -15,7 +15,7 @@ const tocFileInput = path.resolve( __dirname, '../toc.json' );
 const manifestOutput = path.resolve( __dirname, '../manifest-devhub.json' );
 
 // Update data files from code
-execSync( join( __dirname, 'update-data.js' ) );
+execFileSync( 'node', [ join( __dirname, 'update-data.js' ) ] );
 
 // Process TOC file and generate manifest handbook
 fs.writeFileSync( manifestOutput, JSON.stringify( getRootManifest( tocFileInput ), undefined, '\t' ) );

docs/tool/update-data.js

@@ -1,5 +1,6 @@
-#!/usr/bin/env node
-
+/**
+ * Node dependencies.
+ */
 const { join } = require( 'path' );
 const spawnSync = require( 'child_process' ).spawnSync;
 

package.json

@@ -188,7 +188,7 @@
 		"predev": "npm run check-engines",
 		"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 && node ./bin/update-readmes",
+		"docs:build": "node ./docs/tool/index.js && node ./bin/update-readmes.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",
@@ -233,10 +233,10 @@
 			"wp-scripts lint-js"
 		],
 		"{docs/{toc.json,tool/*.js},packages/{*/README.md,*/src/{actions,selectors}.js,components/src/*/**/README.md}}": [
-			"node ./docs/tool"
+			"node ./docs/tool/index.js"
 		],
 		"packages/**/*.js": [
-			"node ./bin/update-readmes"
+			"node ./bin/update-readmes.js"
 		]
 	}
 }

packages/docgen/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.2.1 (Unreleased)
+
+### Bug Fixes
+
+- Docblocks with CRLF endings are now parsed correctly.
+
 ## 1.2.0 (2019-05-21)
 
 ### Enhancement

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

@@ -20,7 +20,7 @@ const getTypeAsString = require( './get-type-as-string' );
 module.exports = function( token ) {
 	let jsdoc;
 	const comments = getLeadingComments( token );
-	if ( comments && comments.startsWith( '*\n' ) ) {
+	if ( comments && /^\*\r?\n/.test( comments ) ) {
 		jsdoc = doctrine.parse( comments, {
 			unwrap: true,
 			recoverable: true,