Indicate commands taking multiple arguments in docs · RexOps/Rex · Discussion #1532

rwp0
Jun 19, 2022

For instance, the pkg command of Rex::Commands::Pkg module is able to take a arrayref as an argument to install multiple packages at once.

This prevents wrapping it with for loop for that end or using the less convenient install command.

It would be good to indicate such in the documentation instead of the current one

pkg($package, %options)

perhaps as duplicating as in the SYNOPSIS

pkg($package, %options)
pkg(@packages, %options)

or just by indicating the alternate arguments

pkg($package | @packages, %options)

Thanks for opening this discussion 👍

To summarize our previous chat about the topic for other readers:

we are already fixing the similar cases for Rex::Commands::File on [doc] Rex::Commands::File: correct optional argument syntax #1530 (without an issue, but it's getting clear now :) )
in a perfect world, the whole codebase would be audited for such clarification opportunities, but that sounds too huge as a scope and has less chances to be actually finished as a single task
there might be more similar cases discovered as @rwp0 goes through some use cases, and opening an issue plus a PR for each case could cause too much overhead through fragmenting the task into too small chunks
therefore let's collect the similar cases for a while here in this discussion, which enables us to discover the amount and types of documentation fixes that would be best to address as a first step

So, pkg is the first additional candidate (and/or perhaps even the whole of Rex::Commands::Pkg) :+1:

0 replies