📘 gulpfile comments

gulpfile.js

@@ -17,6 +17,10 @@ var uncss = require('gulp-uncss');
 
 // -----------------------------------------------------------------------------
 // Remove old CSS
+//
+// This task only deletes the files generated by the 'sass' and 'css' tasks.
+// The 'uncss' task is slow to run and less frequently needed, so we keep the
+// build process fast by making uncss a manually-executed task.
 // -----------------------------------------------------------------------------
 gulp.task('clean-css', function() {
   return del(['css/{all,main}*'], function (err) {
@@ -32,8 +36,9 @@ gulp.task('clean-css', function() {
 
 // -----------------------------------------------------------------------------
 // Sass Task
-// - Compiles Sass
-// - Autoprefixes
+//
+// Compiles Sass and runs the CSS through autoprefixer. A separate task will
+// combine the compiled CSS with vendor files and minify the aggregate.
 // -----------------------------------------------------------------------------
 gulp.task('sass', function() {
   return gulp.src('_sass/**/*.scss')
@@ -54,6 +59,10 @@ gulp.task('sass', function() {
 
 // -----------------------------------------------------------------------------
 // Combine and Minify CSS
+//
+// This task minifies all the CSS found in the css/ directory, including the
+// uncss-ed copies of bootstrap. The end result is a minified aggregate, ready
+// to be served.
 // -----------------------------------------------------------------------------
 gulp.task('css', ['clean-css', 'sass'], function() {
   return gulp.src('css/*.css')
@@ -65,7 +74,10 @@ gulp.task('css', ['clean-css', 'sass'], function() {
 
 // -----------------------------------------------------------------------------
 // UnCSS Task
-// - Checks the site's usage of Bootstrap and strips unused styles out of files.
+//
+// Checks the site's usage of Bootstrap and strips unused styles out. Outputs
+// the resulting files in the css/ directory where they will be combined and
+// minified by a separate task.
 //
 // Note: this task requires a local server to be running because it references
 // the actual compiled site to calculate the unused styles.
@@ -86,11 +98,23 @@ gulp.task('uncss', function() {
     .pipe(gulp.dest('css/'));
 });
 
-// Watch
+// -----------------------------------------------------------------------------
+// Watch tasks
+//
+// These tasks are run whenever a file is saved. Don't confuse the files being
+// watched (gulp.watch blobs in this task) with the files actually operated on
+// by the gulp.src blobs in each individual task.
+// -----------------------------------------------------------------------------
 gulp.task('watch', function() {
   gulp.watch('_sass/**/*.scss', ['css']);
 });
 
+// -----------------------------------------------------------------------------
 // Default: load task listing
+//
+// Instead of launching some unspecified build process when someone innocently
+// types `gulp` into the command line, we provide a task listing so they know
+// what options they have without digging into the file.
+// -----------------------------------------------------------------------------
 gulp.task('help', tasks);
 gulp.task('default', ['help']);