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/commands/command.py

@@ -35,6 +35,7 @@ description:
        processed through the shell, so variables like C($HOME) and operations
        like C("<"), C(">"), C("|"), C(";") and C("&") will not work (use the M(shell)
        module if you need these features).
+     - For Windows targets, use the M(win_command) module instead.
 options:
   free_form:
     description:
@@ -76,6 +77,7 @@ notes:
        The C(command) module is much more secure as it's not affected by the user's 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 Windows targets, use the M(win_command) module instead.
 author:
     - Ansible Core Team
     - Michael DeHaan

lib/ansible/modules/commands/raw.py

@@ -50,6 +50,7 @@ description:
        available. There is no change handler support for this module.
      - This module does not require python on the remote system, much like
        the M(script) module.
+     - This module is also supported for Windows targets.
 notes:
     - "If using raw from a playbook, you may need to disable fact gathering
       using C(gather_facts: no) if you're using C(raw) to bootstrap python
@@ -59,6 +60,7 @@ notes:
     - the C(environment) keyword does not work with raw normally, it requires a shell
       which means it only works if C(executable) is set or using the module
       with privilege escalation (C(become)).
+    - This module is also supported for Windows targets.
 author:
     - Ansible Core Team
     - Michael DeHaan

lib/ansible/modules/commands/script.py

@@ -30,6 +30,7 @@ description:
      - "The given script will be processed through the shell environment on the remote node. "
      - "This module does not require python on the remote system, much like
        the M(raw) module. "
+     - This module is also supported for Windows targets.
 options:
   free_form:
     description:
@@ -53,6 +54,7 @@ notes:
   - It is usually preferable to write Ansible modules than pushing scripts. Convert your script to an Ansible module for bonus points!
   - The ssh connection plugin will force pseudo-tty allocation via -tt when scripts are executed. pseudo-ttys do not have a stderr channel and all
     stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
+  - This module is also supported for Windows targets.
 author:
     - Ansible Core Team
     - Michael DeHaan

lib/ansible/modules/commands/shell.py

@@ -30,6 +30,7 @@ description:
      - The C(shell) module takes the command name followed by a list of space-delimited arguments.
        It is almost exactly like the M(command) module but runs
        the command through a shell (C(/bin/sh)) on the remote node.
+     - For Windows targets, use the M(win_shell) module instead.
 version_added: "0.2"
 options:
   free_form:
@@ -75,7 +76,7 @@ notes:
       judgement.
    -  To sanitize any variables passed to the shell module, you should use
       "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons.
-
+   - For Windows targets, use the M(win_shell) module instead.
 requirements: [ ]
 author:
     - Ansible Core Team

lib/ansible/modules/files/copy.py

@@ -32,6 +32,7 @@ description:
     - The C(copy) module copies a file from the local or remote machine to a location on the remote machine.
       Use the M(fetch) module to copy files from remote locations to the local box.
       If you need variable interpolation in copied files, use the M(template) module.
+    - For Windows targets, use the M(win_copy) module instead.
 options:
   src:
     description:
@@ -106,6 +107,7 @@ author:
 notes:
    - The "copy" module recursively copy facility does not scale to lots (>hundreds) of files.
      For alternative, see synchronize module, which is a wrapper around rsync.
+   - For Windows targets, use the M(win_copy) module instead.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/files/fetch.py

@@ -28,6 +28,7 @@ description:
      - This module works like M(copy), but in reverse. It is used for fetching
        files from remote machines and storing them locally in a file tree,
        organized by hostname.
+     - This module is also supported for Windows targets.
 version_added: "0.2"
 options:
   src:
@@ -86,6 +87,7 @@ notes:
       playbook authors are encouraged to use fail_when or ignore_errors to
       get this ability.  They may also explicitly set fail_on_missing to False
       to get the non-failing behaviour.
+    - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/files/file.py

@@ -33,7 +33,9 @@ description:
      - Sets attributes of files, symlinks, and directories, or removes
        files/symlinks/directories. Many other modules support the same options as
        the C(file) module - including M(copy), M(template), and M(assemble).
+     - For Windows targets, use the M(win_file) module instead.
 notes:
+    - For Windows targets, use the M(win_file) module instead.
     - See also M(copy), M(template), M(assemble)
 requirements: [ ]
 author:

lib/ansible/modules/files/find.py

@@ -31,6 +31,7 @@ version_added: "2.0"
 short_description: Return a list of files based on specific criteria
 description:
     - Return a list of files based on specific criteria. Multiple criteria are AND'd together.
+    - For Windows targets, use the M(win_find) module instead.
 options:
     age:
         description:
@@ -96,6 +97,8 @@ options:
         choices: [ 'no', 'yes' ]
         description:
             - If false the patterns are file globs (shell) if true they are python regexes.
+notes:
+    - For Windows targets, use the M(win_find) module instead.
 '''
 
 

lib/ansible/modules/files/stat.py

@@ -25,6 +25,7 @@ version_added: "1.3"
 short_description: Retrieve file or file system status
 description:
      - Retrieves facts for a file similar to the linux/unix 'stat' command.
+     - For Windows targets, use the M(win_stat) module instead.
 options:
   path:
     description:
@@ -73,6 +74,8 @@ options:
     default: 'yes'
     version_added: "2.3"
     aliases: [ attr, attributes ]
+notes:
+     - For Windows targets, use the M(win_stat) module instead.
 author: Bruce Pennypacker (@bpennypacker)
 '''
 

lib/ansible/modules/files/tempfile.py

@@ -34,6 +34,7 @@ description:
   - The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps
     to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible
     you need to use M(file) module.
+  - For Windows targets, use the M(win_tempfile) module instead.
 options:
   state:
     description:
@@ -56,6 +57,8 @@ options:
       - Suffix of file/directory name created by module.
     required: false
     default: ""
+notes:
+  - For Windows targets, use the M(win_tempfile) module instead.
 '''
 
 EXAMPLES = """

lib/ansible/modules/files/unarchive.py

@@ -35,13 +35,14 @@ description:
      - The C(unarchive) module unpacks an archive.
      - By default, it will copy the source file from the local system to the target before unpacking.
      - Set C(remote_src=yes) to unpack an archive which already exists on the target.
+     - For Windows targets, use the M(win_unzip) module instead.
 options:
   src:
     description:
       - If C(remote_src=no) (default), local path to archive file to copy to the target server; can be absolute or relative. If C(remote_src=yes), path on the
         target server to existing archive file to unpack.
       - If C(remote_src=yes) and C(src) contains C(://), the remote machine will download the file from the URL first. (version_added 2.0). This is only for
-        simple cases, for full download support look at the M(get_url) module.
+        simple cases, for full download support use the M(get_url) module.
     required: true
   dest:
     description:
@@ -107,6 +108,7 @@ notes:
       are not touched. This is the same behavior as a normal archive extraction.
     - Existing files/directories in the destination which are not in the archive
       are ignored for purposes of deciding if the archive should be unpacked or not.
+    - For Windows targets, use the M(win_unzip) module instead.
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/inventory/add_host.py

@@ -27,6 +27,7 @@ short_description: add a host (and alternatively a group) to the ansible-playboo
 description:
   - Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
     Takes variables so you can define the new hosts more fully.
+  - This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   name:
@@ -42,6 +43,7 @@ options:
 notes:
     - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
       to iterate use a with\_ directive.
+    - This module is also supported for Windows targets.
 author:
     - "Ansible Core Team"
     - "Seth Vidal"

lib/ansible/modules/inventory/group_by.py

@@ -26,6 +26,7 @@ module: group_by
 short_description: Create Ansible groups based on facts
 description:
   - Use facts to create ad-hoc groups that can be used later in a playbook.
+  - This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   key:
@@ -35,6 +36,7 @@ options:
 author: "Jeroen Hoekx (@jhoekx)"
 notes:
   - Spaces in group names are converted to dashes '-'.
+  - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/net_tools/basics/get_url.py

@@ -41,6 +41,7 @@ description:
        your proxy environment for both protocols is correct.
      - From Ansible 2.4 when run with C(--check), it will do a HEAD request to validate the URL but
        will not download the entire file or verify it against hashes.
+     - For Windows targets, use the M(win_get_url) module instead.
 version_added: '0.6'
 options:
   url:
@@ -162,6 +163,8 @@ options:
 # informational: requirements for nodes
 extends_documentation_fragment:
     - files
+notes:
+     - For Windows targets, use the M(win_get_url) module instead.
 author: Jan-Piet Mens (@jpmens)
 '''
 

lib/ansible/modules/net_tools/basics/slurp.py

@@ -30,6 +30,7 @@ short_description: Slurps a file from remote nodes
 description:
      - This module works like M(fetch). It is used for fetching a base64-
        encoded blob containing the data in a remote file.
+     - This module is also supported for Windows targets.
 options:
   src:
     description:
@@ -39,6 +40,7 @@ options:
 notes:
    - This module returns an 'in memory' base64 encoded version of the file, take into account that this will require at least twice the RAM as the
      original file size.
+   - This module is also supported for Windows targets.
    - "See also: M(fetch)"
 author:
     - Ansible Core Team

lib/ansible/modules/net_tools/basics/uri.py

@@ -32,6 +32,7 @@ short_description: Interacts with webservices
 description:
   - Interacts with HTTP and HTTPS web services and supports Digest, Basic and WSSE
     HTTP authentication mechanisms.
+  - For Windows targets, use the M(win_uri) module instead.
 version_added: "1.1"
 options:
   url:
@@ -174,6 +175,7 @@ options:
     version_added: 2.4
 notes:
   - The dependency on httplib2 was removed in Ansible 2.1
+  - For Windows targets, use the M(win_uri) module instead.
 author: "Romeo Theriault (@romeotheriault)"
 '''
 

lib/ansible/modules/packaging/os/package.py

@@ -33,6 +33,7 @@ author:
 short_description: Generic OS package manager
 description:
      - Installs, upgrade and removes packages using the underlying OS package manager.
+     - For Windows targets, use the M(win_package) module instead.
 options:
   name:
     description:
@@ -53,6 +54,7 @@ requirements:
     - Whatever is required for the package plugins specific for each system.
 notes:
     - This module actually calls the pertinent package modules for each system (apt, yum, etc).
+    - For Windows targets, use the M(win_package) module instead.
 '''
 EXAMPLES = '''
 - name: install the latest version of ntpdate

lib/ansible/modules/system/group.py

@@ -32,6 +32,7 @@ short_description: Add or remove groups
 requirements: [ groupadd, groupdel, groupmod ]
 description:
     - Manage presence of groups on a host.
+    - For Windows targets, use the M(win_group) module instead.
 options:
     name:
         required: true
@@ -53,7 +54,8 @@ options:
         choices: [ "yes", "no" ]
         description:
             - If I(yes), indicates that the group created is a system group.
-
+notes:
+    - For Windows targets, use the M(win_group) module instead.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/system/ping.py

@@ -35,6 +35,9 @@ description:
      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.
+   - For Windows targets, use the M(ping) module instead.
+notes:
+   - For Windows targets, use the M(ping) module instead.
 options: {}
 author:
     - "Ansible Core Team"

lib/ansible/modules/system/service.py

@@ -34,6 +34,7 @@ short_description:  Manage services.
 description:
     - Controls services on remote hosts. Supported init systems include BSD init,
       OpenRC, SysV, Solaris SMF, systemd, upstart.
+    - For Windows targets, use the M(win_service) module instead.
 options:
     name:
         required: true
@@ -87,6 +88,8 @@ options:
             - Normally it uses the value of the 'ansible_service_mgr' fact and falls back to the old 'service' module when none matching is found.
         default: 'auto'
         version_added: 2.2
+notes:
+    - For Windows targets, use the M(win_service) module instead.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/system/setup.py

@@ -69,6 +69,7 @@ description:
        executed directly by C(/usr/bin/ansible) to check what variables are
        available to a host. Ansible provides many I(facts) about the system,
        automatically.
+     - This module is also supported for Windows targets.
 notes:
     - More ansible facts will be added with successive releases. If I(facter) or
       I(ohai) are installed, variables from these programs will also be snapshotted
@@ -85,6 +86,7 @@ notes:
       their output must be formattable in JSON (Ansible will take care of this). Test the
       output of your scripts.
       This option was added in Ansible 2.1.
+    - This module is also supported for Windows targets.
 author:
     - "Ansible Core Team"
     - "Michael DeHaan"

lib/ansible/modules/system/user.py

@@ -33,8 +33,10 @@ notes:
   - There are specific requirements per platform on user management utilities. However
     they generally come pre-installed with the system and Ansible will require they
     are present at runtime. If they are not, a descriptive error message will be shown.
+  - For Windows targets, use the M(win_user) module instead.
 description:
     - Manage user accounts and user attributes.
+    - For Windows targets, use the M(win_user) module instead.
 options:
     name:
         required: true

lib/ansible/modules/utilities/helper/meta.py

@@ -31,6 +31,7 @@ description:
     - Meta tasks are a special kind of task which can influence Ansible internal execution or state. Prior to Ansible 2.0,
       the only meta option available was `flush_handlers`. As of 2.2, there are five meta tasks which can be used.
       Meta tasks can be used anywhere within your playbook.
+    - This module is also supported for Windows targets.
 options:
   free_form:
     description:
@@ -48,9 +49,9 @@ options:
         - "C(reset_connection) (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)"
     choices: ['noop', 'flush_handlers', 'refresh_inventory', 'clear_facts', 'clear_host_errors', 'end_play', 'reset_connection']
     required: true
-    default: null
 notes:
-    - meta is not really a module nor action_plugin as such it cannot be overwritten.
+    - C(meta) is not really a module nor action_plugin as such it cannot be overwritten.
+    - This module is also supported for Windows targets.
 author:
     - "Ansible Core Team"
 '''

lib/ansible/modules/utilities/logic/assert.py

@@ -29,6 +29,7 @@ module: assert
 short_description: Asserts given expressions are true
 description:
      - This module asserts that given expressions are true with an optional custom message.
+     - This module is also supported for Windows targets.
 version_added: "1.5"
 options:
   that:
@@ -39,7 +40,8 @@ options:
   msg:
     description:
       - "The customized message used for a failing assertion"
-    required: false
+notes:
+     - This module is also supported for Windows targets.
 author:
     - "Ansible Core Team"
     - "Michael DeHaan"

lib/ansible/modules/utilities/logic/async_status.py

@@ -29,25 +29,23 @@ DOCUMENTATION = '''
 module: async_status
 short_description: Obtain status of asynchronous task
 description:
-     - "This module gets the status of an asynchronous task."
+     - This module gets the status of an asynchronous task.
+     - This module is also supported for Windows targets.
 version_added: "0.5"
 options:
   jid:
     description:
       - Job or task identifier
     required: true
-    default: null
-    aliases: []
   mode:
     description:
       - if C(status), obtain the status; if C(cleanup), clean up the async job cache
         located in C(~/.ansible_async/) for the specified job I(jid).
-    required: false
     choices: [ "status", "cleanup" ]
     default: "status"
 notes:
     - See also U(http://docs.ansible.com/playbooks_async.html)
-requirements: []
+    - This module is also supported for Windows targets.
 author:
     - "Ansible Core Team"
     - "Michael DeHaan"

lib/ansible/modules/utilities/logic/debug.py

@@ -31,7 +31,7 @@ description:
      - This module prints statements during execution and can be useful
        for debugging variables or expressions without necessarily halting
        the playbook. Useful for debugging together with the 'when:' directive.
-
+     - This module is also supported for Windows targets.
 version_added: "0.8"
 options:
   msg:
@@ -49,6 +49,8 @@ options:
     required: False
     default: 0
     version_added: "2.1"
+notes:
+    - This module is also supported for Windows targets.
 author:
     - "Dag Wieers (@dagwieers)"
     - "Michael DeHaan"

lib/ansible/modules/utilities/logic/fail.py

@@ -30,6 +30,7 @@ short_description: Fail with custom message
 description:
      - This module fails the progress with a custom message. It can be
        useful for bailing out when a certain condition is met using C(when).
+     - This module is also supported for Windows targets.
 version_added: "0.8"
 options:
   msg:
@@ -38,6 +39,8 @@ options:
         fail will simply bail out with a generic message.
     required: false
     default: "'Failed as requested from task'"
+notes:
+    - This module is also supported for Windows targets.
 
 author: "Dag Wieers (@dagwieers)"
 '''

lib/ansible/modules/utilities/logic/include.py

@@ -26,6 +26,7 @@ description:
      - Static includes are not subject to most directives, for example, loops or conditionals, they are applied instead to each inherited task.
      - Since 2.0 task includes are dynamic and behave more like real tasks.  This means they can be looped, skipped and use variables from any source.
        Ansible tries to auto detect this, use the `static` directive (new in 2.1) to bypass autodetection.
+     - This module is also supported for Windows targets.
 version_added: "0.6"
 options:
   free-form:
@@ -34,6 +35,7 @@ options:
 notes:
     - This is really not a module, though it appears as such, this is a feature of the Ansible Engine, as such it cannot be overridden the same way a
       module can.
+    - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = """

lib/ansible/modules/utilities/logic/include_role.py

@@ -20,7 +20,8 @@ author:
 module: include_role
 short_description: Load and execute a role
 description:
-     - "Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks."
+     - Loads and executes a role as a task, this frees roles from the `role:` directive and allows them to be treated more as tasks.
+     - This module is also supported for Windows targets.
 version_added: "2.2"
 options:
   name:
@@ -57,6 +58,7 @@ notes:
     - As with C(include) this task can be static or dynamic, If static it implies that it won't need templating nor loops nor conditionals and will
       show included tasks in the --list options. Ansible will try to autodetect what is needed, but you can set `static` to `yes` or `no` at task
       level to control this.
+    - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = """

lib/ansible/modules/utilities/logic/include_vars.py

@@ -21,6 +21,7 @@ short_description: Load variables from files, dynamically within a task.
 description:
     - Loads variables from a YAML/JSON files dynamically from within a file or from a directory recursively during task runtime. If loading a directory,
       the files are sorted alphabetically before being loaded.
+    - This module is also supported for Windows targets.
 version_added: "1.4"
 options:
   file:
@@ -65,6 +66,8 @@ options:
     description:
         - This module allows you to specify the 'file' option directly w/o any other options.
           There is no 'free-form' option, this is just an indicator, see example below.
+notes:
+    - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = """

lib/ansible/modules/utilities/logic/pause.py

@@ -33,6 +33,7 @@ description:
   - >
     The pause module integrates into async/parallelized playbooks without any special considerations (see also: Rolling Updates). When using pauses with
     the C(serial) playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts.
+  - This module is also supported for Windows targets.
 version_added: "0.8"
 options:
   minutes:
@@ -53,6 +54,7 @@ options:
 author: "Tim Bielawa (@tbielawa)"
 notes:
       - Starting in 2.2,  if you specify 0 or negative for minutes or seconds, it will wait for 1 second, previously it would wait indefinitely.
+      - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/utilities/logic/set_fact.py

@@ -34,6 +34,7 @@ description:
       a fact cache.
     - Per the standard Ansible variable precedence rules, many other types of variables have a higher priority, so this value may be overridden.
       See U(http://docs.ansible.com/ansible/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) for more information.
+    - This module is also supported for Windows targets.
 options:
   key_value:
     description:
@@ -46,6 +47,7 @@ version_added: "1.2"
 notes:
     - "The `var=value` notation can only create strings or booleans.
       If you want to create lists/arrays or dictionary/hashes use `var: [val1, val2]`"
+    - This module is also supported for Windows targets.
 '''
 
 EXAMPLES = '''

lib/ansible/modules/utilities/logic/set_stats.py

@@ -29,6 +29,7 @@ module: set_stats
 short_description: Set stats for the current ansible run
 description:
      - This module allows setting/accumulating stats on the current ansible run, either per host of for all hosts in the run.
+     - This module is also supported for Windows targets.
 options:
   data:
     description:
@@ -44,6 +45,8 @@ options:
         - boolean that indicates if the provided value is aggregated to the existing stat C(yes) or will replace it C(no)
     required: no
     default: yes
+notes:
+    - This module is also supported for Windows targets.
 version_added: "2.3"
 '''
 

lib/ansible/modules/utilities/logic/wait_for.py

@@ -39,6 +39,7 @@ description:
      - In 1.8 and later, this module can also be used to wait for active
        connections to be closed before continuing, useful if a node
        is being rotated out of a load balancer pool.
+     - This module is also supported for Windows targets.
 version_added: "0.7"
 options:
   host:
@@ -99,6 +100,8 @@ options:
       - This overrides the normal error message from a failure to meet the required conditions.
 notes:
   - The ability to use search_regex with a port connection was added in 1.7.
+  - This module is also supported for Windows targets.
+  - See also M(wait_for_connection)
 author:
     - Jeroen Hoekx (@jhoekx)
     - John Jarvis (@jarv)
@@ -106,7 +109,6 @@ author:
 '''
 
 EXAMPLES = r'''
-
 - name: Wait 300 seconds for port 8000 to become open on the host, don't start checking for 10 seconds
   wait_for:
     port: 8000

lib/ansible/modules/utilities/logic/wait_for_connection.py

@@ -32,6 +32,7 @@ description:
 - Retries the transport connection after a timeout of C(connect_timeout).
 - Tests the transport connection every C(sleep) seconds.
 - This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning.
+- This module is also supported for Windows targets.
 version_added: "2.3"
 options:
   connect_timeout:
@@ -50,6 +51,8 @@ options:
     description:
       - Maximum number of seconds to wait for.
     default: 600
+notes:
+- This module is also supported for Windows targets.
 author: "Dag Wieers (@dagwieers)"
 '''
 

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)"