refactor(gulpfile): cleanup, add comments

gulpfile.js

@@ -2,18 +2,26 @@
 
 // THIS CHECK SHOULD BE THE FIRST THING IN THIS FILE
 // This is to ensure that we catch env issues before we error while requiring other dependencies.
-require('./tools/check-environment')(
-    {requiredNpmVersion: '>=3.5.3 <4.0.0', requiredNodeVersion: '>=5.4.1 <6.0.0'});
-
+require('./tools/check-environment')({
+  requiredNpmVersion: '>=3.5.3 <4.0.0',
+  requiredNodeVersion: '>=5.4.1 <6.0.0',
+});
 
 const gulp = require('gulp');
 const path = require('path');
 const os = require('os');
 
-const srcsToFmt =
-    ['tools/**/*.ts', 'modules/@angular/**/*.ts', '!tools/public_api_guard/**/*.d.ts',
-    'modules/playground/**/*.ts', 'modules/benchmarks/**/*.ts', 'modules/e2e_util/**/*.ts'];
+// clang-format entry points
+const srcsToFmt = [
+  'modules/@angular/**/*.ts',
+  'modules/benchmarks/**/*.ts',
+  'modules/e2e_util/**/*.ts',
+  'modules/playground/**/*.ts',
+  'tools/**/*.ts',
+  '!tools/public_api_guard/**/*.d.ts',
+];
 
+// Check source code for formatting errors (clang-format)
 gulp.task('format:enforce', () => {
   const format = require('gulp-clang-format');
   const clangFormat = require('clang-format');
@@ -21,6 +29,7 @@ gulp.task('format:enforce', () => {
     format.checkFormat('file', clangFormat, {verbose: true, fail: true}));
 });
 
+// Format the source code with clang-format (see .clang-format)
 gulp.task('format', () => {
   const format = require('gulp-clang-format');
   const clangFormat = require('clang-format');
@@ -49,7 +58,7 @@ const entrypoints = [
   'dist/packages-dist/http/index.d.ts',
   'dist/packages-dist/http/testing/index.d.ts',
   'dist/packages-dist/forms/index.d.ts',
-  'dist/packages-dist/router/index.d.ts'
+  'dist/packages-dist/router/index.d.ts',
 ];
 const publicApiDir = path.normalize('tools/public_api_guard');
 const publicApiArgs = [
@@ -58,22 +67,24 @@ const publicApiArgs = [
   '--allowModuleIdentifiers', 'jasmine',
   '--allowModuleIdentifiers', 'protractor',
   '--allowModuleIdentifiers', 'angular',
-  '--onStabilityMissing', 'error'
+  '--onStabilityMissing', 'error',
 ].concat(entrypoints);
 
+// Build angular
 gulp.task('build.sh', (done) => {
   const childProcess = require('child_process');
 
-  childProcess.exec(path.join(__dirname, 'build.sh'), error => done(error));
+  childProcess.exec(path.join(__dirname, 'build.sh'), done);
 });
 
+// Enforce that the public API matches the golden files
 // Note that these two commands work on built d.ts files instead of the source
 gulp.task('public-api:enforce', (done) => {
   const childProcess = require('child_process');
 
   childProcess
     .spawn(
-      path.join(__dirname, `/node_modules/.bin/ts-api-guardian${/^win/.test(os.platform()) ? '.cmd' : ''}`),
+      path.join(__dirname, pfScriptPath(`/node_modules/.bin/ts-api-guardian`)),
       ['--verifyDir', publicApiDir].concat(publicApiArgs), {stdio: 'inherit'})
     .on('close', (errorCode) => {
       if (errorCode !== 0) {
@@ -85,17 +96,19 @@ gulp.task('public-api:enforce', (done) => {
     });
 });
 
+// Generate the public API golden files
 gulp.task('public-api:update', ['build.sh'], (done) => {
   const childProcess = require('child_process');
 
   childProcess
     .spawn(
-      path.join(__dirname, `/node_modules/.bin/ts-api-guardian${/^win/.test(os.platform()) ? '.cmd' : ''}`),
+      path.join(__dirname, pfScriptPath(`/node_modules/.bin/ts-api-guardian`)),
       ['--outDir', publicApiDir].concat(publicApiArgs), {stdio: 'inherit'})
-    .on('close', (errorCode) => done(errorCode));
+    .on('close', done);
 });
 
-gulp.task('lint', ['format:enforce', 'tools:build'], () => {
+// Check the coding standards and programming errors
+gulp.task('lint', [ 'format:enforce', 'tools:build'], () => {
   const tslint = require('gulp-tslint');
   // Built-in rules are at
   // https://github.com/palantir/tslint#supported-rules
@@ -105,22 +118,23 @@ gulp.task('lint', ['format:enforce', 'tools:build'], () => {
       tslint: require('tslint').default,
       configuration: tslintConfig,
       rulesDirectory: 'dist/tools/tslint',
-      formatter: 'prose'
+      formatter: 'prose',
     }))
     .pipe(tslint.report({emitError: true}));
 });
 
 gulp.task('tools:build', (done) => { tsc('tools/', done); });
 
+// Check for circular dependency in the source code
 gulp.task('check-cycle', (done) => {
   const madge = require('madge');
 
-  var dependencyObject = madge(['dist/all/'], {
+  const dependencyObject = madge(['dist/all/'], {
     format: 'cjs',
     extensions: ['.js'],
     onParseFile: function(data) { data.src = data.src.replace(/\/\* circular \*\//g, "//"); }
   });
-  var circularDependencies = dependencyObject.circular().getArray();
+  const circularDependencies = dependencyObject.circular().getArray();
   if (circularDependencies.length > 0) {
     console.log('Found circular dependencies!');
     console.log(circularDependencies);
@@ -129,33 +143,36 @@ gulp.task('check-cycle', (done) => {
   done();
 });
 
+// Serve the built files
 gulp.task('serve', () => {
-  let connect = require('gulp-connect');
-  let cors = require('cors');
+  const connect = require('gulp-connect');
+  const cors = require('cors');
 
   connect.server({
     root: `${__dirname}/dist`,
     port: 8000,
     livereload: false,
     open: false,
-    middleware: (connect, opt) => [cors()]
+    middleware: (connect, opt) => [cors()],
   });
 });
 
+// Serve the examples
 gulp.task('serve-examples', () => {
-  let connect = require('gulp-connect');
-  let cors = require('cors');
+  const connect = require('gulp-connect');
+  const cors = require('cors');
 
   connect.server({
       root: `${__dirname}/dist/examples`,
       port: 8001,
       livereload: false,
       open: false,
-      middleware: (connect, opt) => [cors()]
+      middleware: (connect, opt) => [cors()],
   });
 });
 
 
+// Update the changelog with the latest changes
 gulp.task('changelog', () => {
   const conventionalChangelog = require('gulp-conventional-changelog');
 
@@ -177,8 +194,13 @@ function tsc(projectPath, done) {
 
   childProcess
       .spawn(
-          path.normalize(`${__dirname}/node_modules/.bin/tsc`) + (/^win/.test(os.platform()) ? '.cmd' : ''),
+          path.normalize(platformScriptPath(`${__dirname}/node_modules/.bin/tsc`)),
           ['-p', path.join(__dirname, projectPath)],
           {stdio: 'inherit'})
-      .on('close', (errorCode) => done(errorCode));
+      .on('close', done);
+}
+
+// returns the script path for the current platform
+function platformScriptPath(path) {
+  return /^win/.test(os.platform()) ? `${path}.cmd` : path;
 }