(In reply to Marina from comment #0)
> When trying to create a bond using rhevm-shell
> cannot specify multiple options for --bonding-options-option argument on
> rhevm-shell as within other collection objects and need to separate each
> option as a different argument.
> 
> For instance:
> ~~~
> [RHEVM shell (connected)]# add nic --host-identifier
> 02400a03-c3d0-4be8-8b06-452b1aa9c692 --network-name VMnet \
> --name bond0  --bonding-slaves-host_nic
> "host_nic.name=eth3,host_nic.name=eth2" \
> --bonding-options-option
> "option.name=mode,option.value=1;option.name=miimon,option.value=100"
> ~~~
> Would result in the error:
> ~~~
> error: invalid syntax at "--bonding-options-option", see help on collection
> based arguments for more details.
> ~~~
> 
> The command will work only if you do:
> ~~~
> --bonding-options-option "option.name=mode,option.value=1" \
> --bonding-options-option "option.name=miimon,option.value=100"
> ~~~
> 
> 
> If you consider this as not a bug, but expected behaviour, please explain
> the logic. 

obviously this is by design, every collection based argument should have
own option as you specified above ^, this is done to create clear isolation
between options, just think of curl utility, it has -H option for every
header you specify, and not -H "a:foo; b:fah; c:fee" ...

> So far, it is very not user friendly. And maybe we should change
> the help output.
> How bonding-slaves-host_nic collection is different from
> bonding-options-option?
> 

not sure i understand your question, but as you see collection based
format is listed bellow [1], and it is the same all over the shell + at help
you can see collection based items with possible properties [2],

[1] you specify single collection element (with it's items) peer shell option

> 
> COLLECTION BASED OPTION FORMAT
> 
>     * [--x-y: collection]      
>       {
>         [y.a: string]
>         [y.b: string]
>         [y.c: string]
>       }
> 
>     e.g:
> 
>     --x-y "y.a=a1,y.b=b1,y.c=c1"
>     --x-y "y.a=a2,y.b=b2,y.c=c2"
>     ...

[2]

>    * [--bonding-options-option: collection]
>      {
>        [option.name: string]
>        [option.value: string]
>        [type: string]
>      }

So, how is it different from this collection:

    * --bonding-slaves-host_nic: collection
      {
        host_nic.id|name: string
      }

?


Michael, before we close a bug, let's confirm it is clear what is happening.
The fact that it came from the customer, means, the help was not clear and there is always a place for improving. Reopening. 
I do not say, there is a bug in the code, but the documentation is not clear.

Maybe we should make a differentiation between simple collection object(like bonding-slaves-host_nic), that all values for it can be specified on one line, and a complex collection object(like bonding-options-option), that will require a special line for each option.

Please catch me on irc(mku) or email, if you would like to discuss this further, before closing this bug again.

Michael,

I'm the owner on the case this bug is attached to, and have seen other customers run into problems understanding proper formatting as well.

Like Marina just pointed out, I think what hung both the customer and myself up was the formatting for these parameters. It was not immediately clear to the customers, case owners, or our Virt SEG that one collection-based parameter (slaves) allows you to specify all options in one string, but the other (bonding options) parameter must be declared multiple times.

I feel that while this may not be a bug in the program itself (as we were able to get this working), the bug should be more of a request for a more clear help page within the shell itself.

More from customer's feedback:
"In my cli adventures I've found there is a massive disconnect between the online documentation, the command help documentation and what actually works on the command line.
Those 3 have got to be synced up eventually." This is just FYI, not really related to this bug.

(In reply to Marina from comment #3)
> So, how is it different from this collection:
> 
>     * --bonding-slaves-host_nic: collection
>       {
>         host_nic.id|name: string
>       }
> 
> ?
> 

marina,

sorry, but i'm not sure i understand your question, there is no difference
between the told above & this example, just it has different content to be
specified.


* --bonding-slaves-host_nic: collection <----- means that you can specify a
                                               collection of these options,
                                              (note it marked as 'collection'..)
    {
       host_nic.id|name: string         <----- this is actually content that
                                               has to be specified for this
                                               option
    }

> 
> Michael, before we close a bug, let's confirm it is clear what is happening.
> The fact that it came from the customer, means, the help was not clear and
> there is always a place for improving. Reopening. 
> I do not say, there is a bug in the code, but the documentation is not clear.
> 
> Maybe we should make a differentiation between simple collection object(like
> bonding-slaves-host_nic), that all values for it can be specified on one
> line, and a complex collection object(like bonding-options-option), that
> will require a special line for each option.

this would create inconsistency in application what will make it error
prone and complex to use.

(In reply to wdaniel from comment #4)
> Michael,
> 
> I'm the owner on the case this bug is attached to, and have seen other
> customers run into problems understanding proper formatting as well.
> 
> Like Marina just pointed out, I think what hung both the customer and myself
> up was the formatting for these parameters. It was not immediately clear to
> the customers, case owners, or our Virt SEG that one collection-based
> parameter (slaves) allows you to specify all options in one string, but the
> other (bonding options) parameter must be declared multiple times.
> 
> I feel that while this may not be a bug in the program itself (as we were
> able to get this working), the bug should be more of a request for a more
> clear help page within the shell itself.

currently help using generic [1] to describe the collection pattern and in
command where collection based options available, they described like [2],
if you find it not clear enough, I'm open for suggestions.

[1]

COLLECTION BASED OPTION FORMAT
  
    * [--x-y: collection]
      {
        [y.a: string]
        [y.b: string]
        [y.c: string]
      }
  
    e.g:
  
    --x-y "y.a=a1,y.b=b1,y.c=c1"
    --x-y "y.a=a2,y.b=b2,y.c=c2"
    ...
  
    where a, b, c are option properties and aN, bN, cN is actual user's data

[2]

[oVirt shell (connected)]# help add vm

....

     * [--os-boot: collection]
       {
         [boot.dev: string]
       }
     * [--custom_properties-custom_property: collection]
       {
         [custom_property.name: string]
         [custom_property.value: string]
       }
...

(In reply to Marina from comment #5)
> More from customer's feedback:
> "In my cli adventures I've found there is a massive disconnect between the
> online documentation, the command help documentation and what actually works
> on the command line.
> Those 3 have got to be synced up eventually." This is just FYI, not really
> related to this bug.

Marina,

i figured out that this is a documentation issue rather than bug, and this
why i closed this BZ (i assumed that you'll file new one for documentation folks)

Michael,

Thank you for your time on the phone today.
It is clear now.
So, the right way for any collection object would be to specify every single object separately, i.e.:
--bonding-slaves-host_nic "host_nic.name=eth1" --bonding-slaves-host_nic "host_nic.name=eth2"

I will update our internal kcs solution with this and let customer know.
https://bugzilla.redhat.com/show_bug.cgi?id=1015318

I think there is nothing we can do at this point with this bug, but closing it.