snapshot: tweak snapshot-create-as diskspec docs

With this patch, it is hopefully a bit more obvious that for
snapshot-create-as, a literal '--diskspec' is mandatory if name
or description was omitted, but optional if all earlier options
were provided.

These all denote two diskspecs and a description:
virsh snapshot-create-as dom name desc vda vdb
virsh snapshot-create-as dom name desc --diskspec vda --diskspec vdb
virsh snapshot-create-as dom name desc --diskspec vda vdb
virsh snapshot-create-as dom name desc vda --diskspec vdb
virsh snapshot-create-as dom --diskspec vda --diskspec vdb name desc

This gives two diskspecs but no description:
virsh snapshot-create-as dom name --diskspec vda --diskspec vdb

And this treats 'vda' as the description, with only one diskspec:
virsh snapshot-create-as dom name vda vdb

The help output now shows:
    snapshot-create-as <domain> [<name>] [<description>] [--print-xml] [--no-metadata] [--halt] [--disk-only] [[--diskspec] <string>]...

I also checked the help output for echo and send-key, which are two
other variants of argv commands.

* tools/virsh.pod (snapshot-create-as): Document when a literal
--diskspec must preceed a diskspec argument.
* tools/virsh.c (vshCmddefHelp): Update help output for argv when
naming the option is useful.
(vshCmddefGetData): Fix logic on when argv was seen.
* tests/virsh-optparse: Add tests to avoid regressions.

1 files changed, 39 insertions, 2 deletions

diff --git a/tests/virsh-optparse b/tests/virsh-optparse
index cd5e3eb88..18252d295 100755
--- a/tests/virsh-optparse
+++ b/tests/virsh-optparse
@@ -80,13 +80,50 @@ cat <<\EOF > exp-out || framework_failure
   </disks>
 </domainsnapshot>
 
-
 EOF
-virsh -c $test_url snapshot-create-as --print-xml test \
+virsh -q -c $test_url snapshot-create-as --print-xml test \
   --diskspec 'vda,file=a&b,,c,snapshot=external' --description '1<2' \
   --diskspec vdb >out 2>>err || fail=1
 compare out exp-out || fail=1
 
+cat <<\EOF > exp-out || framework_failure
+<domainsnapshot>
+  <name>name</name>
+  <description>vda</description>
+  <disks>
+    <disk name='vdb'/>
+  </disks>
+</domainsnapshot>
+
+EOF
+virsh -q -c $test_url snapshot-create-as  --print-xml test name vda vdb \
+  >out 2>>err || fail=1
+compare out exp-out || fail=1
+
+cat <<\EOF > exp-out || framework_failure
+<domainsnapshot>
+  <name>name</name>
+  <description>desc</description>
+  <disks>
+    <disk name='vda'/>
+    <disk name='vdb'/>
+  </disks>
+</domainsnapshot>
+
+EOF
+for args in \
+    'test name desc vda vdb' \
+    'test name desc --diskspec vda vdb' \
+    'test name desc --diskspec vda --diskspec vdb' \
+    'test name desc vda vdb' \
+    'test --diskspec vda name --diskspec vdb desc' \
+    '--description desc --name name --domain test vda vdb' \
+; do
+  virsh -q -c $test_url snapshot-create-as --print-xml $args \
+    >out 2>>err || fail=1
+  compare out exp-out || fail=1
+done
+
 test -s err && fail=1
 
 (exit $fail); exit $fail