add hideEmpty option. Fixes #8

Author: chmontgomery

examples/advanced/gulpfile.js

@@ -1,4 +1,4 @@
-var gulp = require('../../index.js')(require('gulp'), { aliases: ['h', '?'] });
+var gulp = require('../../index.js')(require('gulp'), {aliases: ['h', '?']});
 
 // --------------------------------------------------------------------------------------
 // tasks

index.js

@@ -7,7 +7,8 @@ var objectAssign = require('object-assign'),
     aliases: [],
     description: 'Display this help text.',
     afterPrintCallback: noop,
-    hideDepsMessage: false
+    hideDepsMessage: false,
+    hideEmpty: false
   };
 
 module.exports = function (gulp, options) {
@@ -96,7 +97,10 @@ module.exports = function (gulp, options) {
   gulp.task('help', options.description, function () {
     var marginData = calculateMargin(gulp.tasks);
     var margin = marginData.margin;
-    var hideDepsMessage = options.hideDepsMessage;
+    var hideDepsMessageOpt = options.hideDepsMessage;
+    var hideEmptyOpt = options.hideEmpty;
+    var showAllTasks = process.argv.indexOf('--all') !== -1;
+    var afterPrintCallback = options.afterPrintCallback;
 
     // set options buffer if the tasks array has options
     var optionsBuffer = marginData.hasOptions ? '  --' : '';
@@ -107,8 +111,12 @@ module.exports = function (gulp, options) {
     console.log('');
     console.log(chalk.underline('Available tasks'));
     Object.keys(gulp.tasks).sort().forEach(function (name) {
-      if (gulp.tasks[name].help || process.argv.indexOf('--all') !== -1) {
+      if (gulp.tasks[name].help || showAllTasks) {
         var help = gulp.tasks[name].help || {message: '', options: {}};
+
+        if (!showAllTasks && help.message === '' && hideEmptyOpt) {
+          return; //skip task
+        }
         var args = [' ', chalk.cyan(name)];
 
         args.push(new Array(margin - name.length + 1 + optionsBuffer.length).join(' '));
@@ -121,7 +129,7 @@ module.exports = function (gulp, options) {
           args.push(help.aliases);
         }
 
-        if (help.depsMessage && !hideDepsMessage) {
+        if (help.depsMessage && !hideDepsMessageOpt) {
           args.push(chalk.cyan(help.depsMessage));
         }
 
@@ -138,8 +146,8 @@ module.exports = function (gulp, options) {
       }
     });
     console.log('');
-    if (options.afterPrintCallback) {
-      options.afterPrintCallback(gulp.tasks);
+    if (afterPrintCallback) {
+      afterPrintCallback(gulp.tasks);
     }
   }, options);
 

readme.md

@@ -43,7 +43,16 @@ Type: `string`
 Type: `string | boolean`
 
 Custom help message as a string.
-If you want to hide the task from the help menu, supply `false`.
+
+If you want to hide the task from the help menu, supply `false`
+
+```js
+gulp.task('task-hidden-from-help', false, function () {
+  // ...
+});
+```
+
+However, if the `--all` flag is provided, even these tasks will be shown. (i.e. `gulp help --all`)
 
 #### [deps](https://github.com/gulpjs/gulp/blob/master/docs/API.md#deps)
 
@@ -57,23 +66,7 @@ Type: `function`
 
 Type: `Array`
 
-List of aliases for this task.
-
-## Hide Tasks
-
-You can optionally hide a target from showing up in the help menu by passing `false` as the help argument, e.g.
-
-```js
-gulp.task('task-hidden-from-help', false, function () {
-  // ...
-});
-```
-
-However, if the `--all` flag is provided, even these tasks will be shown. (i.e. `gulp help --all`)
-
-## Aliases
-
-You can optionally add aliases to your targets by supplying an object with an aliases array, e.g.
+List of aliases for this task
 
 ```js
 gulp.task('version', 'prints the version.', [], function() {
@@ -87,9 +80,11 @@ which results in
 
 ![](screenshot-aliases.png)
 
-## Options
+#### taskOptions.options
+
+Type: `Object`
 
-You can optionally pass options to your targets by supplying an object with an options object, e.g.
+Object documenting options which can be passed to your task
 
 ```js
 gulp.task('version', 'prints the version.', [], function () {
@@ -106,44 +101,15 @@ which results in
 
 ![](screenshot-options.png)
 
-## Override default help message
-
-```js
-require('gulp-help')(require('gulp'), { description: 'you are looking at it.', aliases: ['h', '?'] });
-```
-
-Then, calling
-
-```shell
-$ gulp      #or
-$ gulp help #or
-$ gulp h    #or
-$ gulp ?
-```
-
-will now result in
-
-![](screenshot-override-default.png)
+## require('gulp-help')(require('gulp'), options);
 
-## Post-help callback
+These are all the options available to be passed to the `gulp-help` instance, NOT individual tasks.
 
-You can define a function to run after the default help task runs.
-
-```js
-require('gulp-help')(gulp, {
-  afterPrintCallback: function(tasks) {
-    console.log(tasks);
-  }
-});
-```
-
-## Hide task dependencies
-
-By default, the dependencies of a task will be listed behind its help message. To hide them:
-
-```js
-require('gulp-help')(require('gulp'), {hideDepsMessage:true});
-```
+- `description` - modifies the default help message
+- `aliases` - adds aliases to the default help task
+- `hideEmpty` - hide all tasks with no help message defined. Useful when including 3rd party tasks
+- `hideDepsMessage` - hide all task dependencies
+- `afterPrintCallback` - a function to run after the default help task runs
 
 ## License