authorize_security_group_ingress documentation hard to parse

[garethr]

The SDK docs around authorize_security_group_ingress at
http://docs.aws.amazon.com/sdkforruby/api/frames.html are difficult to follow. Specifically:

• Having to_port, from_port and cidr_ip at the top level and within each ip_permission makes it difficult to determine which to use, and also what happens when both are used?
• The ip_protocol at the top level can take a -1 argument, but it doesn't appear the one nested in ip_permissions can
• I assume you can specify a group_name OR a group_id within user_id_group_pairs but it's not clear from the documentation
• The behaviour when parameters are not passed is undefined, and only group_id is required

Ultimately, this method feels like two separate implementations tied together.

This stood out as the rest of the SDK I've used (for https://github.com/garethr/puppetlabs-aws) has been obvious in use, even without referring to the documentation in many cases.

[awood45]

Our API docs are directly generated from the service API docs, which includes a few examples that may help. What I can do is forward this on to the EC2 doc teams to see if they can add clarity to the function description.

[garethr]

All of the samples on that page use the nested ip_permissions array, non of them use the top-level attributes. Which reinforces the feeling that it's two parallel implementations, maybe for backwards compatibility. Even just stating that or deprecating those bits, would be a useful signal.

[trevorrowe]

I suspect you are correct about two implementations. We've passed along the documentation feedback. Thanks!