#1: improve comments + docs for error formatter

README.md

@@ -74,6 +74,7 @@ Gulp powers the frontend build system. All the frontend assets (CSS, JS, images)
 | `gulp watch` | Run "default" task and continue watching |
 | `gulp {taskName}` | Run a specific task |
 | `gulp --hide-notify` | Run "default" task (once) and suppress Mac/Windows notifications |
+| `gulp --show-properties` | Run "default" task (once) and log detailed error info in the console |
 
 #### Maintain build tools
 

gulp/error-formatter.js

@@ -7,27 +7,41 @@
 */
 
 
-// ==============================================
+// **********************************************
 // Gulp Error Formatter
-// ==============================================
+//
+// Plugins return inconsistent `error` objects. This module:
+//
+// - Uses Node "stream.pipeline" to keep errors from ending streams.
+// - Normalizes and formats the error, so the console is readable.
+// - Shows Mac/Windows notifications with file + line number hints.
+// **********************************************
+
 
-// An error formatter that uses Node "stream.pipeline" to keep errors from ending streams.
-// Each plugin may have unique error objects, so the response is normalized.
+// ==============================================
+// Packages
+// ==============================================
 
 var beeper      = require('beeper');
 var color       = require('ansi-colors');
 var minimist    = require('minimist');
 var notify      = require('gulp-notify');
 var PluginError = require('plugin-error');
 
-// ----------------------------------------------
+
+// ==============================================
 // Arguments
+// ==============================================
+
+var arguments = minimist(process.argv.slice(2));
 
-var arguments      = minimist(process.argv.slice(2));
+// Use "gulp --show-properties" to log detailed error info in the console.
 var showProperties = (arguments['show-properties']) ? true : false;
 
-// ----------------------------------------------
+
+// ==============================================
 // Module
+// ==============================================
 
 module.exports = function (error) {
     if (typeof error !== 'undefined') {