Filtering by tag documentation is confusing.

[glennpratt]

The highlighting on the filter by tag documentation is confusing (to me at least).

http://docs.aws.amazon.com/sdkforruby/api/Aws/EC2/Resource.html#volumes-instance_method

The highlighting and equal sign had me banging my head against the desk doing:

query = {:filters=>[{:name=>"tag", :values=>["stage=gpratt"]}]}
# => Aws::EC2::Errors::InvalidParameterValue: The filter 'tag' is invalid

When the right answer is:

{:filters=>[{:name=>"tag:stage", :values=>["gpratt"]}]}

[awood45]

Thanks for the documentation feedback - I can see the formatting of the shared documentation is confusing here, and we might need something custom.

[trevorrowe]

To add some context, the API reference documentation for each service is shared from the service API documentation. In this scenario, the service API reference documentation mentions how things are serialized on over the wire, which includes the querystring formatting of key/value pairs which the SDK does for you. This causes the confusion. This sometimes happens as well when service documentation references names sent over the wire which are actually snake_cased in the SDK.

I'm not sure what we can or should do here. I agree, the documentation is confusing at best and basically wrong for Ruby SDK users. Hand maintaining corrections in our library would be difficult at best, as we would need a way to keep this up to date. We could explore writing a documentation plugin that attempts to detect these situations and correct, but I don't think we would be able to catch 100% of miss-matches. A targeted patch/plugin for the EC2 tags documentation is possible, but it is difficult to guess how the source documentation may be changed over-time, potentially breaking said plugin.

I'm open to suggestions.

[Doug-AWS]

I just added an example of using tags to filter ECS instances with a specific tag value. See "Getting Information about All Instances with a Specific Tag Value" in http://docs.aws.amazon.com/sdk-for-ruby/latest/DeveloperGuide/aws-ruby-sdk-recipes.html#aws-ruby-sdk-ec2-recipes.

[trevorrowe]

I've also submitted an SDK specific example that will appear in the API reference documentation for #describe_instances. This should be published with our next release.