Missing documentation for 'rules' and 'scheduler' in Test::Harness App::Prove

Here's a list of places where documentation "scheduling" and "rules" in TAP::Harness / App::Prove is known to be missing. It can be serve as a To-Do list to remedy the situation.

prove

• prove has a --rules flag, but is not documented. --rules can repeated multiple times and appears that it expects values like this: ** par=GLOB - indicates that the following file path, with glob-style wildcards, is able to run in parallel ** seq=GLOB - indicates that the following file path, with glob-style wildcards, must be run serially.
• App::Prove mentions 'rules' without further documentation. However, it's not clear that more is necessary here, if prove is properly documented.

TAP::Parser::Scheduler

• new() should document that it takes 2 arguments ** 'tests' - I think it's an arrayref of 2 element arrays, where the first element is the test name, and the second element is the test description. ** 'rules' - a hashref of "rule" data, defaulting to { par => '**' }. *** An explanation of the data structure should be linked to, if not included.
• The as_string() should include a simple of the output generated.
• Should link to TAP::Parser::Scheduler::Spinner and TAP::Parser::Scheduler::Job
• When the docs say "next job", I think they mean a TAP::Parser::Scheduler::Job object. This should be clarified.

TAP::Parser::Scheduler::Job

• new() contains a third argument, "context", which is not document
• The "$name" argument to new() should be clarified to be a file name.
• The docs refer to every method as a "Class Method". This appears to be a mistake. Only new() appears to be a class method.
• The "filename", "description", and "context" methods are all undocumented. They appear to be "Attributes".

TAP::Parser::Scheduler::Spinner

• Only new() is a class method

TAP::Harness

• The 'rules' data structure is shown but not documented. ** Do rules specify tests to run, or do they only specify "rules" about how to handle tests if the happen to be encountered?

Examples of mixing parallel and serial testing with prove

These examples are fittingly made to run on the Test-Harness test suite.

Run tests starting with "s" in parallel (2x), the rest in serial:

prove -l --rules='par=t/s*.t' -j2 t/*.t

Q & A

• Q: What if a particular test has no rule? ** It still gets run. Example:
  *** prove --rules='seq=t/p*.t' --rules='par=t/p*.t' -j2 t/regression.t
• Q: What if a particular test has conflicting rules, telling it both to run in parallel and in serial? ** It appears that first --rules mention "wins" *** This gets run in serial: prove --rules='seq=t/p*.t' --rules='par=t/p*.t' -j2 t/p*.t *** This runs in parallel: prove --rules='par=t/p*.t' --rules='seq=t/p*.t' -j2 t/p*.t