Mutually reference Windows and non-Windows modules (#25482)

* Mutually reference Windows and non-Windows modules

To make it easier for Windows or non-Windows users to find the relevant
module information, we are mutually referencing both variants in their
documentation.

We are also adding a special note if a module works on both Windows and
non-Windows targets.

* Mutually reference Windows and non-Windows modules

To make it easier for Windows or non-Windows users to find the relevant
module information, we are mutually referencing both variants in their
documentation.

We are also adding a special note if a module works on both Windows and
non-Windows targets.

* Replace 'look at' with 'use', as requested

ci_complete

lib/ansible/modules/windows/win_command.py

@@ -35,6 +35,7 @@ description:
        processed through the shell, so variables like C($env:HOME) and operations
        like C("<"), C(">"), C("|"), and C(";") will not work (use the M(win_shell)
        module if you need these features).
+     - For non-Windows targets, use the M(command) module instead.
 options:
   free_form:
     description:
@@ -57,6 +58,7 @@ notes:
       environment.
     - C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not
       exist, use this.
+    - For non-Windows targets, use the M(command) module instead.
 author:
     - Matt Davis
 '''

lib/ansible/modules/windows/win_copy.py

@@ -31,6 +31,7 @@ version_added: "1.9.2"
 short_description: Copies files to remote locations on windows hosts.
 description:
 - The C(win_copy) module copies a file on the local box to remote windows locations.
+- For non-Windows targets, use the M(copy) module instead.
 options:
   content:
     description:
@@ -72,6 +73,8 @@ options:
       to destination. Otherwise, if it does not end with "/", the directory
       itself with all contents is copied. This behavior is similar to Rsync.
     required: true
+notes:
+- For non-Windows targets, use the M(copy) module instead.
 author: "Jon Hawkesworth (@jhawkesworth)"
 '''
 

lib/ansible/modules/windows/win_file.py

@@ -33,7 +33,9 @@ description:
      - Creates (empty) files, updates file modification stamps of existing files,
        and can create or remove directories.
      - Unlike M(file), does not modify ownership, permissions or manipulate links.
+     - For non-Windows targets, use the M(file) module instead.
 notes:
+    - For non-Windows targets, use the M(file) module instead.
     - See also M(win_copy), M(win_template), M(copy), M(template), M(assemble)
 requirements: [ ]
 author: "Jon Hawkesworth (@jhawkesworth)"

lib/ansible/modules/windows/win_find.py

@@ -31,6 +31,7 @@ short_description: return a list of files based on specific criteria
 description:
     - Return a list of files based on specified criteria.
     - Multiple criteria are AND'd together.
+    - For non-Windows targets, use the M(find) module instead.
 options:
     age:
         description:
@@ -113,6 +114,8 @@ options:
         required: false
         default: false
         choices: ['true', 'false']
+notes:
+    - For non-Windows targets, use the M(find) module instead.
 author: "Jordan Borean (@jborean93)"
 '''
 

lib/ansible/modules/windows/win_get_url.py

@@ -33,6 +33,7 @@ version_added: "1.7"
 short_description: Fetches a file from a given URL
 description:
  - Fetches a file from a URL and saves to locally
+ - For non-Windows targets, use the M(get_url) module instead.
 author:
     - "Paul Durivage (@angstwad)"
     - "Takeshi Kuramochi (tksarah)"
@@ -90,6 +91,8 @@ options:
       - Proxy authentication password
     version_added: "2.0"
     required: false
+notes:
+ - For non-Windows targets, use the M(get_url) module instead.
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_group.py

@@ -32,7 +32,8 @@ module: win_group
 version_added: "1.7"
 short_description: Add and remove local groups
 description:
-    - Add and remove local groups
+    - Add and remove local groups.
+    - For non-Windows targets, please use the M(group) module instead.
 options:
   name:
     description:
@@ -55,6 +56,8 @@ options:
       - absent
     default: present
     aliases: []
+notes:
+    - For non-Windows targets, please use the M(group) module instead.
 author: "Chris Hoffman (@chrishoffman)"
 '''
 

lib/ansible/modules/windows/win_package.py

@@ -38,6 +38,7 @@ description:
        Use a product_id to check if the package needs installing. You can find product ids for installed programs in the windows registry
        either in C(HKLM:Software\Microsoft\Windows\CurrentVersion\Uninstall) or for 32 bit programs
        C(HKLM:Software\Wow6432Node\Microsoft\Windows\CurrentVersion\Uninstall)
+     - For non-Windows targets, use the M(package) module instead.
 options:
   path:
     description:
@@ -88,6 +89,8 @@ options:
       - If not provided, defaults to 0
     required: no
     default: 0
+notes:
+     - For non-Windows targets, use the M(package) module instead.
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_ping.py

@@ -30,14 +30,18 @@ DOCUMENTATION = r'''
 ---
 module: win_ping
 version_added: "1.7"
-short_description: A windows version of the classic ping module.
+short_description: A windows version of the classic ping module
 description:
-  - Checks management connectivity of a windows host
+  - 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.
 options:
   data:
     description:
       - Alternate data to return instead of 'pong'
     default: 'pong'
+notes:
+  - For non-Windows targets, use the M(ping) module instead.
 author: "Chris Church (@cchurch)"
 '''
 

lib/ansible/modules/windows/win_service.py

@@ -32,7 +32,8 @@ module: win_service
 version_added: "1.7"
 short_description: Manages Windows services
 description:
-    - Manages Windows services
+    - Manages Windows services.
+    - For non-Windows targets, use the M(service) module instead.
 options:
   dependencies:
     description:
@@ -117,6 +118,8 @@ options:
       - The username to set the service to start as.
       - This and the C(password) argument must be supplied together.
     version_added: "2.3"
+notes:
+    - For non-Windows targets, use the M(service) module instead.
 author: "Chris Hoffman (@chrishoffman)"
 '''
 

lib/ansible/modules/windows/win_shell.py

@@ -33,6 +33,7 @@ description:
      - The C(win_shell) module takes the command name followed by a list of space-delimited arguments.
        It is similar to the M(win_command) module, but runs
        the command via a shell (defaults to PowerShell) on the target host.
+     - For non-Windows targets, use the M(shell) module instead.
 options:
   free_form:
     description:
@@ -60,8 +61,10 @@ notes:
    -  WinRM will not return from a command execution until all child processes created have exited.
       Thus, it is not possible to use C(win_shell) to spawn long-running child or background processes.
       Consider creating a Windows service for managing background processes.
+   - For non-Windows targets, use the M(shell) module instead.
+   - See also M(win_command), M(raw)
 author:
-    - Matt Davis
+    - Matt Davis (@nitzmahone)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_stat.py

@@ -28,7 +28,8 @@ module: win_stat
 version_added: "1.7"
 short_description: returns information about a Windows file
 description:
-     - Returns information about a Windows file
+     - Returns information about a Windows file.
+     - For non-Windows targets, use the M(stat) module instead.
 options:
     path:
         description:
@@ -59,6 +60,8 @@ options:
         default: sha1
         choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512']
         version_added: "2.3"
+notes:
+     - For non-Windows targets, use the M(stat) module instead.
 author: "Chris Church (@cchurch)"
 '''
 

lib/ansible/modules/windows/win_tempfile.py

@@ -31,6 +31,7 @@ author: Dag Wieers (@dagwieers)
 short_description: Creates temporary files and directories.
 description:
   - Creates temporary files and directories.
+  - For non-Windows targets, please use the M(tempfile) module instead.
 options:
   state:
     description:
@@ -50,6 +51,8 @@ options:
     description:
       - Suffix of file/directory name created by module.
     default: ''
+notes:
+  - For non-Windows targets, please use the M(tempfile) module instead.
 '''
 
 EXAMPLES = r"""

lib/ansible/modules/windows/win_unzip.py

@@ -35,6 +35,7 @@ description:
 - Unzips compressed files and archives.
 - Supports .zip files natively
 - Supports other formats supported by the Powershell Community Extensions (PSCX) module (basically everything 7zip supports)
+- For non-Windows targets, use the M(unarchive) module instead.
 requirements:
 - PSCX
 options:
@@ -75,6 +76,7 @@ notes:
 - For extracting any compression types other than .zip, the PowerShellCommunityExtensions (PSCX) Module is required.  This module (in conjunction with PSCX)
   has the ability to recursively unzip files within the src zip file provided and also functionality for many other compression types. If the destination
   directory does not exist, it will be created before unzipping the file.  Specifying rm parameter will force removal of the src file after extraction.
+- For non-Windows targets, use the M(unarchive) module instead.
 author: Phil Schwartz
 '''
 

lib/ansible/modules/windows/win_uri.py

@@ -34,6 +34,7 @@ short_description: Interacts with webservices
 description:
 - Interacts with FTP, HTTP and HTTPS web services.
 - Supports Digest, Basic and WSSE HTTP authentication mechanisms.
+- For non-Windows targets, use the M(uri) module instead.
 options:
   url:
     description:
@@ -138,6 +139,8 @@ options:
     description:
     - Specifies the client certificate(.pfx)  that is used for a secure web request.
     version_added: '2.4'
+notes:
+- For non-Windows targets, use the M(uri) module instead.
 author:
 - Corwin Brown (@blakfeld)
 - Dag Wieers (@dagwieers)

lib/ansible/modules/windows/win_user.py

@@ -33,6 +33,7 @@ version_added: "1.7"
 short_description: Manages local Windows user accounts
 description:
      - Manages local Windows user accounts
+     - For non-Windows targets, use the M(user) module instead.
 options:
   name:
     description:
@@ -132,6 +133,8 @@ options:
       - query
     default: present
     aliases: []
+notes:
+     - For non-Windows targets, use the M(user) module instead.
 author:
     - "Paul Durivage (@angstwad)"
     - "Chris Church (@cchurch)"