Feature request: Add descriptions to tasks

[oscarotero]

Hi. I think it would be great to include descriptions to deno tasks, and show these descriptions on run deno task. For example, the following tasks:

{
  "tasks": {
    "format": "deno fmt .",
    "lint": "deno lint ."
  }
}

Could be also defined as following:

{
  "tasks": {
    "format": {
      "run": "deno fmt .",
      "description": "Format the code",
    },
    "lint": {
      "run": "deno lint .",
      "description": "Lint the code",
    }
  }
}

And show these descriptions by running deno task:

Available tasks:
  format         Format the code
  lint           Lint the code

The use of objects to define tasks (with run and description properties for now) could be extended in the future with more options (like cwd for example).

[sigmaSd]

Here is a poc for this https://github.com/denoland/deno/compare/main...sigmaSd:tasksUp?expand=1

I wonder if its possible to support both the current and this requested schema and I wonder if that's a desirable thing to do.

[oscarotero]

Someone had the same idea before: #14084

[kitsonk]

I'm in favour of this, I was going to actually raise an issue about this, as it improves the DX a lot more than #15241

ping @bartlomieju

[dsherret]

A point brought up by @crowlKats is that this can be expressed with a comment in the configuration file. Also that tasks and names should be descriptive enough on their own, and if they're not then at that point a comment can be added.

I agree with that and don't think we should add this property unless we have another reason for introducing object notation.

[oscarotero]

Comments are available only in .jsonc format, so it's a broken solution to me, because it's not compatible with all file formats supported to configure Deno.
Also, AFAIK there's no support in std library to stringify data in JSONC, only parse, so there's no way to create or modify an existing jsonc file with deno.

FYI, Lume creates/modify the deno configuration file to add the import map and tasks and it doesn't support JSONC for this reason: lumeland/lume#211 (comment)

[nayeemrmn]

Comments are available only in .jsonc format, so it's a broken solution to me, because it's not compatible with all file formats supported to configure Deno.

But jsonc exists for when you want to add comments, and that's why it's supported. The std lib can always be improved.

[oscarotero]

To me, a tasks description is a value that configure how this task should be displayed when the user run deno task. A comment in a jsonc can be anthing: a private comment like // todo: refactor this task, a previous comment that have been disabled, like:

{
    tasks: {
        //"format": "deno fmt .",
        "lint": "deno lint ."
    }
}

... etc. I wouldn't mix both things. The deno configuration (no matter the format used) should be based in real values. Treating comments like they were configuration values looks hacky to me.

[crowlKats]

Closing as a PR was made but closed due to there being a consensus of not wanting to do this, and jsonc should be the way to achieve this.

[dsherret]

Something similar to this proposal is now done in #23101 (displays the comments when running deno task)

[oscarotero]

@dsherret I think using jsonc comments is a bad idea because it's mixing commented code that you don't want to use with task descriptions.

And, in addition to that, the jsonc parser of std removes the comments, so it's not possible to edit the file without removing these descriptions.

Object notation is a stronger way to have this.

[dsherret]

I think using jsonc comments is a bad idea because it's mixing commented code that you don't want to use with task descriptions.

The output shows the comments as comments. I'm not sure why someone would comment above a task and not want that displayed when someone runs deno task.

And, in addition to that, the jsonc parser of std removes the comments, so it's not possible to edit the file without removing these descriptions.

The jsonc parser in std is severely lacking and should be improved to handle comments better. I don't think it should be a reason to drive the decision here. jsonc-parser on npm is much better for making modifications to jsonc files, for example.

[oscarotero]

The output shows the comments as comments. I'm not sure why someone would comment above a task and not want that displayed when someone runs deno task.

Well, let's say I have 3 tasks, but I want to disable, temporarily one of them for some reason.

{
  "tasks": {
    "format": "deno fmt .",
    // "lint": "deno lint .",
    "test": "deno test ."
  }
}

Now the commented lint task becomes the description of test task.

[dsherret]

Good point! I opened #23104 to improve it.

[oscarotero]

This is just an example, but what I want to say is the use of comments for task descriptions is a very weak approach because there are many edge cases that cause unexpected behaviors. It's not portable, because it doesn't work with json, only jsonc.
Allowing only block comments formats like this can help:

{
  "tasks": {
    "format": "deno fmt .",
    // "lint": "deno lint .",
    /** Task description */
    "test": "deno test ."
  }
}

But my opinion is it should be a json field. It's the most robust, portable and predictible.

[dsherret]

This was added in Deno 2.1 and comments were removed from the output https://deno.com/blog/v2.1#turbocharged-deno-task (we had a reason for object notation)

[oscarotero]

Great! Thanks for implementing it!