authorize_security_group_ingress documentation hard to parse
Closed this issue · 3 comments
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.
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.
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.
I suspect you are correct about two implementations. We've passed along the documentation feedback. Thanks!