Defining tasks with description

[allenhwkim]

I see gulp -T and gulp --tasks-simple provides list of tasks like the following

$ gulp --tasks-simple
clean
build:js
build:css
docs
watch
build
test

I wished that it looked like the following

$ gulp -T
clean      clear build directory
build:js   build minified javascript
build:css  build css from sass files
docs       generate documentation
watch      run monitoring tasks for .js and .sass
build      run all build tasks
test       run a test

From the API documentation, I see task "description" is not a part of gulp.task parameters since syntax is like this gulp.task(name[, deps], fn)

I googled around if defining description for gulp.task is possible, then find this help plugin that overwrites gulp.task and accepts description as help.

I think it is a good idea to accept description like the following and wished it was the core feature of gulp without using extra plugin.

gulp.task(name[, description, deps, fn, taskOptions])

[yocontra]

No, this issue has been raised about 20 times. Please read those threads for more info.

[allenhwkim]

No because of not worth having this feature or no because it's already planned?

I could not find the relative thread.

Are you talking about new task system, #355?

I searched
https://github.com/gulpjs/gulp/search?q=gulp+tasks&type=Issues and
https://github.com/gulpjs/gulp/search?q=gulp+tasks+description&type=Issues

Still not able to find one from 546 closed tasks.

Could you find me one plz?

I forgot to say thank you for making gulp.

[yocontra]

https://github.com/gulpjs/gulp/search?q=description&type=Issues

[yocontra]

tl;dr it's not planned to be a part of the task system itself, but the CLI will support functions with .description and .name properties in gulp 4

[mnpenner]

Just FYI this thread is the top hit on Google and searching the gulp issues for "description" only yields one useful result other than this one.

I'm glad this is planned for Gulp 4 👍

[yocontra]

@phated This should be added to the CLI when printing the task tree. If a description property exists it should be included.

[phated]

I see this causing more problems than benefits. I was thinking this would be supported by custom registries. @contra thoughts?

[yocontra]

@phated Custom registries wouldn't solve this AFAIK because the task tree logging would still not print the attributes attached to the function. I think if any custom attributes are tacked onto the task function we should log them in --tasks

[phated]

@contra with the logging changes, we could just have custom registries log the information, right?

[yocontra]

@phated How do custom registries play into the taskTree stuff in the CLI? Is the string representation of the tree handled by the registry?

[phated]

@contra you have to call .tree() on undertaker which calls .tasks() on the custom registry to get the list of tasks. Descriptions could be logged when that is called. Might be weird though. Let me think on it some more.

[phated]

example of something I think would cause issues to be opened:

function clean(){ /* clean stuff */ }
clean.description = 'Clean the built files';

var cleanOnce = once(clean);

gulp.task(cleanOnce); // <- no description is available on the once function

[yocontra]

@phated Sure it would confuse people, that is an easy fix though and could be cleared up by good docs

[heikki]

Is it necessary to be able to set it for every function? Rake/Jake have this style:

gulp.desc('Clean the built files');
gulp.task('clean', function() {
  /* clean stuff */
});

• http://ruby-doc.org/core-1.9.3/doc/rake/rakefile_rdoc.html#label-Comments
• http://jakejs.com/docs#tasks.

[yocontra]

@heikki That's so bad for a lot of reasons, but now we have to maintain state for task declarations which is very funky. jake is not a great place to look for inspiration

[heikki]

True that. Adding another command again feels wrong too. This is probably bad too but let's try.. 😄

gulp.task('Clean the built files', function clean() {
    /* clean stuff */
});

--edit

Well, that's close to gulp-help syntax. I don't really need descriptions but if the feature is there it's usage should look nice.

[darsain]

Maybe task() could create and return task object with methods and stuff:

function clean() {}

gulp.task(clean)
  .description('This cleans.');

That could be extended with more useful stuff, like:

function serve() {
  startServer('.', gulp.argv.port);
}

gulp.task(serve)
  .description('Start server.');
  .arg('p', 'port', 8080); // -n, --name, default value

i.e. gulp taking over CLI arguments, instead of leaving it on developers to reimplement, and hope it won't collide (ehm #780).

Or is this going too far? :)

[phated]

going too far. argv has been deprecated forever

[Aetet]

Maybe

gulp.task('clean', function () {}, 'Clean this mess')

Argument after function and make it optional. Or it will be too hackish to parse so much args? This won't force using comments, but let add your own description.

Or it can be:

gulp.loadDescriptions({
  clean: 'Clean this stuff',
  build: 'Some build task'
})

So actuality of this object will be on users.

[blvz]

Maybe having something more 'manual' like gulp.loadDescriptions, would simplify issues like #851.

[phated]

No, if we support anything, it will be a description property on the task function.

[ilanbiala]

Any progress on this?

[yocontra]

@ilanbiala No need to keep adding "Any progress on this?" to every issue - the last response in this thread was 9 hrs ago saying there will be support for it. Please don't spam.

[ilanbiala]

@contra sorry if it seems spammy, the most recent comment just seemed like he was still making a decision or had to discuss something so I wanted to see if anything final had been decided regarding the implementation. @phated can you clear up what the confusion might be if something like concat.description = 'concatenate JS' were to be implemented and used as a property of the given function?

[dinoboff]

With gulp 4 currently, you could do something like:

function _(description, fn) {
  fn.description = description;
  return fn;
}

gulp.task(_('clean all the things', function clean(done) {
  done();
}));

gulp.task('build', _('build all the things',
  gulp.series('clean', function(done) {
    done();
  }
)));

gulp.task(_('show this help message', function help(done) {
  var tasks = gulp.registry().tasks();

  Object.keys(tasks).forEach(function(name) {
    console.log(name, gulp.get(name).description);
  });

  done();
}));

[yocontra]

@phated Is this implemented in the CLI yet? Can I close this?

[phated]

@contra no, this isn't in the CLI - I will open an issue there and redirect this one to that. I feel like it is a good issue for a community member to pick up.

[phated]

New issue opened at gulpjs/gulp-cli#19

[phated]

This just landed in the gulp-cli 4.0 branch

[khitrenovich]

For those who read this thread in 2019+ - gulp-help is not compatible with Gulp 4.

[phated]

https://gulpjs.com/docs/en/api/task#task-metadata