From db61f8f9673bb03a34ff55e3d8d31b7225c6f47d Mon Sep 17 00:00:00 2001
From: John R Barker <john@johnrbarker.com>
Date: Wed, 17 Jan 2018 14:02:06 +0000
Subject: [PATCH] Clarify which ping module to use (#34935)

* Clarify which ping module to use

Ensure each of the ping modules link to each other

ping - Requires Python on remote-node
nxos_ping - Only on Cisco NXOS
ios_ping - Only on Cisco IOS
net_ping - For network devices
win_ping - only for Windows
---
 lib/ansible/modules/network/ios/ios_ping.py    | 9 ++++++++-
 lib/ansible/modules/network/nxos/nxos_ping.py  | 7 +++++++
 lib/ansible/modules/network/system/net_ping.py | 5 +++++
 lib/ansible/modules/system/ping.py             | 6 ++++--
 lib/ansible/modules/windows/win_ping.py        | 2 ++
 5 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/lib/ansible/modules/network/ios/ios_ping.py b/lib/ansible/modules/network/ios/ios_ping.py
index d24296a2f2e..cee79a02dfd 100644
--- a/lib/ansible/modules/network/ios/ios_ping.py
+++ b/lib/ansible/modules/network/ios/ios_ping.py
@@ -13,9 +13,12 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: ios_ping
-short_description: Tests reachability using ping from IOS switch
+short_description: Tests reachability using ping from Cisco IOS network devices
 description:
 - Tests reachability using ping from switch to a remote destination.
+- For a general purpose network module, see the M(net_ping) module.
+- For Windows targets, use the M(win_ping) module instead.
+- For targets running Python, use the M(ping) module instead.
 author:
 - Jacob McGill (@jmcgill298)
 version_added: '2.4'
@@ -45,6 +48,10 @@ options:
     - The VRF to use for forwarding.
     required: false
     default: default
+notes:
+  - For a general purpose network module, see the M(net_ping) module.
+  - For Windows targets, use the M(win_ping) module instead.
+  - For targets running Python, use the M(ping) module instead.
 '''
 
 EXAMPLES = r'''
diff --git a/lib/ansible/modules/network/nxos/nxos_ping.py b/lib/ansible/modules/network/nxos/nxos_ping.py
index 9a9572088da..e5afc07f276 100644
--- a/lib/ansible/modules/network/nxos/nxos_ping.py
+++ b/lib/ansible/modules/network/nxos/nxos_ping.py
@@ -29,6 +29,9 @@ version_added: "2.1"
 short_description: Tests reachability using ping from Nexus switch.
 description:
     - Tests reachability using ping from switch to a remote destination.
+    - For a general purpose network module, see the M(net_ping) module.
+    - For Windows targets, use the M(win_ping) module instead.
+    - For targets running Python, use the M(ping) module instead.
 author:
     - Jason Edelman (@jedelman8)
     - Gabriele Gerbino (@GGabriele)
@@ -57,6 +60,10 @@ options:
             - Determines if the expected result is success or fail.
         choices: [ absent, present ]
         default: present
+notes:
+    - For a general purpose network module, see the M(net_ping) module.
+    - For Windows targets, use the M(win_ping) module instead.
+    - For targets running Python, use the M(ping) module instead.
 '''
 
 EXAMPLES = '''
diff --git a/lib/ansible/modules/network/system/net_ping.py b/lib/ansible/modules/network/system/net_ping.py
index ae1828e273e..13b3817a845 100644
--- a/lib/ansible/modules/network/system/net_ping.py
+++ b/lib/ansible/modules/network/system/net_ping.py
@@ -21,6 +21,8 @@ author: "Jacob McGill (@jmcgill298)"
 short_description: Tests reachability using ping from a network device
 description:
   - Tests reachability using ping from network device to a remote destination.
+  - For Windows targets, use the M(win_ping) module instead.
+  - For targets running Python, use the M(ping) module instead.
 options:
   count:
     description:
@@ -46,6 +48,9 @@ options:
     - The VRF to use for forwarding.
     required: false
     default: default
+notes:
+  - For Windows targets, use the M(win_ping) module instead.
+  - For targets running Python, use the M(ping) module instead.
 '''
 
 
diff --git a/lib/ansible/modules/system/ping.py b/lib/ansible/modules/system/ping.py
index f698d66f1e7..c8f96761cf0 100644
--- a/lib/ansible/modules/system/ping.py
+++ b/lib/ansible/modules/system/ping.py
@@ -21,11 +21,13 @@ short_description: Try to connect to host, verify a usable python and return C(p
 description:
    - A trivial test module, this module always returns C(pong) on successful
      contact. It does not make sense in playbooks, but it is useful from
-     C(/usr/bin/ansible) to verify the ability to login and that a usable python is configured.
-   - This is NOT ICMP ping, this is just a trivial test module.
+     C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured.
+   - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.
    - For Windows targets, use the M(win_ping) module instead.
+   - For Network targets, use the M(net_ping) module instead.
 notes:
    - For Windows targets, use the M(win_ping) module instead.
+   - For Network targets, use the M(net_ping) module instead.
 options:
   data:
     description:
diff --git a/lib/ansible/modules/windows/win_ping.py b/lib/ansible/modules/windows/win_ping.py
index 4c753460e80..15eaa1a7897 100644
--- a/lib/ansible/modules/windows/win_ping.py
+++ b/lib/ansible/modules/windows/win_ping.py
@@ -34,6 +34,7 @@ description:
   - Checks management connectivity of a windows host.
   - This is NOT ICMP ping, this is just a trivial test module.
   - For non-Windows targets, use the M(ping) module instead.
+  - For Network targets, use the M(net_ping) module instead.
 options:
   data:
     description:
@@ -42,6 +43,7 @@ options:
     default: pong
 notes:
   - For non-Windows targets, use the M(ping) module instead.
+  - For Network targets, use the M(net_ping) module instead.
 author:
 - Chris Church (@cchurch)
 '''