It would be cool to say that you cannot specify both result_id and subject/testcase. If you specify result_id you cannot specify subject/testcase and vice versa.

this parameter is required, it should be nice to write it somewhere

If the user doesn't specify the result_id he/she should specify the subject and the testcase. I would write also that.

Same thing as for the product-version (even if it's still not required...) but it will be.

Actually I think we should just leave this totally undocumented. We have only kept it in for backwards compatibility, right?

This is a bare role which is not what you want. Use file:/usr... role, or /usr... code markup.

Sorry I meant :file:/usr...

Yes. And we also said that at some point we would like to remove it completely, but we still didn't talk about it. So yes, probably is a good idea leave it undocumented.

It shouldn't be required for long (see #111).

Also shouldn't be required after #159 is merged.

I've add :file: to paths in FILES section.

The OPTIONS section is only taken from --help output. It definitely needs more details.

Also SYNOPSIS should be updated to show the required arguments (it should list multiple commands).

This is a fine start regardless. So :+1: if you want to merge as is and we can iterate on it from there, or post more changes on this PR first. Your choice.