[doc] desc command doesn't mention documenting batch as well as task

[rwp0]

trafficstars

Describe the bug

desc says:

Set the description of a task.

desc "This is a task description of the following task";
task "mytask", sub {
  say "Do something";
}

but it also describes batches as well as seen in rex -T output.

I don't know if the desc is used anywhere else (apart from the -T output).

Expected behavior

Mention describing batches and give a code example in addition to task.

How to reproduce it

• perldoc Rex::Commands
• read Rex::Commands::desc
• run rex -T with a Rexfile contaning a task and a batch with their description set (to witness both are being documented)

Code example

No response

Additional context

I initially thought desc is part of task, and hence was wondering for a while why it was not including as a docstring implemented as another option argument of the task command instead of preceding it as a separate independent command.

Rex::Commands synopsis section also implies documenting task only:

desc "Task description";
task "taskname", sub { ... };
task "taskname", "server1", ..., "server20", sub { ... };

I'm not aware if desc will document anything else as well such as hosts, groups, and so on.

Looking at the source seem like environment command uses desc as well, but I haven't been using that so far, hence not sure what it really is.

Rex version

1.13.4

Perl version

5.36.0

Operating system running rex

Debian 11

Operating system managed by rex

FreeBSD

How rex was installed?

cpan client

[ferki]

Thank you for the detailed bug report, @rwp0! :heart:

Your analysis is correct: desc can also provide a description for batches and environments, not just tasks. These cases are indeed not mentioned in the docs, neither in the code example there.

Since the code example would be touched as well, it would be also a good opportunity to clean up the style of the related code example as a secondary optional goal (e.g. use single quotes instead of double quotes when nothing is interpolated, use 4 spaces indent instead of 2, etc.).