Repository: ansible/ansible-modules-core

Issue:
ec2_eip docs do not explain ip and public_ip parameters correctly
##### Issue Type:
- Documentation Report
##### Ansible Version:

```
ansible 2.0.1.0
  config file =
  configured module search path = Default w/o overrides
```
##### Ansible Configuration:
##### Environment:

control: MacOSX El Capitan
target: RHEL7 on AWS
##### Summary:

Documentation for ec2_eip here:
http://docs.ansible.com/ansible/ec2_eip_module.html

Examples use the parameter "ip" which is not listed in the parameter table. 
Parameter table shows "public_ip" but its use is unclear.
##### Steps To Reproduce:
##### Expected Results:
##### Actual Results:



Discussion:
<!-- @slimandslam: Thanks for filing this documentation report! -->

@rickmendes ping, this issue is waiting for your response.
[click here for bot help](https://github.com/jctanner/ansibullbot/blob/ISSUE_TRIAGE_CLASS/ISSUE_HELP.md)

<!--- boilerplate: issue_bug_new --->


Resolving patch:
diff --git a/cloud/amazon/ec2_eip.py b/cloud/amazon/ec2_eip.py
--- a/cloud/amazon/ec2_eip.py
+++ b/cloud/amazon/ec2_eip.py
@@ -17,9 +17,10 @@
 DOCUMENTATION = '''
 ---
 module: ec2_eip
-short_description: associate an EC2 elastic IP with an instance.
+short_description: manages EC2 elastic IP (EIP) addresses.
 description:
-    - This module associates AWS EC2 elastic IP addresses with instances
+    - This module can allocate or release an EIP.
+    - This module can associate/disassociate an EIP with instances or network interfaces.
 version_added: "1.4"
 options:
   device_id:
@@ -30,13 +31,15 @@
     version_added: "2.0"
   public_ip:
     description:
-      - The elastic IP address to associate with the instance.
-      - If absent, allocate a new address
+      - The IP address of a previously allocated EIP.
+      - If present and device is specified, the EIP is associated with the device.
+      - If absent and device is specified, the EIP is disassociated from the device.
     required: false
+    aliases: [ ip ]
   state:
     description:
-      - If present, associate the IP with the instance.
-      - If absent, disassociate the IP with the instance.
+      - If present, allocate an EIP or associate an existing EIP with a device.
+      - If absent, disassociate the EIP from the device and optionally release it.
     required: false
     choices: ['present', 'absent']
     default: present
@@ -48,7 +51,7 @@
     version_added: "1.4"
   reuse_existing_ip_allowed:
     description:
-      - Reuse an EIP that is not associated to an instance (when available), instead of allocating a new one.
+      - Reuse an EIP that is not associated to a device (when available), instead of allocating a new one.
     required: false
     default: false
     version_added: "1.6"
@@ -64,8 +67,8 @@
 author: "Rick Mendes (@rickmendes) <rmendes@illumina.com>"
 notes:
    - This module will return C(public_ip) on success, which will contain the
-     public IP address associated with the instance.
-   - There may be a delay between the time the Elastic IP is assigned and when
+     public IP address associated with the device.
+   - There may be a delay between the time the EIP is assigned and when
      the cloud instance is reachable via the new address. Use wait_for and
      pause to delay further playbook execution until the instance is reachable,
      if necessary.
@@ -93,7 +96,7 @@
 - name: another way of allocating an elastic IP without associating it to anything
   ec2_eip: state='present'
 - name: provision new instances with ec2
-  ec2: keypair=mykey instance_type=c1.medium image=emi-40603AD1 wait=yes'''
+  ec2: keypair=mykey instance_type=c1.medium image=ami-40603AD1 wait=yes'''
 ''' group=webserver count=3
   register: ec2
 - name: associate new elastic IPs with each of the instances


Test patch: