Help and documentation 'list of unicodes' inconsistent

[Martin Packman]

Documentation and help text refers to 'list of unicodes' for some params but what that means is undefined and inconsistent.

In tags= it can be either comma separated, or multiple params:

:param tags: List of tags the returned machine must have.
:type tags: list of unicodes
:param not_tags: List of tags the acquired machine must not have.
:type tags: List of unicodes.

$ maas $MAAS nodes acquire tags=a,b verbose=true dry_run=true
{"tags": ["No such tag(s): 'a', 'b'."]}

$ maas $MAAS nodes acquire tags=a tags=b verbose=true dry_run=true
{"tags": ["No such tag(s): 'a', 'b'."]}

Both correctly interpret as two tags, 'a' and 'b'.

But for networks/not_networks apparently it cannot be comma separated:

:param networks: List of networks (defined in MAAS) to which the
    machine must be attached. ...
:type networks: list of unicodes
:param not_networks: List of networks (defined in MAAS) to which the
    machine must not be attached. ...
:type not_networks: list of unicodes

$ maas $MAAS nodes acquire networks=space:1 verbose=true dry_run=true
No available node matches constraints: networks=endpoint-bindings-data-dummy:192.168.254.2/31(vid=0)

$ maas $MAAS nodes acquire networks=space:1,space:0 verbose=true dry_run=true
{"networks": ["No matching subnets found."]}

This is maas attempting to say the param couldn't be parsed, in a confusing manner.

$ maas $MAAS nodes acquire networks=space:1 networks=space:0 verbose=true dry_run=true
No available node matches constraints: networks=endpoint-bindings-data-dummy:192.168.254.2/31(vid=0),10.0.210.0/24:10.0.210.0/24(vid=0)

This is maas understanding the constraint correctly.

Also, 'unicode' would generally be treated as a maas-noun in english, so no 's' for the plural.

[Mike Pontillo (mpontillo)]

I agree; this is very confusing.

I was thinking of changing the documentation to read more like:

:param arch: Architecture of the returned machine (e.g. 'i386/generic',
    'amd64', 'armhf/highbank', etc.). If multiple architectures are
    specified, the machine to acquire may match any of the given
    architectures. To request multiple architectures, this parameter
    must be repeated in the request with each value.
:type arch: unicode (accepts multiple)
    ...
:param tags: The tag name(s) the machine to acquire must be tagged
    with. If multiple tag names are specified, the machine must be
    tagged with all of them. To request multiple tags, this parameter
    must be repeated in the request with each value.
:type tags: unicode (accepts multiple)

I already have a bug open to address documentation problems with constraints, so I might fix this under that one.