Windows: Clean up documentation (#36684)

This PR includes:
- Further cleanup of BOTMETA.yml
- Cleanup of author github handles
- Use of proper booleans
- One-line license statement
- Copyright format statement
- Smaller cleanups

.github/BOTMETA.yml

@@ -1,6 +1,6 @@
 # BOTMETA V2.0
 #
-# Data used by ansibot to indentify who works on each file in the repo.
+# Data used by ansibot to identify who works on each file in the repo.
 # If you have questions about this data format, please join #ansible-devel
 # on irc.freenode and ping anyone who is op'ed.
 #
@@ -303,7 +303,6 @@ files:
   $modules/cloud/vmware/vca_fw.py: privateip
   $modules/cloud/vmware/vca_nat.py: privateip
   $modules/cloud/vmware/vca_vapp.py: privateip
-  $modules/cloud/vmware/vcenter_license.py: dagwieers
   $modules/cloud/vmware/vmware_cluster.py: $team_ansible
   $modules/cloud/vmware/vmware_datacenter.py: $team_ansible kamsz
   $modules/cloud/vmware/vmware_dns_config.py: $team_ansible
@@ -328,7 +327,6 @@ files:
   $modules/cloud/vmware/vmware_vmotion.py: $team_ansible bedecarroll
   $modules/cloud/vmware/vmware_vsan_cluster.py: $team_ansible
   $modules/cloud/vmware/vmware_vswitch.py: akasurde
-  $modules/cloud/vmware/vsphere_copy.py: dagwieers
   $modules/cloud/vmware/vsphere_guest.py: $team_ansible rhoop dagwieers
   $modules/cloud/vultr/: resmo
   $modules/cloud/webfaction/: quentinsf
@@ -377,7 +375,6 @@ files:
   $modules/files/fetch.py: $team_ansible
   $modules/files/file.py: $team_ansible
   $modules/files/find.py: $team_ansible
-  $modules/files/iso_extract.py: dagwieers jhoekx ribbons
   $modules/files/lineinfile.py: ahtik $team_ansible dhozac
   $modules/files/replace.py: EvanK
   $modules/files/stat.py: bpennypacker
@@ -387,11 +384,12 @@ files:
   $modules/files/unarchive.py:
     labels: unarchive
     maintainers: pileofrogs
+    ignored: dagwieers
   $modules/files/xattr.py: $team_ansible bcoca
   $modules/files/xml.py:
     ignored: magnus919
     labels: xml
-    maintainers: tbielawa dagwieers sm4rk0 cmprescott
+    maintainers: sm4rk0 cmprescott
   $modules/identity/cyberark/:
     notified: cyberark-bizdev
   $modules/identity/ipa/:
@@ -523,7 +521,6 @@ files:
   $modules/notification/hall.py: bkimble
   $modules/notification/hipchat.py: pb8226 shirou
   $modules/notification/jabber.py: bcoca
-  $modules/notification/mail.py: dagwieers
   $modules/notification/mattermost.py: bjolivot
   $modules/notification/mqtt.py: jpmens
   $modules/notification/nexmo.py: sivel
@@ -604,7 +601,6 @@ files:
   $modules/remote_management/manageiq/: $team_manageiq
   $modules/remote_management/stacki/stacki_host.py: bbyhuy bsanders
   $modules/remote_management/ucs/: $team_ucs
-  $modules/remote_management/wakeonlan.py: dagwieers
   $modules/source_control/bzr.py: andreparames
   $modules/source_control/git.py: $team_ansible
   $modules/source_control/git_config.py: djmattyg007
@@ -671,7 +667,6 @@ files:
   $modules/system/puppet.py: emonty nibalizer
   $modules/system/runit.py: jsumners
   $modules/system/seboolean.py: $team_ansible sfromm
-  $modules/system/sefcontext.py: dagwieers
   $modules/system/selinux.py: goozbach
   $modules/system/selinux_permissive.py: mscherer
   $modules/system/seport.py: dankeder
@@ -690,16 +685,12 @@ files:
   $modules/utilities/logic/assert.py: $team_ansible
   $modules/utilities/logic/async_status.py: $team_ansible
   $modules/utilities/logic/async_wrapper.py: $team_ansible
-  $modules/utilities/logic/debug.py: dagwieers
-  $modules/utilities/logic/fail.py: dagwieers
   $modules/utilities/logic/include.py: $team_ansible
   $modules/utilities/logic/include_role.py: $team_ansible
   $modules/utilities/logic/include_vars.py: $team_ansible linuxdynasty
   $modules/utilities/logic/pause.py: tbielawa
-  $modules/utilities/logic/set_fact.py: dagwieers
   $modules/utilities/logic/set_stats.py: bcoca
   $modules/utilities/logic/wait_for.py: AnderEnder gregswift jarv jhoekx
-  $modules/utilities/logic/wait_for_connection.py: dagwieers
   $modules/web_infrastructure/ansible_tower/: $team_tower
   $modules/web_infrastructure/apache2_mod_proxy.py: oboukili
   $modules/web_infrastructure/deploy_helper.py: ramondelafuente
@@ -725,38 +716,14 @@ files:
     ignored: angstwad georgefrank h0nig
   $modules/windows/setup.ps1: $team_ansible
   $modules/windows/slurp.ps1: $team_ansible
-  $modules/windows/win_acl.ps1:
-    maintainers: schwartzmx trondhindenes
-  $modules/windows/win_file_version.ps1: SamLiu79
-  $modules/windows/win_file_version.py: SamLiu79
-  $modules/windows/win_get_url.ps1: jhawkesworth
-  $modules/windows/win_get_url.py: jhawkesworth
-  $modules/windows/win_iis_virtualdirectory.ps1: $team_ansible
   $modules/windows/win_iis_virtualdirectory.py: $team_ansible
-  $modules/windows/win_lineinfile.ps1: brianlloyd
-  $modules/windows/win_lineinfile.py: brianlloyd
-  $modules/windows/win_owner.ps1: jborean93
-  $modules/windows/win_owner.py: jborean93
-  $modules/windows/win_ping.ps1: nitzmahone
-  $modules/windows/win_ping.py: nitzmahone
-  $modules/windows/win_security_policy.ps1: rndmh3ro defionscode
   $modules/windows/win_security_policy.py: rndmh3ro defionscode
-  $modules/windows/win_share.ps1: jborean93
-  $modules/windows/win_share.py: jborean93
-  $modules/windows/win_stat.ps1: nitzmahone
-  $modules/windows/win_stat.py: nitzmahone
-  $modules/windows/win_timezone.ps1: schwartzmx
-  $modules/windows/win_timezone.py: schwartzmx
-  $modules/windows/win_user.ps1: nitzmahone
-  $modules/windows/win_user.py: nitzmahone
-  $modules/windows/win_webpicmd.ps1: petemounce
-  $modules/windows/win_webpicmd.py: petemounce
   contrib/inventory:
     keywords:
     - dynamic inventory script
     - dynamic inventory
     - inventory script
-    labels: "c:inventory/contrib_script"
+    labels: c:inventory/contrib_script
     support: community
   contrib/inventory/digital_ocean.py:
     keywords:

lib/ansible/modules/windows/_win_msi.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Matt Martz <matt@sivel.net>, and others
+# Copyright: (c) 2014, Matt Martz <matt@sivel.net>, and others
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -40,8 +26,8 @@ description:
 options:
     path:
         description:
-            - File system path to the MSI file to install
+            - File system path to the MSI file to install.
-        required: true
+        required: yes
     extra_args:
         description:
             - Additional arguments to pass to the msiexec.exe command.

lib/ansible/modules/windows/win_acl.py

@@ -1,14 +1,15 @@
 #!/usr/bin/python
-# Copyright 2015, Phil Schwartz <schwartzmx@gmail.com>
+# -*- coding: utf-8 -*-
-# Copyright 2015, Trond Hindenes
+
-# Copyright 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
+# Copyright: (c) 2015, Phil Schwartz <schwartzmx@gmail.com>
+# Copyright: (c) 2015, Trond Hindenes
+# Copyright: (c) 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_acl

lib/ansible/modules/windows/win_acl_inheritance.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
+# Copyright: (c) 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_acl_inheritance
@@ -37,14 +22,11 @@ options:
   path:
     description:
       - Path to be used for changing inheritance
-    required: true
+    required: yes
   state:
     description:
       - Specify whether to enable I(present) or disable I(absent) ACL inheritance
-    required: false
+    choices: [ absent, present ]
-    choices:
-      - present
-      - absent
     default: absent
   reorganize:
     description:
@@ -52,12 +34,10 @@ options:
         (in combination with removal) for a simple ACL instead of using multiple ACE deny entries.
       - For P(state) = I(present), indicates if the inherited ACE's should be deduplicated compared to the parent directory. This removes complexity
         of the ACL structure.
-    required: false
+    type: bool
-    choices:
+    default: 'no'
-      - no
+author:
-      - yes
+- Hans-Joachim Kliemeck (@h0nIg)
-    default: no
-author: Hans-Joachim Kliemeck (@h0nIg)
 '''
 
 EXAMPLES = r'''
@@ -70,13 +50,13 @@ EXAMPLES = r'''
   win_acl_inheritance:
     path: C:\apache
     state: absent
-    reorganize: True
+    reorganize: yes
 
 - name: Enable and remove dedicated ACE's
   win_acl_inheritance:
     path: C:\apache
     state: present
-    reorganize: True
+    reorganize: yes
 '''
 
 RETURN = r'''

lib/ansible/modules/windows/win_audit_policy_system.py

@@ -1,19 +1,18 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Noah Sparks <nsparks@outlook.com>
+# Copyright: (c) 2017, Noah Sparks <nsparks@outlook.com>
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = '''
 ---
 module: win_audit_policy_system
-short_description: Used to make changes to the system wide Audit Policy.
+short_description: Used to make changes to the system wide Audit Policy
 description:
   - Used to make changes to the system wide Audit Policy.
   - It is recommended to take a backup of the policies before adjusting them for the first time.
@@ -35,8 +34,8 @@ options:
     description:
       - The type of event you would like to audit for.
       - Accepts a list. See examples.
-    choices: [ 'success', 'failure', 'none' ]
+    choices: [ failure, none, success ]
-    required: true
+    required: yes
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_audit_rule.py

@@ -8,7 +8,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_audit_rule
@@ -28,12 +27,12 @@ options:
       - Path to the file, folder, or registry key.
       - Registry paths should be in Powershell format, beginning with an abbreviation for the root
         such as, 'hklm:\software'.
-    required: true
+    required: yes
     aliases: [ dest, destination ]
   user:
     description:
       - The user or group to adjust rules for.
-    required: true
+    required: yes
   rights:
     description:
       - Comma seperated list of the rights desired. Only required for adding a rule.
@@ -41,7 +40,7 @@ options:
         FileSystemRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.filesystemrights.aspx).
       - If I(path) is a registry key, rights can be any right under MSDN
         RegistryRights U(https://msdn.microsoft.com/en-us/library/system.security.accesscontrol.registryrights.aspx).
-    required: true
+    required: yes
   inheritance_flags:
     description:
       - Defines what objects inside of a folder or registry key will inherit the settings.
@@ -62,51 +61,51 @@ options:
     description:
       - Defines whether to log on failure, success, or both.
       - To log both define as comma seperated list "Success, Failure".
-    required: true
+    required: yes
-    choices: [ Success, Failure ]
+    choices: [ Failure, Success ]
   state:
     description:
       - Whether the rule should be C(present) or C(absent).
       - For absent, only I(path), I(user), and I(state) are required.
       - Specifying C(absent) will remove all rules matching the defined I(user).
+    choices: [ absent, present ]
     default: present
-    choices: [ present, absent ]
 '''
 
 EXAMPLES = r'''
 - name: add filesystem audit rule for a folder
   win_audit_rule:
-    path: 'c:\inetpub\wwwroot\website'
+    path: C:\inetpub\wwwroot\website
-    user: 'BUILTIN\Users'
+    user: BUILTIN\Users
-    rights: 'write,delete,changepermissions'
+    rights: write,delete,changepermissions
-    audit_flags: 'success,failure'
+    audit_flags: success,failure
-    inheritance_flags: 'ContainerInherit,ObjectInherit'
+    inheritance_flags: ContainerInherit,ObjectInherit
 
 - name: add filesystem audit rule for a file
   win_audit_rule:
-    path: 'c:\inetpub\wwwroot\website\web.config'
+    path: C:\inetpub\wwwroot\website\web.config
-    user: 'BUILTIN\Users'
+    user: BUILTIN\Users
     rights: write,delete,changepermissions
     audit_flags: success,failure
     inheritance_flags: None
 
 - name: add registry audit rule
   win_audit_rule:
-    path: 'hklm:\software'
+    path: HKLM:\software
-    user: 'BUILTIN\Users'
+    user: BUILTIN\Users
-    rights: 'delete'
+    rights: delete
     audit_flags: 'success'
 
 - name: remove filesystem audit rule
   win_audit_rule:
-    path: 'c:\inetpub\wwwroot\website'
+    path: C:\inetpub\wwwroot\website
-    user: 'BUILTIN\Users'
+    user: BUILTIN\Users
     state: absent
 
 - name: remove registry audit rule
   win_audit_rule:
-    path: 'hklm:\software'
+    path: HKLM:\software
-    user: 'BUILTIN\Users'
+    user: BUILTIN\Users
     state: absent
 '''
 

lib/ansible/modules/windows/win_certificate_store.py

@@ -1,17 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2017, Ansible Project
-
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_certificate_store
@@ -36,11 +32,8 @@ options:
       specified by I(thumbprint).
     - When exporting a certificate, if I(path) is a directory then the module
       will fail, otherwise the file will be replaced if needed.
+    choices: [ absent, exported, present ]
     default: present
-    choices:
-    - present
-    - absent
-    - exported
   path:
     description:
     - The path to a certificate file.
@@ -69,10 +62,8 @@ options:
     description:
     - The store location to use when importing a certificate or searching for a
       certificate.
+    choices: [ CurrentUser, LocalMachine ]
     default: LocalMachine
-    choices:
-    - CurrentUser
-    - LocalMachine
   password:
     description:
     - The password of the pkcs12 certificate key.
@@ -99,10 +90,7 @@ options:
     - Used when C(state=present) only and cannot be changed once imported.
     - See U(https://msdn.microsoft.com/en-us/library/system.security.cryptography.x509certificates.x509keystorageflags.aspx)
       for more details.
-    choices:
+    choices: [ default, machine, user ]
-    - default
-    - machine
-    - user
     default: default
   file_type:
     description:
@@ -113,10 +101,7 @@ options:
       the certificate and private key unlike the other options.
     - When C(pkcs12) is set and the private key is not exportable or accessible
       by the current user, it will throw an exception.
-    choices:
+    choices: [ der, pem, pkcs12 ]
-    - der
-    - pem
-    - pkcs12
     default: der
 notes:
 - Some actions on PKCS12 certificates and keys may fail with the error
@@ -131,12 +116,12 @@ author:
 EXAMPLES = r'''
 - name: import a certificate
   win_certificate_store:
-    path: C:\temp\cert.pem
+    path: C:\Temp\cert.pem
     state: present
 
 - name: import pfx certificate that is password protected
   win_certificate_store:
-    path: C:\temp\cert.pfx
+    path: C:\Temp\cert.pfx
     state: present
     password: VeryStrongPasswordHere!
   become: yes
@@ -144,7 +129,7 @@ EXAMPLES = r'''
 
 - name: import pfx certificate without password and set private key as un-exportable
   win_certificate_store:
-    path: C:\temp\cert.pfx
+    path: C:\Temp\cert.pfx
     state: present
     key_exportable: no
   # usually you don't set this here but it is for illustrative purposes
@@ -153,7 +138,7 @@ EXAMPLES = r'''
 
 - name: remove a certificate based on file thumbprint
   win_certificate_store:
-    path: C:\temp\cert.pem
+    path: C:\Temp\cert.pem
     state: absent
 
 - name: remove a certificate based on thumbprint
@@ -170,13 +155,13 @@ EXAMPLES = r'''
 
 - name: export certificate as der encoded file
   win_certificate_store:
-    path: C:\temp\cert.cer
+    path: C:\Temp\cert.cer
     state: exported
     file_type: der
 
 - name: export certificate and key as pfx encoded file
   win_certificate_store:
-    path: C:\temp\cert.pfx
+    path: C:\Temp\cert.pfx
     state: exported
     file_type: pkcs12
     password: AnotherStrongPass!

lib/ansible/modules/windows/win_chocolatey.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Trond Hindenes <trond@hindenes.com>
+# Copyright: (c) 2014, Trond Hindenes <trond@hindenes.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name

lib/ansible/modules/windows/win_command.py

@@ -1,29 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, inc
+# Copyright: (c) 2016, Ansible, inc
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_command
@@ -39,18 +23,18 @@ description:
 options:
   free_form:
     description:
-      - the C(win_command) module takes a free form command to run.  There is no parameter actually named 'free form'.
+      - The C(win_command) module takes a free form command to run.
-        See the examples!
+      - There is no parameter actually named 'free form'. See the examples!
-    required: true
+    required: yes
   creates:
     description:
-      - a path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
+      - A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
   removes:
     description:
-      - a path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped.
+      - A path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped.
   chdir:
     description:
-      - set the specified path as the current working directory before executing a command.
+      - Set the specified path as the current working directory before executing a command.
   stdin:
     description:
     - Set the stdin of the command directly to the specified value.
@@ -64,7 +48,7 @@ notes:
       exist, use this.
     - For non-Windows targets, use the M(command) module instead.
 author:
-    - Matt Davis
+    - Matt Davis (@nitzmahone)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_copy.py

@@ -1,18 +1,14 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-
+# Copyright: (c) 2017, Ansible Project
-# (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_copy
@@ -27,13 +23,13 @@ options:
     - When used instead of C(src), sets the contents of a file directly to the
       specified value. This is for simple values, for anything complex or with
       formatting please switch to the template module.
-    version_added: "2.3"
+    version_added: '2.3'
   decrypt:
     description:
     - This option controls the autodecryption of source files using vault.
     type: bool
     default: 'yes'
-    version_added: "2.5"
+    version_added: '2.5'
   dest:
     description:
     - Remote absolute path where the file should be copied to. If src is a
@@ -45,9 +41,8 @@ options:
       with "/" or "\", or C(src) is a directory.
     - If C(src) and C(dest) are files and if the parent directory of C(dest)
       doesn't exist, then the task will fail.
-    required: true
+    required: yes
   force:
-    version_added: "2.3"
     description:
     - If set to C(yes), the file will only be transferred if the content
       is different than destination.
@@ -55,22 +50,23 @@ options:
       destination does not exist.
     - If set to C(no), no checksuming of the content is performed which can
       help improve performance on larger files.
-    default: 'yes'
     type: bool
+    default: 'yes'
+    version_added: '2.3'
   local_follow:
-    version_added: '2.4'
     description:
     - This flag indicates that filesystem links in the source tree, if they
       exist, should be followed.
-    default: 'yes'
     type: bool
+    default: 'yes'
+    version_added: '2.4'
   remote_src:
     description:
-    - If False, it will search for src at originating/master machine, if True
+    - If C(no), it will search for src at originating/master machine.
-      it will go to the remote/target machine for the src.
+    - If C(yes), it will go to the remote/target machine for the src.
-    default: 'no'
     type: bool
-    version_added: "2.3"
+    default: 'no'
+    version_added: '2.3'
   src:
     description:
     - Local path to a file to copy to the remote server; can be absolute or
@@ -82,7 +78,7 @@ options:
       end with "/", the directory itself with all contents is copied.
     - If path is a file and dest ends with "\", the file is copied to the
       folder with the same filename.
-    required: true
+    required: yes
 notes:
 - For non-Windows targets, use the M(copy) module instead.
 - Currently win_copy does not support copying symbolic links from both local to
@@ -101,39 +97,39 @@ EXAMPLES = r'''
 - name: Copy a single file
   win_copy:
     src: /srv/myfiles/foo.conf
-    dest: c:\Temp\renamed-foo.conf
+    dest: C:\Temp\renamed-foo.conf
 
 - name: Copy a single file keeping the filename
   win_copy:
     src: /src/myfiles/foo.conf
-    dest: c:\temp\
+    dest: C:\Temp\
 
-- name: Copy folder to c:\temp (results in C:\Temp\temp_files)
+- name: Copy folder to C:\Temp (results in C:\Temp\temp_files)
   win_copy:
     src: files/temp_files
-    dest: c:\Temp
+    dest: C:\Temp
 
 - name: Copy folder contents recursively
   win_copy:
     src: files/temp_files/
-    dest: c:\Temp
+    dest: C:\Temp
 
 - name: Copy a single file where the source is on the remote host
   win_copy:
-    src: C:\temp\foo.txt
+    src: C:\Temp\foo.txt
     dest: C:\ansible\foo.txt
-    remote_src: True
+    remote_src: yes
 
 - name: Copy a folder recursively where the source is on the remote host
   win_copy:
-    src: C:\temp
+    src: C:\Temp
     dest: C:\ansible
-    remote_src: True
+    remote_src: yes
 
 - name: Set the contents of a file
   win_copy:
-    dest: C:\temp\foo.txt
     content: abc123
+    dest: C:\Temp\foo.txt
 '''
 
 RETURN = r'''

lib/ansible/modules/windows/win_disk_facts.py

@@ -8,7 +8,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_disk_facts

lib/ansible/modules/windows/win_disk_image.py

@@ -1,32 +1,17 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Red Hat, Inc.
+# Copyright: (c) 2017, Red Hat, Inc.
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = '''
 module: win_disk_image
 short_description: Manage ISO/VHD/VHDX mounts on Windows hosts
-version_added: 2.3
+version_added: '2.3'
 description:
      - Manages mount behavior for a specified ISO, VHD, or VHDX image on a Windows host. When C(state) is C(present),
        the image will be mounted under a system-assigned drive letter, which will be returned in the C(mount_path) value
@@ -34,14 +19,12 @@ description:
 options:
   image_path:
     description:
-      - path to an ISO, VHD, or VHDX image on the target Windows host (the file cannot reside on a network share)
+      - Path to an ISO, VHD, or VHDX image on the target Windows host (the file cannot reside on a network share)
-    required: true
+    required: yes
   state:
     description:
-      - whether the image should be present as a drive-letter mount or not.
+      - Whether the image should be present as a drive-letter mount or not.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
     default: present
 author:
     - Matt Davis (@nitzmahone)
@@ -56,21 +39,21 @@ mount_path:
 '''
 
 EXAMPLES = r'''
-# ensure an iso is mounted
+# Run installer from mounted ISO, then unmount
-- win_disk_image:
+- name: Ensure an ISO is mounted
+  win_disk_image:
     image_path: C:\install.iso
     state: present
   register: disk_image_out
 
-# run installer from mounted iso
+- name: Run installer from mounted iso
-- win_package:
+  win_package:
     path: '{{ disk_image_out.mount_path }}setup\setup.exe'
-    product_id: '35a4e767-0161-46b0-979f-e61f282fee21'
+    product_id: 35a4e767-0161-46b0-979f-e61f282fee21
     state: present
 
-# unmount iso
+- name: Unmount iso
-- win_disk_image:
+  win_disk_image:
     image_path: C:\install.iso
     state: absent
-
 '''

lib/ansible/modules/windows/win_dns_client.py

@@ -1,29 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Red Hat, Inc.
+# Copyright: (c) 2017, Red Hat, Inc.
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_dns_client
@@ -36,36 +20,37 @@ options:
     description:
       - Adapter name or list of adapter names for which to manage DNS settings ('*' is supported as a wildcard value).
         The adapter name used is the connection caption in the Network Control Panel or via C(Get-NetAdapter), eg C(Local Area Connection).
-    required: true
+    required: yes
   ipv4_addresses:
     description:
       - Single or ordered list of DNS server IPv4 addresses to configure for lookup. An empty list will configure the adapter to use the
         DHCP-assigned values on connections where DHCP is enabled, or disable DNS lookup on statically-configured connections.
-    required: true
+    required: yes
 notes:
   - When setting an empty list of DNS server addresses on an adapter with DHCP enabled, a change will always be registered, since it is not possible to
     detect the difference between a DHCP-sourced server value and one that is statically set.
-author: "Matt Davis (@nitzmahone)"
+author:
+- Matt Davis (@nitzmahone)
 '''
 
 EXAMPLES = r'''
-  # set a single address on the adapter named Ethernet
+- name: Set a single address on the adapter named Ethernet
-  - win_dns_client:
+  win_dns_client:
-      adapter_names: Ethernet
+    adapter_names: Ethernet
-      ipv4_addresses: 192.168.34.5
+    ipv4_addresses: 192.168.34.5
 
-  # set multiple lookup addresses on all visible adapters (usually physical adapters that are in the Up state), with debug logging to a file
+- name: Set multiple lookup addresses on all visible adapters (usually physical adapters that are in the Up state), with debug logging to a file
-  - win_dns_client:
+  win_dns_client:
-      adapter_names: "*"
+    adapter_names: '*'
-      ipv4_addresses:
+    ipv4_addresses:
-      - 192.168.34.5
+    - 192.168.34.5
-      - 192.168.34.6
+    - 192.168.34.6
-      log_path: c:\dns_log.txt
+    log_path: C:\dns_log.txt
 
-  # configure all adapters whose names begin with Ethernet to use DHCP-assigned DNS values
+- name: Configure all adapters whose names begin with Ethernet to use DHCP-assigned DNS values
-  - win_dns_client:
+  win_dns_client:
-      adapter_names: "Ethernet*"
+    adapter_names: 'Ethernet*'
-      ipv4_addresses: []
+    ipv4_addresses: []
 '''
 
 RETURN = '''

lib/ansible/modules/windows/win_domain.py

@@ -1,44 +1,30 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Red Hat, Inc.
+# Copyright: (c) 2017, Red Hat, Inc.
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 module: win_domain
-short_description: Ensures the existence of a Windows domain.
+short_description: Ensures the existence of a Windows domain
 version_added: 2.3
 description:
-     - Ensure that the domain named by C(dns_domain_name) exists and is reachable. If the domain is not reachable, the domain is created in a new forest
+- Ensure that the domain named by C(dns_domain_name) exists and is reachable.
-       on the target Windows Server 2012R2+ host. This module may require subsequent use of the M(win_reboot) action if changes are made.
+- If the domain is not reachable, the domain is created in a new forest on the target Windows Server 2012R2+ host.
+- This module may require subsequent use of the M(win_reboot) action if changes are made.
 options:
   dns_domain_name:
     description:
       - the DNS name of the domain which should exist and be reachable or reside on the target Windows host
-    required: true
+    required: yes
   safe_mode_password:
     description:
       - safe mode password for the domain controller
-    required: true
+    required: yes
   database_path:
     description:
     - The path to a directory on a fixed disk of the Windows host where the
@@ -61,13 +47,11 @@ reboot_required:
     returned: always
     type: boolean
     sample: true
-
 '''
 
 EXAMPLES = r'''
-# ensure the named domain is reachable from the target host; if not, create the domain in a new forest residing on the target host
+- name: Ensure the named domain is reachable from the target host; if not, create the domain in a new forest residing on the target host
-- win_domain:
+  win_domain:
     dns_domain_name: ansible.vagrant
     safe_mode_password: password123!
-
 '''

lib/ansible/modules/windows/win_domain_controller.py

@@ -1,17 +1,14 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2017, Red Hat, Inc.
-
+# Copyright: (c) 2017, Ansible Project
-# (c) 2017, Red Hat, Inc.
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 module: win_domain_controller
 short_description: Manage domain controller/member server state for a Windows host
@@ -89,7 +86,7 @@ EXAMPLES = r'''
     domain_admin_password: password123!
     safe_mode_password: password123!
     state: domain_controller
-    log_path: c:\ansible_win_domain_controller.txt
+    log_path: C:\ansible_win_domain_controller.txt
 
 # ensure a server is not a domain controller
 # note that without an action wrapper, in the case where a DC is demoted,
@@ -102,7 +99,7 @@ EXAMPLES = r'''
     domain_admin_password: password123!
     local_admin_password: password123!
     state: member_server
-    log_path: c:\ansible_win_domain_controller.txt
+    log_path: C:\ansible_win_domain_controller.txt
 
 - name: promote server as a read only domain controller
   win_domain_controller:

lib/ansible/modules/windows/win_domain_group.py

@@ -1,20 +1,18 @@
 #!/usr/bin/python
+# -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2017, Ansible Project
-
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_domain_group
 version_added: '2.4'
-short_description: creates, modifies or removes domain groups
+short_description: Creates, modifies or removes domain groups
 description:
 - Creates, modifies or removes groups in Active Directory.
 - For local groups, use the M(win_group) module instead.
@@ -57,7 +55,7 @@ options:
     - Will ignore the C(ProtectedFromAccidentalDeletion) flag when deleting or
       moving a group.
     - The module will fail if one of these actions need to occur and this value
-      is set to no.
+      is set to C(no).
     type: bool
     default: 'no'
   managed_by:
@@ -94,8 +92,8 @@ options:
     - If C(state=present) this module will ensure the group is created and is
       configured accordingly.
     - If C(state=absent) this module will delete the group if it exists
-    default: present
     choices: [ absent, present ]
+    default: present
 notes:
 - This must be run on a host that has the ActiveDirectory powershell module
   installed.
@@ -104,24 +102,24 @@ author:
 '''
 
 EXAMPLES = r'''
-- name: ensure the group Cow exists using sAMAccountName
+- name: Ensure the group Cow exists using sAMAccountName
   win_domain_group:
     name: Cow
     scope: global
     path: OU=groups,DC=ansible,DC=local
 
-- name: ensure the group Cow does't exist using the Distinguished Name
+- name: Ensure the group Cow does't exist using the Distinguished Name
   win_domain_group:
     name: CN=Cow,OU=groups,DC=ansible,DC=local
     state: absent
 
-- name: delete group ignoring the protection flag
+- name: Delete group ignoring the protection flag
   win_domain_group:
     name: Cow
     state: absent
     ignore_protection: yes
 
-- name: create group with delete protection enabled and custom attributes
+- name: Create group with delete protection enabled and custom attributes
   win_domain_group:
     name: Ansible Users
     scope: domainlocal
@@ -131,19 +129,19 @@ EXAMPLES = r'''
       wWWHomePage: www.ansible.com
     ignore_protection: yes
 
-- name: change the OU of a group using the SID and ignore the protection flag
+- name: Change the OU of a group using the SID and ignore the protection flag
   win_domain_group:
     name: S-1-5-21-2171456218-3732823212-122182344-1189
     scope: global
     organizational_unit: OU=groups,DC=ansible,DC=local
-    ignore_protection: True
+    ignore_protection: yes
 
-- name: add managed_by user
+- name: Add managed_by user
   win_domain_group:
     name: Group Name Here
     managed_by: Domain Admins
 
-- name: add group and specify the AD domain services to use for the create
+- name: Add group and specify the AD domain services to use for the create
   win_domain_group:
     name: Test Group
     domain_username: user@CORP.ANSIBLE.COM

lib/ansible/modules/windows/win_domain_membership.py

@@ -1,50 +1,34 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Red Hat, Inc.
+# Copyright: (c) 2017, Red Hat, Inc.
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = '''
 module: win_domain_membership
 short_description: Manage domain/workgroup membership for a Windows host
-version_added: 2.3
+version_added: '2.3'
 description:
-     - Manages domain membership or workgroup membership for a Windows host. Also supports hostname changes. This module may require
+- Manages domain membership or workgroup membership for a Windows host. Also supports hostname changes.
-       subsequent use of the M(win_reboot) action if changes are made.
+- This module may require subsequent use of the M(win_reboot) action if changes are made.
 options:
   dns_domain_name:
     description:
-      - when C(state) is C(domain), the DNS name of the domain to which the targeted Windows host should be joined
+      - When C(state) is C(domain), the DNS name of the domain to which the targeted Windows host should be joined.
   domain_admin_user:
     description:
-      - username of a domain admin for the target domain (required to join or leave the domain)
+      - Username of a domain admin for the target domain (required to join or leave the domain).
-    required: true
+    required: yes
   domain_admin_password:
     description:
-      - password for the specified C(domain_admin_user)
+      - Password for the specified C(domain_admin_user).
   hostname:
     description:
-      - the desired hostname for the Windows host
+      - The desired hostname for the Windows host.
   domain_ou_path:
     description:
       - The desired OU path for adding the computer object.
@@ -52,13 +36,11 @@ options:
     version_added: "2.4"
   state:
     description:
-      - whether the target host should be a member of a domain or workgroup
+      - Whether the target host should be a member of a domain or workgroup.
-    choices:
+    choices: [ domain, workgroup ]
-      - domain
-      - workgroup
   workgroup_name:
     description:
-      - when C(state) is C(workgroup), the name of the workgroup that the Windows host should be in
+      - When C(state) is C(workgroup), the name of the workgroup that the Windows host should be in.
 author:
     - Matt Davis (@nitzmahone)
 '''

lib/ansible/modules/windows/win_domain_user.py

@@ -1,8 +1,6 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
-
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -12,7 +10,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_domain_user
@@ -30,14 +27,12 @@ options:
       - When C(present), creates or updates the user account.  When C(absent),
         removes the user account if it exists.  When C(query),
         retrieves the user account details without making any changes.
-    choices:
+    choices: [ absent, present, query ]
-      - present
-      - absent
-      - query
     default: present
   enabled:
     description:
-      - C(yes) will enable the user account. C(no) will disable the account.
+      - C(yes) will enable the user account.
+      - C(no) will disable the account.
     type: bool
     default: 'yes'
   account_locked:
@@ -45,9 +40,8 @@ options:
       - C(no) will unlock the user account if locked. Note that there is not a
         way to lock an account as an administrator. Accounts are locked due to
         user actions; as an admin, you may only unlock a locked account. If you
-        wish to administratively disable an account, set 'enabled' to 'no'.
+        wish to administratively disable an account, set I(enabled) to C(no).
     choices: [ 'no' ]
-    type: bool
   description:
     description:
       - Description of the user
@@ -60,11 +54,12 @@ options:
         their principal group (for example, "Domain Users").
   groups_action:
     description:
+      - If C(add), the user is added to each group in I(groups) where not
+        already a member.
+      - If C(remove), the user is removed from each group in I(groups).
       - If C(replace), the user is added as a member of each group in
-        I(groups) and removed from any other groups.  If C(add), the user is
+        I(groups) and removed from any other groups.
-        added to each group in I(groups) where not already a member.  If
+    choices: [ add, remove, replace ]
-        C(remove), the user is removed from each group in I(groups).
-    choices: [ 'replace', 'add', 'remove' ]
     default: replace
   password:
     description:
@@ -73,67 +68,71 @@ options:
         configured on the account, or you must provide a password here.
   update_password:
     description:
-      - C(always) will update passwords if they differ.  C(on_create) will
+      - C(always) will update passwords if they differ.
-        only set the password for newly created users. Note that C(always) will
+      - C(on_create) will only set the password for newly created users.
-        always report an Ansible status of 'changed' because we cannot
+      - Note that C(always) will always report an Ansible status of 'changed'
-        determine whether the new password differs from the old password.
+        because we cannot determine whether the new password differs from
-    choices: [ 'always', 'on_create' ]
+        the old password.
+    choices: [ always, on_create ]
     default: always
   password_expired:
     description:
       - C(yes) will require the user to change their password at next login.
-        C(no) will clear the expired password flag. This is mutually exclusive
+      - C(no) will clear the expired password flag.
-        with I(password_never_expires).
+      - This is mutually exclusive with I(password_never_expires).
     type: bool
   password_never_expires:
     description:
-      - C(yes) will set the password to never expire.  C(no) will allow the
+      - C(yes) will set the password to never expire.
-        password to expire. This is mutually exclusive with I(password_expired)
+      - C(no) will allow the password to expire.
+      - This is mutually exclusive with I(password_expired).
     type: bool
   user_cannot_change_password:
     description:
-      - C(yes) will prevent the user from changing their password.  C(no) will
+      - C(yes) will prevent the user from changing their password.
-        allow the user to change their password.
+      - C(no) will allow the user to change their password.
     type: bool
   firstname:
     description:
-      - Configures the user's first name (given name)
+      - Configures the user's first name (given name).
   surname:
     description:
-      - Configures the user's last name (surname)
+      - Configures the user's last name (surname).
   company:
     description:
-      - Configures the user's company name
+      - Configures the user's company name.
   upn:
     description:
-      - Configures the User Principal Name (UPN) for the account. This is not
+      - Configures the User Principal Name (UPN) for the account.
-        required, but is best practice to configure for modern versions of
+      - This is not required, but is best practice to configure for modern
-        Active Directory. The format is "<username>@<domain>".
+        versions of Active Directory.
+      - The format is C(<username>@<domain>).
   email:
     description:
-      - Configures the user's email address. This is a record in AD and does
+      - Configures the user's email address.
-        not do anything to configure any email servers or systems.
+      - This is a record in AD and does not do anything to configure any email
+        servers or systems.
   street:
     description:
-      - Configures the user's street address
+      - Configures the user's street address.
   city:
     description:
-      - Configures the user's city
+      - Configures the user's city.
   state_province:
     description:
-      - Configures the user's state or province
+      - Configures the user's state or province.
   postal_code:
     description:
-      - Configures the user's postal code / zip code
+      - Configures the user's postal code / zip code.
   country:
     description:
-      - Configures the user's country code. Note that this is a two-character
+      - Configures the user's country code.
-        ISO 3166 code.
+      - Note that this is a two-character ISO 3166 code.
   path:
     description:
       - Container or OU for the new user; if you do not specify this, the
         user will be placed in the default container for users in the domain.
-        Setting the path is only available when a new user is created;
+      - Setting the path is only available when a new user is created;
         if you specify a path on an existing user, the user's path will not
         be updated - you must delete (e.g., state=absent) the user and
         then re-add the user with the appropriate path.
@@ -143,7 +142,7 @@ options:
       - This can be used to set custom attributes that are not exposed as module
         parameters, e.g. C(telephoneNumber).
       - See the examples on how to format this parameter.
-    version_added: "2.5"
+    version_added: '2.5'
   domain_username:
     description:
     - The username to use when interacting with AD.
@@ -152,7 +151,7 @@ options:
     version_added: '2.5'
   domain_password:
     description:
-    - The password for C(username).
+    - The password for I(username).
     version_added: '2.5'
   domain_server:
     description:

lib/ansible/modules/windows/win_dotnet_ngen.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Peter Mounce <public@neverrunwithscissors.com>
+# Copyright: (c) 2015, Peter Mounce <public@neverrunwithscissors.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_dotnet_ngen
@@ -35,12 +20,13 @@ description:
     - After .NET framework is installed/updated, Windows will probably want to recompile things to optimise for the host.
     - This happens via scheduled task, usually at some inopportune time.
     - This module allows you to run this task on your own schedule, so you incur the CPU hit at some more convenient and controlled time.
-    - "http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx"
+    - U(http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx)
 notes:
-    - there are in fact two scheduled tasks for ngen but they have no triggers so aren't a problem
+    - There are in fact two scheduled tasks for ngen but they have no triggers so aren't a problem.
-    - there's no way to test if they've been completed (?)
+    - There's no way to test if they've been completed.
-    - the stdout is quite likely to be several megabytes
+    - The stdout is quite likely to be several megabytes.
-author: Peter Mounce
+author:
+- Peter Mounce (@petemounce)
 options: {}
 '''
 

lib/ansible/modules/windows/win_dsc.py

@@ -1,13 +1,10 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2015, Trond Hindenes <trond@hindenes.com>, and others
-
+# Copyright: (c) 2017, Ansible Project
-# (c) 2015, Trond Hindenes <trond@hindenes.com>, and others
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
@@ -28,7 +25,7 @@ options:
     description:
     - The name of the DSC Resource to use.
     - Must be accessible to PowerShell using any of the default paths.
-    required: true
+    required: yes
   module_version:
     description:
     - Can be used to configure the exact version of the DSC resource to be

lib/ansible/modules/windows/win_environment.py

@@ -26,7 +26,7 @@ options:
   name:
     description:
     - The name of the environment variable.
-    required: true
+    required: yes
   value:
     description:
     - The value to store in the environment variable.
@@ -38,7 +38,7 @@ options:
     - Use C(user) to set for the current user that ansible is connected as.
     - Use C(process) to set for the current process.  Probably not that useful.
     choices: [ machine, user, process ]
-    required: true
+    required: yes
 author:
 - Jon Hawkesworth (@jhawkesworth)
 notes:

lib/ansible/modules/windows/win_eventlog.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
+# Copyright: (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -38,17 +24,14 @@ options:
   name:
     description:
       - Name of the event log to manage.
-    required: true
+    required: yes
   state:
     description:
       - Desired state of the log and/or sources.
       - When C(sources) is populated, state is checked for sources.
       - When C(sources) is not populated, state is checked for the specified log itself.
       - If C(state) is C(clear), event log entries are cleared for the target log.
-    choices:
+    choices: [ absent, clear, present ]
-      - present
-      - clear
-      - absent
     default: present
   sources:
     description:

lib/ansible/modules/windows/win_eventlog_entry.py

@@ -1,4 +1,5 @@
 #!/usr/bin/python
+# -*- coding: utf-8 -*-
 
 # (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
@@ -18,20 +19,20 @@ options:
   log:
     description:
       - Name of the event log to write an entry to.
-    required: true
+    required: yes
   source:
     description:
       - Name of the log source to indicate where the entry is from.
-    required: true
+    required: yes
   event_id:
     description:
       - The numeric event identifier for the entry.
       - Value must be between 0 and 65535.
-    required: true
+    required: yes
   message:
     description:
       - The message for the given log entry.
-    required: true
+    required: yes
   entry_type:
     description:
       - Indicates the entry being written to the log is of a specific type.

lib/ansible/modules/windows/win_feature.py

@@ -26,13 +26,11 @@ options:
   name:
     description:
       - Names of roles or features to install as a single feature or a comma-separated list of features.
-    required: true
+    required: yes
   state:
     description:
       - State of the features or roles on the system.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
     default: present
   restart:
     description:
@@ -59,8 +57,8 @@ options:
       - Can either be C({driveletter}:\sources\sxs) or C(\\{IP}\share\sources\sxs).
     version_added: "2.1"
 author:
-    - "Paul Durivage (@angstwad)"
+    - Paul Durivage (@angstwad)
-    - "Trond Hindenes (@trondhindenes)"
+    - Trond Hindenes (@trondhindenes)
 '''
 
 EXAMPLES = r'''
@@ -86,8 +84,8 @@ EXAMPLES = r'''
   win_feature:
     name: Web-Server
     state: present
-    include_sub_features: True
+    include_sub_features: yes
-    include_management_tools: True
+    include_management_tools: yes
   register: win_feature
 
 - name: reboot if installing Web-Server feature requires it

lib/ansible/modules/windows/win_file.py

@@ -1,34 +1,18 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright: (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_file
 version_added: "1.9.2"
-short_description: Creates, touches or removes files or directories.
+short_description: Creates, touches or removes files or directories
 description:
      - Creates (empty) files, updates file modification stamps of existing files,
        and can create or remove directories.
@@ -37,25 +21,25 @@ description:
 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:
-author: "Jon Hawkesworth (@jhawkesworth)"
+- Jon Hawkesworth (@jhawkesworth)
 options:
   path:
     description:
-      - 'path to the file being managed.  Aliases: I(dest), I(name)'
+      - Path to the file being managed.
-    required: true
+    required: yes
-    aliases: ['dest', 'name']
+    aliases: [ dest, name ]
   state:
     description:
       - If C(directory), all immediate subdirectories will be created if they
         do not exist.
-        If C(file), the file will NOT be created if it does not exist, see the M(copy)
+      - If C(file), the file will NOT be created if it does not exist, see the M(copy)
         or M(template) module if you want that behavior.  If C(absent),
         directories will be recursively deleted, and files will be removed.
-        If C(touch), an empty file will be created if the C(path) does not
+      - If C(touch), an empty file will be created if the C(path) does not
         exist, while an existing file or directory will receive updated file access and
         modification times (similar to the way C(touch) works from the command line).
-    choices: [ file, directory, touch, absent ]
+    choices: [ absent, directory, file, touch ]
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_file_version.py

@@ -1,42 +1,30 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-# Get DLL or EXE build version
+# Copyright: (c) 2015, Sam Liu <sam.liu@activenetwork.com>
-# Copyright © 2015 Sam Liu <sam.liu@activenetwork.com>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_file_version
 version_added: "2.1"
 short_description: Get DLL or EXE file build version
 description:
-  - Get DLL or EXE file build version
+  - Get DLL or EXE file build version.
-  - change state alway be false
+notes:
+  - This module will always return no change.
 options:
   path:
     description:
-      - File to get version(provide absolute path)
+      - File to get version.
-    required: true
+      - Always provide absolute path.
-    aliases: []
+    required: yes
-author: Sam Liu
+author:
+- Sam Liu (@SamLiu79)
 '''
 
 EXAMPLES = r'''
@@ -84,5 +72,4 @@ win_file_version.file_private_part:
   description: file private part number.
   returned: no error
   type: string
-
 '''

lib/ansible/modules/windows/win_find.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2016 Ansible Project
+# Copyright: (c) 2016, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -32,22 +32,22 @@ options:
         description:
             - Choose the file property against which we compare C(age). The
               default attribute we compare with is the last modification time.
+        choices: [ atime, ctime, mtime ]
         default: mtime
-        choices: ['atime', 'mtime', 'ctime']
     checksum_algorithm:
         description:
             - Algorithm to determine the checksum of a file. Will throw an error
               if the host is unable to use specified algorithm.
+        choices: [ md5, sha1, sha256, sha384, sha512 ]
         default: sha1
-        choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512']
     file_type:
         description: Type of file to search for.
+        choices: [ directory, file ]
         default: file
-        choices: ['file', 'directory']
     follow:
         description:
-            - Set this to true to follow symlinks in the path. This needs to
+            - Set this to C(yes) to follow symlinks in the path.
-              be used in conjunction with C(recurse).
+            - This needs to be used in conjunction with C(recurse).
         type: bool
         default: 'no'
     get_checksum:
@@ -64,7 +64,7 @@ options:
         description:
             - List of paths of directories to search for files or folders in.
               This can be supplied as a single path or a list of paths.
-        required: true
+        required: yes
     patterns:
         description:
             - One or more (powershell or regex) patterns to compare filenames
@@ -87,7 +87,7 @@ options:
               evaluated for symbolic links.
     use_regex:
         description:
-            - Will set patterns to run as a regex check if true.
+            - Will set patterns to run as a regex check if set to C(yes).
         type: bool
         default: 'no'
 author:
@@ -97,99 +97,103 @@ author:
 EXAMPLES = r'''
 - name: Find files in path
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
 
 - name: Find hidden files in path
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
-    hidden: True
+    hidden: yes
 
 - name: Find files in multiple paths
   win_find:
-    paths: ['C:\temp', 'D:\temp']
+    paths:
+    - C:\Temp
+    - D:\Temp
 
 - name: Find files in directory while searching recursively
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
-    recurse: True
+    recurse: yes
 
 - name: Find files in directory while following symlinks
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
-    recurse: True
+    recurse: yes
-    follow: True
+    follow: yes
 
 - name: Find files with .log and .out extension using powershell wildcards
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
-    patterns: ['*.log', '*.out']
+    patterns: [ '*.log', '*.out' ]
 
 - name: Find files in path based on regex pattern
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
-    patterns: 'out_\d{8}-\d{6}.log'
+    patterns: out_\d{8}-\d{6}.log
 
 - name: Find files older than 1 day
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     age: 86400
 
 - name: Find files older than 1 day based on create time
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     age: 86400
     age_stamp: ctime
 
 - name: Find files older than 1 day with unit syntax
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     age: 1d
 
 - name: Find files newer than 1 hour
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     age: -3600
 
 - name: Find files newer than 1 hour with unit syntax
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     age: -1h
 
 - name: Find files larger than 1MB
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     size: 1048576
 
 - name: Find files larger than 1GB with unit syntax
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     size: 1g
 
 - name: Find files smaller than 1MB
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     size: -1048576
 
 - name: Find files smaller than 1GB with unit syntax
   win_find:
-    paths: D:\temp
+    paths: D:\Temp
     size: -1g
 
 - name: Find folders/symlinks in multiple paths
   win_find:
-    paths: ['C:\temp', 'D:\temp']
+    paths:
+    - C:\Temp
+    - D:\Temp
     file_type: directory
 
 - name: Find files and return SHA256 checksum of files found
   win_find:
-    paths: C:\temp
+    paths: C:\Temp
-    get_checksum: True
+    get_checksum: yes
     checksum_algorithm: sha256
 
 - name: Find files and do not return the checksum
   win_find:
-    path: C:\temp
+    path: C:\Temp
-    get_checksum: False
+    get_checksum: no
 '''
 
 RETURN = r'''

lib/ansible/modules/windows/win_firewall.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Michael Eaton <meaton@iforium.com>
+# Copyright: (c) 2017, Michael Eaton <meaton@iforium.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -49,7 +35,8 @@ options:
     - disabled
 requirements:
   - This module requires Windows Management Framework 5 or later.
-author: Michael Eaton (@if-meaton)
+author:
+- Michael Eaton (@if-meaton)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_firewall_rule.py

@@ -1,13 +1,14 @@
 #!/usr/bin/env python
-# Copyright (c) 2017 Artem Zinenko <zinenkoartem@gmail.com>
+# -*- coding: utf-8 -*-
-# Copyright (c) 2014 Timothy Vandenbrande <timothy.vandenbrande@gmail.com>
+
+# Copyright: (c) 2014, Timothy Vandenbrande <timothy.vandenbrande@gmail.com>
+# Copyright: (c) 2017, Artem Zinenko <zinenkoartem@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_firewall_rule
@@ -24,37 +25,37 @@ options:
       - Is this firewall rule enabled or disabled.
     type: bool
     default: 'yes'
-    aliases: [ 'enable' ]
+    aliases: [ enable ]
   state:
     description:
       - Should this rule be added or removed.
-    default: "present"
+    choices: [ absent, present ]
-    choices: ['present', 'absent']
+    default: present
   name:
     description:
       - The rules name
-    required: true
+    required: yes
   direction:
     description:
       - Is this rule for inbound or outbound traffic.
-    required: true
+    required: yes
-    choices: ['in', 'out']
+    choices: [ in, out ]
   action:
     description:
       - What to do with the items this rule is for.
-    required: true
+    required: yes
-    choices: ['allow', 'block', 'bypass']
+    choices: [ allow, block, bypass ]
   description:
     description:
       - Description for the firewall rule.
   localip:
     description:
       - The local ip address this rule applies to.
-    default: 'any'
+    default: any
   remoteip:
     description:
       - The remote ip address/range this rule applies to.
-    default: 'any'
+    default: any
   localport:
     description:
       - The local port this rule applies to.
@@ -70,19 +71,19 @@ options:
   protocol:
     description:
       - The protocol this rule applies to.
-    default: 'any'
+    default: any
   profiles:
     description:
       - The profile this rule applies to.
-    default: 'domain,private,public'
+    default: domain,private,public
-    aliases: [ 'profile' ]
+    aliases: [ profile ]
   force:
     description:
     - Replace any existing rule by removing it first.
     - This is no longer required in 2.4 as rules no longer need replacing when being modified.
     - DEPRECATED in 2.4 and will be removed in 2.9.
+    type: bool
     default: 'no'
-    choices: [ 'no', 'yes' ]
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_get_url.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Paul Durivage <paul.durivage@rackspace.com>, and others
+# Copyright: (c) 2014, Paul Durivage <paul.durivage@rackspace.com>, and others
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -35,7 +21,7 @@ description:
 - For non-Windows targets, use the M(get_url) module instead.
 author:
 - Paul Durivage (@angstwad)
-- Takeshi Kuramochi (tksarah)
+- Takeshi Kuramochi (@tksarah)
 options:
   url:
     description:

lib/ansible/modules/windows/win_group.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Chris Hoffman <choffman@chathamfinancial.com>
+# Copyright: (c) 2014, Chris Hoffman <choffman@chathamfinancial.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_group
@@ -37,28 +22,20 @@ description:
 options:
   name:
     description:
-      - Name of the group
+      - Name of the group.
-    required: true
+    required: yes
-    default: null
-    aliases: []
   description:
     description:
-      - Description of the group
+      - Description of the group.
-    required: false
-    default: null
-    aliases: []
   state:
     description:
-      - Create or remove the group
+      - Create or remove the group.
-    required: false
+    choices: [ absent, present ]
-    choices:
-      - present
-      - absent
     default: present
-    aliases: []
 notes:
     - For non-Windows targets, please use the M(group) module instead.
-author: "Chris Hoffman (@chrishoffman)"
+author:
+- Chris Hoffman (@chrishoffman)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_group_membership.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
+# Copyright: (c) 2017, Andrew Saraceni <andrew.saraceni@gmail.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -37,20 +23,18 @@ options:
   name:
     description:
       - Name of the local group to manage membership on.
-    required: true
+    required: yes
   members:
     description:
       - A list of members to ensure are present/absent from the group.
       - Accepts local users as username, .\username, and SERVERNAME\username.
       - Accepts domain users and groups as DOMAIN\username and username@DOMAIN.
       - Accepts service users as NT AUTHORITY\username.
-    required: true
+    required: yes
   state:
     description:
       - Desired state of the members in the group.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
     default: present
 author:
     - Andrew Saraceni (@andrewsaraceni)

lib/ansible/modules/windows/win_hotfix.py

@@ -1,18 +1,7 @@
 #!/usr/bin/python
-# This file is part of Ansible
+# -*- coding: utf-8 -*-
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub, actual code lives in the .ps1
 # file of the same name
@@ -21,12 +10,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_hotfix
 version_added: '2.4'
-short_description: install and uninstalls Windows hotfixes
+short_description: Install and uninstalls Windows hotfixes
 description:
 - Install, uninstall a Windows hotfix.
 options:

lib/ansible/modules/windows/win_iis_virtualdirectory.py

@@ -1,63 +1,43 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
+# Copyright: (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_iis_virtualdirectory
 version_added: "2.0"
-short_description: Configures a virtual directory in IIS.
+short_description: Configures a virtual directory in IIS
 description:
      - Creates, Removes and configures a virtual directory in IIS.
 options:
   name:
     description:
-      - The name of the virtual directory to create or remove
+      - The name of the virtual directory to create or remove.
-    required: true
+    required: yes
   state:
     description:
-      - Whether to add or remove the specified virtual directory
+      - Whether to add or remove the specified virtual directory.
-    choices:
+    choices: [ absent, present ]
-      - absent
-      - present
-    required: false
     default: present
   site:
     description:
       - The site name under which the virtual directory is created or exists.
-    required: true
+    required: yes
   application:
     description:
       - The application under which the virtual directory is created or exists.
-    required: false
-    default: null
   physical_path:
     description:
-      - The physical path to the folder in which the new virtual directory is created. The specified folder must already exist.
+      - The physical path to the folder in which the new virtual directory is created.
-    required: false
+      - The specified folder must already exist.
-    default: null
+author:
-author: Henrik Wallström
+- Henrik Wallström
 '''
 
 EXAMPLES = r'''
@@ -66,7 +46,7 @@ EXAMPLES = r'''
     name: somedirectory
     site: somesite
     state: present
-    physical_path: c:\virtualdirectory\some
+    physical_path: C:\virtualdirectory\some
 
 - name: Remove a virtual directory if it exists
   win_iis_virtualdirectory:
@@ -80,5 +60,5 @@ EXAMPLES = r'''
     site: somesite
     application: someapp
     state: present
-    physical_path: c:\virtualdirectory\some
+    physical_path: C:\virtualdirectory\some
 '''

lib/ansible/modules/windows/win_iis_webapplication.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
+# Copyright: (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
@@ -33,11 +19,11 @@ options:
   name:
     description:
     - Name of the web application.
-    required: true
+    required: yes
   site:
     description:
     - Name of the site on which the application is created.
-    required: true
+    required: yes
   state:
     description:
     - State of the web application.

lib/ansible/modules/windows/win_iis_webapppool.py

@@ -1,33 +1,18 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
+# Copyright: (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_iis_webapppool
 version_added: "2.0"
-short_description: configures an IIS Web Application Pool
+short_description: Configure IIS Web Application Pools
 description:
   - Creates, removes and configures an IIS Web Application Pool.
 options:
@@ -59,26 +44,21 @@ options:
   name:
     description:
       - Name of the application pool.
-    required: true
+    required: yes
   state:
-    choices:
+    choices: [ absent, present, restarted, started, stopped ]
-      - present
-      - absent
-      - stopped
-      - started
-      - restarted
     default: present
     description:
       - The state of the application pool.
-      - If C(present) will ensure the app pool is configured and exists.
       - If C(absent) will ensure the app pool is removed.
-      - If C(stopped) will ensure the app pool exists and is stopped.
+      - If C(present) will ensure the app pool is configured and exists.
-      - If C(started) will ensure the app pool exists and is started.
       - If C(restarted) will ensure the app pool exists and will restart, this
         is never idempotent.
+      - If C(started) will ensure the app pool exists and is started.
+      - If C(stopped) will ensure the app pool exists and is stopped.
 author:
-  - "Henrik Wallström (@henrikwallstrom)"
+- Henrik Wallström (@henrikwallstrom)
-  - "Jordan Borean (@jborean93)"
+- Jordan Borean (@jborean93)
 '''
 
 EXAMPLES = r'''
@@ -107,7 +87,7 @@ EXAMPLES = r'''
     name: AppPool
     attributes:
       managedRuntimeVersion: v4.0
-      autoStart: false
+      autoStart: no
 
 # Note this format style has been deprecated, please use the newer dict style instead
 - name: change application pool attributes using older string style
@@ -122,7 +102,7 @@ EXAMPLES = r'''
     state: started
     attributes:
       managedRuntimeVersion: v4.0
-      autoStart: false
+      autoStart: no
 
 # In the below example we are setting attributes in child element processModel
 # https://www.iis.net/configreference/system.applicationhost/applicationpools/add/processmodel

lib/ansible/modules/windows/win_iis_webbinding.py

@@ -5,31 +5,27 @@
 # Copyright: (c) 2017, Henrik Wallström <henrik@wallstroms.nu>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_iis_webbinding
 version_added: "2.0"
-short_description: Configures a IIS Web site binding.
+short_description: Configures a IIS Web site binding
 description:
-     - Creates, Removes and configures a binding to an existing IIS Web site
+     - Creates, removes and configures a binding to an existing IIS Web site.
 options:
   name:
     description:
-      - Names of web site
+      - Names of web site.
-    required: true
+    required: yes
-    aliases: [website]
+    aliases: [ website ]
   state:
     description:
-      - State of the binding
+      - State of the binding.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
     default: present
   port:
     description:
@@ -53,7 +49,7 @@ options:
   certificate_store_name:
     description:
       - Name of the certificate store where the certificate for the binding is located.
-    default: "my"
+    default: my
   ssl_flags:
     description:
       - This parameter is only valid on Server 2012 and newer.

lib/ansible/modules/windows/win_iis_website.py

@@ -1,102 +1,58 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
+# Copyright: (c) 2015, Henrik Wallström <henrik@wallstroms.nu>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_iis_website
 version_added: "2.0"
-short_description: Configures a IIS Web site.
+short_description: Configures a IIS Web site
 description:
-     - Creates, Removes and configures a IIS Web site
+     - Creates, Removes and configures a IIS Web site.
 options:
   name:
     description:
-      - Names of web site
+      - Names of web site.
-    required: true
+    required: yes
-    default: null
-    aliases: []
   site_id:
     description:
-      - Explicitly set the IIS numeric ID for a site. Note that this value cannot be changed after the website has been created.
+      - Explicitly set the IIS numeric ID for a site.
-    required: false
+      - Note that this value cannot be changed after the website has been created.
     version_added: "2.1"
-    default: null
   state:
     description:
       - State of the web site
-    choices:
+    choices: [ absent, started, stopped, restarted ]
-      - started
-      - restarted
-      - stopped
-      - absent
-    required: false
-    default: null
-    aliases: []
   physical_path:
     description:
-      - The physical path on the remote host to use for the new site. The specified folder must already exist.
+      - The physical path on the remote host to use for the new site.
-    required: false
+      - The specified folder must already exist.
-    default: null
-    aliases: []
   application_pool:
     description:
       - The application pool in which the new site executes.
-    required: false
-    default: null
-    aliases: []
   port:
     description:
       - The port to bind to / use for the new site.
-    required: false
-    default: null
-    aliases: []
   ip:
     description:
       - The IP address to bind to / use for the new site.
-    required: false
-    default: null
-    aliases: []
   hostname:
     description:
       - The host header to bind to / use for the new site.
-    required: false
-    default: null
-    aliases: []
   ssl:
     description:
       - Enables HTTPS binding on the site..
-    required: false
-    default: null
-    aliases: []
   parameters:
     description:
       - Custom site Parameters from string where properties are separated by a pipe and property name/values by colon Ex. "foo:1|bar:2"
-    required: false
+author:
-    default: null
+- Henrik Wallström
-    aliases: []
-author: Henrik Wallström
 '''
 
 EXAMPLES = r'''
@@ -105,14 +61,14 @@ EXAMPLES = r'''
 
 - name: Acme IIS site
   win_iis_website:
-    name: "Acme"
+    name: Acme
     state: started
     port: 80
     ip: 127.0.0.1
     hostname: acme.local
-    application_pool: "acme"
+    application_pool: acme
-    physical_path: c:\sites\acme
+    physical_path: C:\sites\acme
-    parameters: logfile.directory:c:\sites\logs
+    parameters: logfile.directory:C:\sites\logs
   register: website
 
 # Remove Default Web Site and the standard port 80 binding
@@ -143,8 +99,8 @@ EXAMPLES = r'''
 # $ ansible -i hosts -m win_iis_website -a "name='Default Web Site' state=stopped" host
 
 # This creates a new site.
-# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
+# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=C:\\sites\\acme" host
 
 # Change logfile.
-# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
+# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=C:\\sites\\acme" host
 '''

lib/ansible/modules/windows/win_lineinfile.py

@@ -1,122 +1,94 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-#
+
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_lineinfile
-author: "Brian Lloyd <brian.d.lloyd@gmail.com>"
+author:
-short_description: Ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression.
+- Brian Lloyd (@brianlloyd)
+short_description: Ensure a particular line is in a file, or replace an existing line using a back-referenced regular expression
 description:
   - This module will search a file for a line, and ensure that it is present or absent.
   - This is primarily useful when you want to change a single line in a file only.
 version_added: "2.0"
 options:
   path:
-    required: true
-    aliases: [ dest, destfile, name ]
     description:
       - The path of the file to modify.
       - Note that the Windows path delimiter C(\) must be escaped as C(\\) when the line is double quoted.
       - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name).
+    required: yes
+    aliases: [ dest, destfile, name ]
   regexp:
-    required: false
     description:
-      - >
+      - The regular expression to look for in every line of the file. For C(state=present), the pattern to replace if found; only the last line found
-        The regular expression to look for in every line of the file. For C(state=present), the pattern to replace if found; only the last line found
         will be replaced. For C(state=absent), the pattern of the line to remove. Uses .NET compatible regular expressions;
         see U(https://msdn.microsoft.com/en-us/library/hs600312%28v=vs.110%29.aspx).
   state:
-    required: false
-    choices: [ present, absent ]
-    default: "present"
     description:
       - Whether the line should be there or not.
+    choices: [ absent, present ]
+    default: present
   line:
-    required: false
     description:
       - Required for C(state=present). The line to insert/replace into the file. If C(backrefs) is set, may contain backreferences that will get
         expanded with the C(regexp) capture groups if the regexp matches.
   backrefs:
-    required: false
-    default: "no"
-    choices: [ "yes", "no" ]
     description:
       - Used with C(state=present). If set, line can contain backreferences (both positional and named) that will get populated if the C(regexp)
         matches. This flag changes the operation of the module slightly; C(insertbefore) and C(insertafter) will be ignored, and if the C(regexp)
         doesn't match anywhere in the file, the file will be left unchanged.
       - If the C(regexp) does match, the last matching line will be replaced by the expanded line parameter.
+    type: bool
+    default: 'no'
   insertafter:
-    required: false
-    default: EOF
     description:
       - Used with C(state=present). If specified, the line will be inserted after the last match of specified regular expression. A special value is
         available; C(EOF) for inserting the line at the end of the file.
       - If specified regular expression has no matches, EOF will be used instead. May not be used with C(backrefs).
-    choices: [ 'EOF', '*regex*' ]
+    choices: [ EOF, '*regex*' ]
+    default: EOF
   insertbefore:
-    required: false
     description:
       - Used with C(state=present). If specified, the line will be inserted before the last match of specified regular expression. A value is available;
         C(BOF) for inserting the line at the beginning of the file.
       - If specified regular expression has no matches, the line will be inserted at the end of the file. May not be used with C(backrefs).
-    choices: [ 'BOF', '*regex*' ]
+    choices: [ BOF, '*regex*' ]
   create:
-    required: false
-    choices: [ "yes", "no" ]
-    default: "no"
     description:
       - Used with C(state=present). If specified, the file will be created if it does not already exist. By default it will fail if the file is missing.
+    type: bool
+    default: 'no'
   backup:
-    required: false
-    default: "no"
-    choices: [ "yes", "no" ]
     description:
       - Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.
+    type: bool
+    default: 'no'
   validate:
-    required: false
     description:
       - Validation to run before copying into place. Use %s in the command to indicate the current file to validate.
       - The command is passed securely so shell features like expansion and pipes won't work.
-    default: None
   encoding:
-    required: false
-    default: "auto"
     description:
       - Specifies the encoding of the source text file to operate on (and thus what the output encoding will be). The default of C(auto) will cause
         the module to auto-detect the encoding of the source file and ensure that the modified file is written with the same encoding.
-      - >
+      - An explicit encoding can be passed as a string that is a valid value to pass to the .NET framework System.Text.Encoding.GetEncoding() method -
-        An explicit encoding can be passed as a string that is a valid value to pass to the .NET framework System.Text.Encoding.GetEncoding() method - see
+        see U(https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx).
-        U(https://msdn.microsoft.com/en-us/library/system.text.encoding%28v=vs.110%29.aspx).
       - This is mostly useful with C(create=yes) if you want to create a new file with a specific encoding. If C(create=yes) is specified without a
         specific encoding, the default encoding (UTF-8, no BOM) will be used.
+    default: auto
   newline:
-    required: false
     description:
-      - >
+      - Specifies the line separator style to use for the modified file. This defaults to the windows line separator (C(\r\n)). Note that the indicated
-        Specifies the line separator style to use for the modified file. This defaults to the windows line separator (C(\r\n)). Note that the indicated
         line separator will be used for file output regardless of the original line separator that appears in the input file.
-    choices: [ "windows", "unix" ]
+    choices: [ unix, windows ]
-    default: "windows"
+    default: windows
 notes:
   - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well.
 '''
@@ -124,48 +96,48 @@ notes:
 EXAMPLES = r'''
 # Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
 - win_lineinfile:
-    path: C:\temp\example.conf
+    path: C:\Temp\example.conf
     regexp: '^name='
     line: 'name=JohnDoe'
 
 - win_lineinfile:
-    path: C:\temp\example.conf
+    path: C:\Temp\example.conf
     regexp: '^name='
     state: absent
 
 - win_lineinfile:
-    path: C:\temp\example.conf
+    path: C:\Temp\example.conf
     regexp: '^127\.0\.0\.1'
     line: '127.0.0.1 localhost'
 
 - win_lineinfile:
-    path: C:\temp\httpd.conf
+    path: C:\Temp\httpd.conf
     regexp: '^Listen '
     insertafter: '^#Listen '
     line: Listen 8080
 
 - win_lineinfile:
-    path: C:\temp\services
+    path: C:\Temp\services
     regexp: '^# port for http'
     insertbefore: '^www.*80/tcp'
     line: '# port for http by default'
 
 # Create file if it doesn't exist with a specific encoding
 - win_lineinfile:
-    path: C:\temp\utf16.txt
+    path: C:\Temp\utf16.txt
     create: yes
     encoding: utf-16
     line: This is a utf-16 encoded file
 
 # Add a line to a file and ensure the resulting file uses unix line separators
 - win_lineinfile:
-    path: C:\temp\testfile.txt
+    path: C:\Temp\testfile.txt
     line: Line added to file
     newline: unix
 
 # Update a line using backrefs
 - win_lineinfile:
-    path: C:\temp\example.conf
+    path: C:\Temp\example.conf
     backrefs: yes
     regexp: '(^name=)'
     line: '$1JohnDoe'

lib/ansible/modules/windows/win_mapped_drive.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
-# This file is part of Ansible
+# -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub, actual code lives in the .ps1
@@ -16,7 +16,7 @@ DOCUMENTATION = r'''
 ---
 module: win_mapped_drive
 version_added: '2.4'
-short_description: maps a network drive for a user
+short_description: Map network drives for users
 description:
 - Allows you to modify mapped network drives for individual users.
 notes:
@@ -45,8 +45,8 @@ options:
       path does not match the target of the mapped drive.
   state:
     description:
-    - If C(state=present) will ensure the mapped drive exists.
+    - If C(present) will ensure the mapped drive exists.
-    - If C(state=absent) will ensure the mapped drive does not exist.
+    - If C(absent) will ensure the mapped drive does not exist.
     choices: [ absent, present ]
     default: present
   username:
@@ -59,30 +59,30 @@ author:
 '''
 
 EXAMPLES = r'''
-- name: create a mapped drive under Z
+- name: Create a mapped drive under Z
   win_mapped_drive:
     letter: Z
     path: \\domain\appdata\accounting
 
-- name: delete any mapped drives under Z
+- name: Delete any mapped drives under Z
   win_mapped_drive:
     letter: Z
     state: absent
 
-- name: only delete the mapped drive Z if the paths match (error is thrown otherwise)
+- name: Only delete the mapped drive Z if the paths match (error is thrown otherwise)
   win_mapped_drive:
     letter: Z
     path: \\domain\appdata\accounting
     state: absent
 
-- name: create mapped drive with local credentials
+- name: Create mapped drive with local credentials
   win_mapped_drive:
     letter: M
     path: \\SERVER\c$
     username: SERVER\Administrator
     password: Password
 
-- name: create mapped drive with domain credentials
+- name: Create mapped drive with domain credentials
   win_mapped_drive:
     letter: M
     path: \\domain\appdata\it

lib/ansible/modules/windows/win_msg.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright: (c) 2017, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -29,7 +15,7 @@ DOCUMENTATION = r'''
 ---
 module: win_msg
 version_added: "2.3"
-short_description: Sends a message to logged in users on Windows hosts.
+short_description: Sends a message to logged in users on Windows hosts
 description:
     - Wraps the msg.exe command in order to send messages to Windows hosts.
 options:
@@ -44,7 +30,7 @@ options:
   wait:
     description:
       - Whether to wait for users to respond.  Module will only wait for the number of seconds specified in display_seconds or 10 seconds if not specified.
-        However, if I(wait) is true, the message is sent to each logged on user in turn, waiting for the user to either press 'ok' or for
+        However, if I(wait) is C(yes), the message is sent to each logged on user in turn, waiting for the user to either press 'ok' or for
         the timeout to elapse before moving on to the next user.
     type: bool
     default: 'no'
@@ -60,7 +46,7 @@ notes:
      hosts, or delegates to a windows host.
    - Messages are only sent to the local host where the module is run.
    - The module does not support sending to users listed in a file.
-   - Setting wait to true can result in long run times on systems with many logged in users.
+   - Setting wait to C(yes) can result in long run times on systems with many logged in users.
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_nssm.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Heyo
+# Copyright: (c) 2015, Heyo
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_nssm
@@ -38,70 +23,61 @@ requirements:
 options:
   name:
     description:
-      - Name of the service to operate on
+      - Name of the service to operate on.
     required: true
   state:
     description:
-      - State of the service on the system
+      - State of the service on the system.
       - Note that NSSM actions like "pause", "continue", "rotate" do not fit the declarative style of ansible, so these should be implemented via the
-        ansible command module
+        ansible command module.
-    choices:
+    choices: [ absent, present, started, stopped, restarted ]
-      - present
-      - started
-      - stopped
-      - restarted
-      - absent
     default: started
   application:
     description:
       - The application binary to run as a service
       - "Specify this whenever the service may need to be installed (state: present, started, stopped, restarted)"
       - "Note that the application name must look like the following, if the directory includes spaces:"
-      - 'nssm install service "c:\\Program Files\\app.exe\\" "C:\\Path with spaces\\"'
+      - 'nssm install service "C:\\Program Files\\app.exe\\" "C:\\Path with spaces\\"'
       - >
         See commit 0b386fc1984ab74ee59b7bed14b7e8f57212c22b in the nssm.git project for more info:
         U(https://git.nssm.cc/?p=nssm.git;a=commit;h=0b386fc1984ab74ee59b7bed14b7e8f57212c22b)
   stdout_file:
     description:
-      - Path to receive output
+      - Path to receive output.
   stderr_file:
     description:
-      - Path to receive error output
+      - Path to receive error output.
   app_parameters:
     description:
       - Parameters to be passed to the application when it starts.
-      - Use either this or C(app_parameters_free_form), not both
+      - Use either this or C(app_parameters_free_form), not both.
   app_parameters_free_form:
     version_added: "2.3.0"
     description:
       - Single string of parameters to be passed to the service.
-      - Use either this or C(app_parameters), not both
+      - Use either this or C(app_parameters), not both.
   dependencies:
     description:
       - Service dependencies that has to be started to trigger startup, separated by comma.
   user:
     description:
-      - User to be used for service startup
+      - User to be used for service startup.
   password:
     description:
-      - Password to be used for service startup
+      - Password to be used for service startup.
   start_mode:
     description:
       - If C(auto) is selected, the service will start at bootup.
       - C(delayed) causes a delayed but automatic start after boot (added in version 2.5).
       - C(manual) means that the service will start only when another service needs it.
       - C(disabled) means that the service will stay off, regardless if it is needed or not.
+    choices: [ auto, delayed, disabled, manual ]
     default: auto
-    choices:
-      - auto
-      - delayed
-      - manual
-      - disabled
 author:
-  - "Adam Keech (@smadam813)"
+  - Adam Keech (@smadam813)
-  - "George Frank (@georgefrank)"
+  - George Frank (@georgefrank)
-  - "Hans-Joachim Kliemeck (@h0nIg)"
+  - Hans-Joachim Kliemeck (@h0nIg)
-  - "Michael Wild (@themiwi)"
+  - Michael Wild (@themiwi)
 '''
 
 EXAMPLES = r'''
@@ -116,7 +92,7 @@ EXAMPLES = r'''
     name: foo
     application: C:\windows\foo.exe
     app_parameters:
-      bar: true
+      bar: 'true'
 
 # Install and start the foo service with a key-value pair argument, where the argument needs to start with a dash
 # This will yield the following command: C:\windows\\foo.exe -bar "true"
@@ -124,7 +100,7 @@ EXAMPLES = r'''
     name: foo
     application: C:\windows\foo.exe
     app_parameters:
-      "-bar": true
+      "-bar": 'true'
 
 # Install and start the foo service with a single parameter
 # This will yield the following command: C:\windows\\foo.exe bar

lib/ansible/modules/windows/win_owner.py

@@ -1,12 +1,13 @@
 #!/usr/bin/python
-# Copyright 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_owner
@@ -18,17 +19,18 @@ options:
   path:
     description:
       - Path to be used for changing owner
-    required: true
+    required: yes
   user:
     description:
       - Name to be used for changing owner
-    required: true
+    required: yes
   recurse:
     description:
       - Indicates if the owner should be changed recursively
     type: bool
     default: 'no'
-author: Hans-Joachim Kliemeck (@h0nIg)
+author:
+- Hans-Joachim Kliemeck (@h0nIg)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_package.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Trond Hindenes <trond@hindenes.com>, and others
+# Copyright: (c) 2014, Trond Hindenes <trond@hindenes.com>, and others
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name

lib/ansible/modules/windows/win_pagefile.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2017, Liran Nisanov <lirannis@gmail.com>
+# Copyright: (c) 2017, Liran Nisanov <lirannis@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -11,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_pagefile
@@ -58,10 +57,7 @@ options:
   state:
     description:
       - State of the pagefile.
-    choices:
+    choices: [ absent, present, query ]
-      - present
-      - absent
-      - query
     default: query
 notes:
 - There is difference between automatic managed pagefiles that configured once for the entire system and system managed pagefile that configured per pagefile.

lib/ansible/modules/windows/win_path.py

@@ -1,21 +1,8 @@
 #!/usr/bin/python
-#
+# -*- coding: utf-8 -*-
-# Copyright 2016 Red Hat | Ansible
+
-#
+# Copyright: (c) 2016, Red Hat | Ansible
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # This is a windows documentation stub.  Actual code lives in the .ps1
 # file of the same name
@@ -24,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = '''
 ---
 module: win_path
@@ -35,7 +21,7 @@ description:
 options:
   name:
     description:
-      - Target path environment variable name
+      - Target path environment variable name.
     default: PATH
   elements:
     description:
@@ -47,21 +33,18 @@ options:
       - New path elements are appended to the path, and existing path elements may be moved closer to the end to satisfy the requested ordering.
       - Paths are compared in a case-insensitive fashion, and trailing backslashes are ignored for comparison purposes. However, note that trailing
         backslashes in YAML require quotes.
-    required: true
+    required: yes
   state:
     description:
       - Whether the path elements specified in C(elements) should be present or absent.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
   scope:
     description:
       - The level at which the environment variable specified by C(name) should be managed (either for the current user or global machine scope).
-    choices:
+    choices: [ machine, user ]
-      - machine
-      - user
     default: machine
-author: "Matt Davis (@nitzmahone)"
+author:
+- Matt Davis (@nitzmahone)
 notes:
    - This module is for modifying indidvidual elements of path-like
      environment variables. For general-purpose management of other

lib/ansible/modules/windows/win_ping.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
+# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name

lib/ansible/modules/windows/win_power_plan.py

@@ -1,13 +1,13 @@
 #!/usr/bin/python
-# Copyright (c) 2017 Ansible Project
+# -*- coding: utf-8 -*-
-# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# Copyright: (c) 2017, Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = '''
 ---
 module: win_power_plan
@@ -24,13 +24,13 @@ options:
     description:
       - String value that indicates the desired power plan. The power plan must already be
         present on the system. Commonly there will be options for C(balanced) and C(high performance).
-    required: True
+    required: yes
 requirements:
   - Windows Server 2008R2 (6.1)/Windows 7 or higher
 '''
 
 EXAMPLES = '''
-- name: change power plan to high performance
+- name: Change power plan to high performance
   win_power_plan:
     name: high performance
 '''

lib/ansible/modules/windows/win_psexec.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2017, Dag Wieers <dag@wieers.com>
+# Copyright: 2017, Dag Wieers (@dagwieers) <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
@@ -20,7 +20,7 @@ options:
   command:
     description:
     - The command line to run through PsExec (limited to 260 characters).
-    required: true
+    required: yes
   executable:
     description:
     - The location of the PsExec utility (in case it is not located in your PATH).
@@ -151,14 +151,4 @@ stderr:
     returned: always
     type: string
     sample: Error 15 running E:\setup.exe
-msg:
-    description: Possible error message on failure
-    returned: failed
-    type: string
-    sample: The 'password' parameter is a required parameter.
-changed:
-    description: Whether or not any changes were made.
-    returned: always
-    type: bool
-    sample: True
 '''

lib/ansible/modules/windows/win_psmodule.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Daniele Lazzari <lazzari@mailup.com>
+# Copyright: (c) 2017, Daniele Lazzari <lazzari@mailup.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -29,38 +15,36 @@ DOCUMENTATION = r'''
 ---
 module: win_psmodule
 version_added: "2.4"
-short_description: Adds or removes a Powershell Module.
+short_description: Adds or removes a Powershell Module
 description:
     - This module helps to install Powershell modules and register custom modules repository on Windows Server.
 options:
   name:
     description:
       - Name of the powershell module that has to be installed.
-    required: true
+    required: yes
   allow_clobber:
     description:
-      - If yes imports all commands, even if they have the same names as commands that already exists. Available only in Powershell 5.1 or higher.
+      - If C(yes) imports all commands, even if they have the same names as commands that already exists. Available only in Powershell 5.1 or higher.
-    default: no
+    type: bool
-    choices:
+    default: 'no'
-      - no
-      - yes
   repository:
     description:
       - Name of the custom repository to register.
   url:
     description:
-      - Url of the custom repository.
+      - URL of the custom repository.
   state:
     description:
-      - If present a new module is installed. If absent a module is removed.
+      - If C(present) a new module is installed.
+      - If C(absent) a module is removed.
+    choices: [ absent, present ]
     default: present
-    choices:
-      - present
-      - absent
 notes:
    -  Powershell 5.0 or higer is needed.
 
-author: Daniele Lazzari
+author:
+- Daniele Lazzari
 '''
 
 EXAMPLES = '''

lib/ansible/modules/windows/win_rabbitmq_plugin.py

@@ -1,12 +1,13 @@
 #!/usr/bin/python
-# Copyright (c) 2017 Ansible Project
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_rabbitmq_plugin
@@ -20,8 +21,8 @@ options:
   names:
     description:
       - Comma-separated list of plugin names.
-    required: true
+    required: yes
-    aliases: [name]
+    aliases: [ name ]
   new_only:
     description:
       - Only enable missing plugins.
@@ -31,8 +32,8 @@ options:
   state:
     description:
       - Specify if plugins are to be enabled or disabled.
+    choices: [ disabled, enabled ]
     default: enabled
-    choices: [enabled, disabled]
   prefix:
     description:
       - Specify a custom install prefix to a Rabbit.

lib/ansible/modules/windows/win_reg_stat.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, inc
+# Copyright: (c) 2016, Ansible, inc
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,12 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_reg_stat
 version_added: "2.3"
-short_description: returns information about a Windows registry key or property of a key
+short_description: Get information about Windows registry keys
 description:
 - Like M(win_file), M(win_reg_stat) will return whether the key/property exists.
 - It also returns the sub keys and properties of the key specified.
@@ -38,24 +23,24 @@ description:
 options:
   path:
     description: The full registry key path including the hive to search for.
-    required: true
+    required: yes
     aliases: [ key ]
   name:
     description:
     - The registry property name to get information for, the return json will not include the sub_keys and properties entries for the I(key) specified.
-    required: false
     aliases: [ entry, value, property ]
-author: "Jordan Borean (@jborean93)"
+author:
+- Jordan Borean (@jborean93)
 '''
 
 EXAMPLES = r'''
-# Obtain information about a registry key using short form
+- name: Obtain information about a registry key using short form
-- win_reg_stat:
+  win_reg_stat:
     path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
   register: current_version
 
-# Obtain information about a registry key property
+- name: Obtain information about a registry key property
-- win_reg_stat:
+  win_reg_stat:
     path: HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion
     name: CommonFilesDir
   register: common_files_dir

lib/ansible/modules/windows/win_regedit.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Adam Keech <akeech@chathamfinancial.com>, Josh Ludwig <jludwig@chathamfinancial.com>
+# Copyright: (c) 2015, Adam Keech <akeech@chathamfinancial.com>, Josh Ludwig <jludwig@chathamfinancial.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -41,7 +27,7 @@ options:
     - Name of the registry path.
     - 'Should be in one of the following registry hives: HKCC, HKCR, HKCU,
       HKLM, HKU.'
-    required: true
+    required: yes
     aliases: [ key ]
   name:
     description:
@@ -73,12 +59,12 @@ options:
   state:
     description:
     - The state of the registry entry.
-    choices: [ present, absent ]
+    choices: [ absent, present ]
     default: present
   delete_key:
     description:
     - When C(state) is 'absent' then this will delete the entire key.
-    - If this is False then it will only clear out the '(Default)' property for
+    - If C(no) then it will only clear out the '(Default)' property for
       that key.
     type: bool
     default: 'yes'

lib/ansible/modules/windows/win_region.py

@@ -1,29 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, inc
+# Copyright: (c) 2016, Ansible, inc
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 module: win_region
 version_added: "2.3"
@@ -61,9 +45,10 @@ options:
               C(location), C(format) or C(unicode_language) has resulted in a
               change. If this process runs then it will always result in a
               change.
-        default: false
+        type: bool
-        choices: ['true', 'false']
+        default: 'no'
-author: "Jordan Borean (@jborean93)"
+author:
+- Jordan Borean (@jborean93)
 '''
 
 EXAMPLES = r'''
@@ -74,7 +59,7 @@ EXAMPLES = r'''
 # Set the region format to English Australia and copy settings to new profiles
 - win_region:
     format: en-AU
-    copy_settings: True
+    copy_settings: yes
 
 # Set the unicode language to English Great Britain, reboot if required
 - win_region:
@@ -100,11 +85,6 @@ EXAMPLES = r'''
 '''
 
 RETURN = r'''
-changed:
-    description: Whether anything was changed
-    returned: always
-    type: boolean
-    sample: True
 restart_required:
     description: Whether a reboot is required for the change to take effect
     returned: success

lib/ansible/modules/windows/win_regmerge.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright: (c) 2015, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_regmerge
@@ -43,16 +28,14 @@ options:
   path:
     description:
       - The full path including file name to the registry file on the remote machine to be merged
-    required: true
+    required: yes
-    default: no default
   compare_key:
     description:
       - The parent key to use when comparing the contents of the registry to the contents of the file.  Needs to be in HKLM or HKCU part of registry.
         Use a PS-Drive style path for example HKLM:\SOFTWARE not HKEY_LOCAL_MACHINE\SOFTWARE
         If not supplied, or the registry key is not found, no comparison will be made, and the module will report changed.
-    required: false
+author:
-    default: no default
+- Jon Hawkesworth (@jhawkesworth)
-author: "Jon Hawkesworth (@jhawkesworth)"
 notes:
    - Organise your registry files so that they contain a single root registry
      key if you want to use the compare_to functionality.
@@ -65,14 +48,14 @@ notes:
 '''
 
 EXAMPLES = r'''
-  # Merge in a registry file without comparing to current registry
+- name: Merge in a registry file without comparing to current registry
-  # Note that paths using / to separate are preferred as they require less special handling than \
+  win_regmerge:
-  - win_regmerge:
+    path: C:\autodeploy\myCompany-settings.reg
-      path: C:/autodeploy/myCompany-settings.reg
+
-  # Compare and merge registry file
+- name: Compare and merge registry file
-  - win_regmerge:
+  win_regmerge:
-      path: C:/autodeploy/myCompany-settings.reg
+    path: C:\autodeploy\myCompany-settings.reg
-      compare_to: HKLM:\SOFTWARE\myCompany
+    compare_to: HKLM:\SOFTWARE\myCompany
 '''
 
 RETURN = r'''

lib/ansible/modules/windows/win_robocopy.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Corwin Brown <blakfeld@gmail.com>
+# Copyright: (c) 2015, Corwin Brown <blakfeld@gmail.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -38,11 +24,11 @@ options:
   src:
     description:
     - Source file/directory to sync.
-    required: true
+    required: yes
   dest:
     description:
     - Destination file/directory to sync (Will receive contents of src).
-    required: true
+    required: yes
   recurse:
     description:
     - Includes all subdirectories (Toggles the C(/e) flag to RoboCopy).

lib/ansible/modules/windows/win_route.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Daniele Lazzari <lazzari@mailup.com>
+# Copyright: (c) 2017, Daniele Lazzari <lazzari@mailup.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # This is a windows documentation stub.  Actual code lives in the .ps1
 # file of the same name.
@@ -29,14 +15,14 @@ DOCUMENTATION = r'''
 ---
 module: win_route
 version_added: "2.4"
-short_description: Add or remove a static route.
+short_description: Add or remove a static route
 description:
     - Add or remove a static route.
 options:
   destination:
     description:
       - Destination IP address in CIDR format (ip address/prefix length)
-    required: true
+    required: yes
   gateway:
     description:
         - The gateway used by the static route.
@@ -47,17 +33,18 @@ options:
     default: 1
   state:
     description:
-      - If present, it adds a network static route.
+      - If C(absent), it removes a network static route.
-        If absent, it removes a network static route.
+      - If C(present), it adds a network static route.
+    choices: [ absent, present ]
     default: present
 notes:
   - Works only with Windows 2012 R2 and newer.
-author: Daniele Lazzari
+author:
+- Daniele Lazzari
 '''
 
 EXAMPLES = r'''
 ---
-
 - name: Add a network static route
   win_route:
     destination: 192.168.2.10/32

lib/ansible/modules/windows/win_say.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright: (c) 2016, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name

lib/ansible/modules/windows/win_scheduled_task.py

@@ -1,15 +1,13 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-# This file is part of Ansible
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_scheduled_task
@@ -26,8 +24,9 @@ notes:
 options:
   # module definition options
   name:
-    description: The name of the scheduled task without the path.
+    description:
-    required: true
+    - The name of the scheduled task without the path.
+    required: yes
   path:
     description:
     - Task folder in which this task will be stored.
@@ -58,7 +57,7 @@ options:
       path:
         description:
         - The path to the executable for the ExecAction.
-        required: true
+        required: yes
       arguments:
         description:
         - An argument string to supply for the executable.
@@ -96,7 +95,7 @@ options:
         description:
         - The trigger type, this value controls what below options are
           required.
-        required: true
+        required: yes
         choices: [ boot, daily, event, idle, logon, monthlydow, monthly, registration, time, weekly, session_state_change ]
       enabled:
         description:

lib/ansible/modules/windows/win_scheduled_task_stat.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -11,12 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_scheduled_task_stat
 version_added: "2.5"
-short_description: Returns information about a Windows Scheduled Task
+short_description: Get information about Windows Scheduled Tasks
 description:
 - Will return whether the folder and task exists.
 - Returns the names of tasks in the folder specified.

lib/ansible/modules/windows/win_security_policy.py

@@ -1,18 +1,7 @@
 #!/usr/bin/python
-# This file is part of Ansible
+# -*- coding: utf-8 -*-
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub, actual code lives in the .ps1
 # file of the same name
@@ -21,12 +10,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_security_policy
 version_added: '2.4'
-short_description: changes local security policy settings
+short_description: Change local security policy settings
 description:
 - Allows you to set the local security policies that are configured by
   SecEdit.exe.

lib/ansible/modules/windows/win_service.py

@@ -32,16 +32,13 @@ options:
     - Remove the dependencies to the existing dependencies.
     - Set the dependencies to only the values in the list replacing the
       existing dependencies.
+    choices: [ add, remove, set ]
     default: set
-    choices:
-    - set
-    - add
-    - remove
     version_added: "2.3"
   desktop_interact:
     description:
       - Whether to allow the service user to interact with the desktop.
-      - This should only be set to true when using the LocalSystem username.
+      - This should only be set to C(yes) when using the LocalSystem username.
     type: bool
     default: 'no'
     version_added: "2.3"
@@ -67,7 +64,7 @@ options:
       - Name of the service.
       - If only the name parameter is specified, the module will report
         on whether the service exists or not without making any changes.
-    required: true
+    required: yes
   path:
     description:
       - The path to the executable to set for the service.
@@ -83,11 +80,7 @@ options:
     description:
       - Set the startup type for the service.
       - C(delayed) added in Ansible 2.3
-    choices:
+    choices: [ auto, delayed, disabled, manual ]
-      - auto
-      - manual
-      - disabled
-      - delayed
   state:
     description:
       - C(started)/C(stopped)/C(absent)/C(pause) are idempotent actions that will not run
@@ -98,12 +91,7 @@ options:
       - Only services that support the paused state can be paused, you can
         check the return value C(can_pause_and_continue).
       - You can only pause a service that is already started.
-    choices:
+    choices: [ absent, paused, started, stopped, restarted ]
-      - started
-      - stopped
-      - restarted
-      - absent
-      - paused
   username:
     description:
       - The username to set the service to start as.
@@ -185,7 +173,7 @@ EXAMPLES = r'''
     state: restarted
     username: LocalSystem
     password: ""
-    desktop_interact: True
+    desktop_interact: yes
 
 - name: Set the log on user to Network Service
   win_service:

lib/ansible/modules/windows/win_share.py

@@ -1,12 +1,13 @@
 #!/usr/bin/python
-# Copyright 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2015, Hans-Joachim Kliemeck <git@kliemeck.de>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_share
@@ -24,21 +25,19 @@ options:
   name:
     description:
       - Share name.
-    required: True
+    required: yes
   path:
     description:
       - Share directory.
-    required: True
+    required: yes
   state:
     description:
       - Specify whether to add C(present) or remove C(absent) the specified share.
-    choices:
+    choices: [ absent, present ]
-      - present
-      - absent
     default: present
   description:
     description:
-      - Share description
+      - Share description.
   list:
     description:
       - Specify whether to allow or deny file listing, in case user got no permission on share.
@@ -66,7 +65,7 @@ options:
       - None
       - Programs
       - Unknown
-    default: "Manual"
+    default: Manual
     version_added: "2.3"
   encrypt:
     description: Sets whether to encrypt the traffic to the share or not.

lib/ansible/modules/windows/win_shell.py

@@ -1,33 +1,17 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, inc
+# Copyright: (c) 2016, Ansible, inc
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-#
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_shell
-short_description: Execute shell commands on target hosts.
+short_description: Execute shell commands on target hosts
 version_added: 2.2
 description:
      - The C(win_shell) module takes the command name followed by a list of space-delimited arguments.
@@ -37,22 +21,22 @@ description:
 options:
   free_form:
     description:
-      - The C(win_shell) module takes a free form command to run.  There is no parameter actually named 'free form'.
+      - The C(win_shell) module takes a free form command to run.
-        See the examples!
+      - There is no parameter actually named 'free form'. See the examples!
-    required: true
+    required: yes
   creates:
     description:
-      - a path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
+      - A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
   removes:
     description:
-      - a path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped.
+      - A path or path filter pattern; when the referenced path B(does not) exist on the target host, the task will be skipped.
   chdir:
     description:
-      - set the specified path as the current working directory before executing a command
+      - Set the specified path as the current working directory before executing a command
   executable:
     description:
-      - change the shell used to execute the command (eg, C(cmd)). The target shell must accept a C(/c) parameter followed by the raw command line to be
+      - Change the shell used to execute the command (eg, C(cmd)).
-        executed.
+      - The target shell must accept a C(/c) parameter followed by the raw command line to be executed.
   stdin:
     description:
     - Set the stdin of the command directly to the specified value.
@@ -74,18 +58,18 @@ author:
 EXAMPLES = r'''
 # Execute a command in the remote shell; stdout goes to the specified
 # file on the remote.
-- win_shell: C:\somescript.ps1 >> c:\somelog.txt
+- win_shell: C:\somescript.ps1 >> C:\somelog.txt
 
 # Change the working directory to somedir/ before executing the command.
-- win_shell: C:\somescript.ps1 >> c:\somelog.txt chdir=c:\somedir
+- win_shell: C:\somescript.ps1 >> C:\somelog.txt chdir=C:\somedir
 
 # You can also use the 'args' form to provide the options. This command
 # will change the working directory to somedir/ and will only run when
 # somedir/somelog.txt doesn't exist.
-- win_shell: C:\somescript.ps1 >> c:\somelog.txt
+- win_shell: C:\somescript.ps1 >> C:\somelog.txt
   args:
-    chdir: c:\somedir
+    chdir: C:\somedir
-    creates: c:\somelog.txt
+    creates: C:\somelog.txt
 
 # Run a command under a non-Powershell interpreter (cmd in this case)
 - win_shell: echo %HOMEDIR%

lib/ansible/modules/windows/win_shortcut.py

@@ -53,8 +53,8 @@ options:
     choices: [ maximized, minimized, normal ]
   state:
     description:
-    - When C(present), creates or updates the shortcut.
     - When C(absent), removes the shortcut if it exists.
+    - When C(present), creates or updates the shortcut.
     choices: [ absent, present ]
     default: present
 author:

lib/ansible/modules/windows/win_stat.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -11,12 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_stat
 version_added: "1.7"
-short_description: returns information about a Windows file
+short_description: Get information about Windows files
 description:
      - Returns information about a Windows file.
      - For non-Windows targets, use the M(stat) module instead.
@@ -49,7 +48,7 @@ options:
             - Algorithm to determine checksum of file. Will throw an error if
               the host is unable to use specified algorithm.
         default: sha1
-        choices: ['md5', 'sha1', 'sha256', 'sha384', 'sha512']
+        choices: [ md5, sha1, sha256, sha384, sha512 ]
         version_added: "2.3"
 notes:
      - For non-Windows targets, use the M(stat) module instead.

lib/ansible/modules/windows/win_tempfile.py

@@ -1,34 +1,20 @@
 #!/usr/bin/python
 # coding: utf-8 -*-
 
-# (c) 2017 Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017 Dag Wieers <dag@wieers.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_tempfile
 version_added: "2.3"
-author: Dag Wieers (@dagwieers)
+author:
-short_description: Creates temporary files and directories.
+- 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.
@@ -36,7 +22,7 @@ options:
   state:
     description:
       - Whether to create file or directory.
-    choices: [ file, directory ]
+    choices: [ directory, file ]
     default: file
   path:
     description:

lib/ansible/modules/windows/win_template.py

@@ -1,30 +1,19 @@
-# this is a virtual module that is entirely implemented server side
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-#
+
-# Ansible is free software: you can redistribute it and/or modify
+# this is a virtual module that is entirely implemented server side
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_template
 version_added: "1.9.2"
-short_description: Templates a file out to a remote server.
+short_description: Templates a file out to a remote server
 description:
      - Templates are processed by the Jinja2 templating language
        (U(http://jinja.pocoo.org/docs/)) - documentation on the template
@@ -43,11 +32,11 @@ options:
   src:
     description:
       - Path of a Jinja2 formatted template on the local server. This can be a relative or absolute path.
-    required: true
+    required: yes
   dest:
     description:
       - Location to render the template to on the remote machine.
-    required: true
+    required: yes
   newline_sequence:
     description:
       - Specify the newline sequence to use for templating files.
@@ -76,16 +65,18 @@ options:
     version_added: '2.4'
   trim_blocks:
     description:
-      - If this is set to True the first newline after a block is removed (block, not variable tag!).
+      - If this is set to C(yes) the first newline after a block is removed (block, not variable tag!).
-    default: "no"
+    type: bool
+    default: 'no'
     version_added: '2.4'
   force:
     description:
-      - the default is C(yes), which will replace the remote file when contents
+      - If C(yes), will replace the remote file when contents are different
-        are different than the source.  If C(no), the file will only be transferred
+        from the source.
-        if the destination does not exist.
+      - If C(no), the file will only be transferred if the destination does
-    choices: [ "yes", "no" ]
+        not exist.
-    default: "yes"
+    type: bool
+    default: 'yes'
     version_added: '2.4'
 notes:
   - For other platforms you can use M(template) which uses '\n' as C(newline_sequence).
@@ -95,18 +86,19 @@ notes:
     add a Byte Order Mark as the first character of the file, which can cause tracebacks.
   - To find Byte Order Marks in files, use C(Format-Hex <file> -Count 16) on Windows, and use C(od -a -t x1 -N 16 <file>) on Linux.
   - "Also, you can override jinja2 settings by adding a special header to template file.
-    i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False)
+    i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: no)
     which changes the variable interpolation markers to  [% var %] instead of  {{ var }}.
     This is the best way to prevent evaluation of things that look like, but should not be Jinja2.
     raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively evaluated."
-author: "Jon Hawkesworth (@jhawkesworth)"
+author:
+- Jon Hawkesworth (@jhawkesworth)
 '''
 
 EXAMPLES = r'''
 - name: Create a file from a Jinja2 template
   win_template:
     src: /mytemplates/file.conf.j2
-    dest: C:\temp\file.conf
+    dest: C:\Temp\file.conf
 
 - name: Create a Unix-style file from a Jinja2 template
   win_template:

lib/ansible/modules/windows/win_timezone.py

@@ -1,25 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Phil Schwartz <schwartzmx@gmail.com>
+# Copyright: (c) 2015, Phil Schwartz <schwartzmx@gmail.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
-
-# this is a windows documentation stub.  actual code lives in the .ps1
-# file of the same name
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
@@ -35,8 +18,9 @@ description:
 options:
   timezone:
     description:
-    - Timezone to set to. Example Central Standard Time
+    - Timezone to set to.
-    required: true
+    - 'Example: Central Standard Time'
+    required: yes
 notes:
 - The module will check if the provided timezone is supported on the machine.
 - A list of possible timezones is available from C(tzutil.exe /l) and from
@@ -44,7 +28,8 @@ notes:
 - If running on Server 2008 the hotfix
   U(https://support.microsoft.com/en-us/help/2556308/tzutil-command-line-tool-is-added-to-windows-vista-and-to-windows-server-2008)
   needs to be installed to be able to run this module.
-author: Phil Schwartz
+author:
+- Phil Schwartz (@schwartzmx)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_toast.py

@@ -1,8 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
+# Copyright: (c) 2017, Jon Hawkesworth (@jhawkesworth) <figs@unity.demon.co.uk>
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -30,11 +30,12 @@ options:
     default: Powershell
   msg:
     description:
-      - The message to appear inside the notification.  May include \n to format the message to appear within the Action Center.
+      - The message to appear inside the notification.
-    default: 'Hello, World!'
+      - May include \n to format the message to appear within the Action Center.
+    default: Hello, World!
   popup:
     description:
-      - If false, the notification will not pop up and will only appear in the Action Center.
+      - If C(no), the notification will not pop up and will only appear in the Action Center.
     type: bool
     default: yes
   tag:

lib/ansible/modules/windows/win_unzip.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Phil Schwartz <schwartzmx@gmail.com>
+# Copyright: (c) 2015, Phil Schwartz <schwartzmx@gmail.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -32,8 +18,8 @@ version_added: "2.0"
 short_description: Unzips compressed files and archives on the Windows node
 description:
 - Unzips compressed files and archives.
-- Supports .zip files natively
+- Supports .zip files natively.
-- Supports other formats supported by the Powershell Community Extensions (PSCX) module (basically everything 7zip supports)
+- 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
@@ -41,11 +27,11 @@ options:
   src:
     description:
       - File to be unzipped (provide absolute path).
-    required: true
+    required: yes
   dest:
     description:
       - Destination of zip file (provide absolute path of directory). If it does not exist, the directory will be created.
-    required: true
+    required: yes
   delete_archive:
     description:
       - Remove the zip file, after unzipping.
@@ -89,7 +75,7 @@ EXAMPLES = r'''
 # Unzip .zip file, recursively decompresses the contained .gz files and removes all unneeded compressed files after completion.
 - name: Unzip ApplicationLogs.zip and decompress all GZipped log files
   hosts: all
-  gather_facts: false
+  gather_facts: no
   tasks:
     - name: Recursively decompress GZ files in ApplicationLogs.zip
       win_unzip:

lib/ansible/modules/windows/win_updates.py

@@ -1,8 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2015, Matt Davis <mdavis_ansible@rolpdog.com>
+# Copyright: (c) 2015, Matt Davis <mdavis_ansible@rolpdog.com>
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -19,7 +19,7 @@ module: win_updates
 version_added: "2.0"
 short_description: Download and install Windows updates
 description:
-    - Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client
+    - Searches, downloads, and installs Windows updates synchronously by automating the Windows Update client.
 options:
     blacklist:
         description:
@@ -29,13 +29,11 @@ options:
           skipped and not installed.
         - Each entry can either be the KB article or Update title as a regex
           according to the PowerShell regex rules.
-        required: false
         version_added: '2.5'
     category_names:
         description:
         - A scalar or list of categories to install updates from
-        required: false
+        default: [ CriticalUpdates, SecurityUpdates, UpdateRollups ]
-        default: ["CriticalUpdates","SecurityUpdates","UpdateRollups"]
         choices:
         - Application
         - Connectors
@@ -70,15 +68,11 @@ options:
         description:
         - Controls whether found updates are returned as a list or actually installed.
         - This module also supports Ansible check mode, which has the same effect as setting state=searched
-        required: false
+        choices: [ installed, searched ]
         default: installed
-        choices:
-        - installed
-        - searched
     log_path:
         description:
         - If set, C(win_updates) will append update progress to the specified file. The directory must already exist.
-        required: false
     whitelist:
         description:
         - A list of update titles or KB numbers that can be used to specify
@@ -90,9 +84,9 @@ options:
         - The whitelist is only validated on updates that were found based on
           I(category_names). It will not force the module to install an update
           if it was not in the category specified.
-        required: false
         version_added: '2.5'
-author: "Matt Davis (@nitzmahone)"
+author:
+- Matt Davis (@nitzmahone)
 notes:
 - C(win_updates) must be run by a user with membership in the local Administrators group.
 - C(win_updates) will use the default update service configured for the machine (Windows Update, Microsoft Update, WSUS, etc).
@@ -117,11 +111,11 @@ EXAMPLES = r'''
   win_updates:
     category_names: SecurityUpdates
 
-- name: Search-only, return list of found updates (if any), log to c:\ansible_wu.txt
+- name: Search-only, return list of found updates (if any), log to C:\ansible_wu.txt
   win_updates:
     category_names: SecurityUpdates
     state: searched
-    log_path: c:\ansible_wu.txt
+    log_path: C:\ansible_wu.txt
 
 - name: Install all security updates with automatic reboots
   win_updates:

lib/ansible/modules/windows/win_user.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2014, Matt Martz <matt@sivel.net>, and others
+# Copyright: (c) 2014, Matt Martz <matt@sivel.net>, and others
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,83 +11,65 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_user
 version_added: "1.7"
 short_description: Manages local Windows user accounts
 description:
-     - Manages local Windows user accounts
+     - Manages local Windows user accounts.
      - For non-Windows targets, use the M(user) module instead.
 options:
   name:
     description:
       - Name of the user to create, remove or modify.
-    required: true
+    required: yes
   fullname:
     description:
-      - Full name of the user
+      - Full name of the user.
-    required: false
-    default: null
     version_added: "1.9"
   description:
     description:
-      - Description of the user
+      - Description of the user.
-    required: false
-    default: null
     version_added: "1.9"
   password:
     description:
       - Optionally set the user's password to this (plain text) value.
-    required: false
-    default: null
   update_password:
     description:
       - C(always) will update passwords if they differ.  C(on_create) will
         only set the password for newly created users.
-    required: false
+    choices: [ always, on_create ]
-    choices: [ 'always', 'on_create' ]
     default: always
     version_added: "1.9"
   password_expired:
     description:
       - C(yes) will require the user to change their password at next login.
-        C(no) will clear the expired password flag.
+      - C(no) will clear the expired password flag.
-    required: false
+    type: bool
-    choices: [ 'yes', 'no' ]
-    default: null
     version_added: "1.9"
   password_never_expires:
     description:
-      - C(yes) will set the password to never expire.  C(no) will allow the
+      - C(yes) will set the password to never expire.
-        password to expire.
+      - C(no) will allow the password to expire.
-    required: false
+    type: bool
-    choices: [ 'yes', 'no' ]
-    default: null
     version_added: "1.9"
   user_cannot_change_password:
     description:
-      - C(yes) will prevent the user from changing their password.  C(no) will
+      - C(yes) will prevent the user from changing their password.
-        allow the user to change their password.
+      - C(no) will allow the user to change their password.
-    required: false
+    type: bool
-    choices: [ 'yes', 'no' ]
-    default: null
     version_added: "1.9"
   account_disabled:
     description:
-      - C(yes) will disable the user account.  C(no) will clear the disabled
+      - C(yes) will disable the user account.
-        flag.
+      - C(no) will clear the disabled flag.
-    required: false
+    type: bool
-    choices: [ 'yes', 'no' ]
-    default: null
     version_added: "1.9"
   account_locked:
     description:
       - C(no) will unlock the user account if locked.
-    required: false
     choices: [ 'no' ]
-    default: null
     version_added: "1.9"
   groups:
     description:
@@ -109,35 +77,30 @@ options:
         depending on the value of I(groups_action). When I(groups_action) is
         C(replace) and I(groups) is set to the empty string ('groups='), the
         user is removed from all groups.
-    required: false
     version_added: "1.9"
   groups_action:
     description:
+      - If C(add), the user is added to each group in I(groups) where not
+        already a member.
       - If C(replace), the user is added as a member of each group in
-        I(groups) and removed from any other groups.  If C(add), the user is
+        I(groups) and removed from any other groups.
-        added to each group in I(groups) where not already a member.  If
+      - If C(remove), the user is removed from each group in I(groups).
-        C(remove), the user is removed from each group in I(groups).
+    choices: [ add, replace, remove ]
-    required: false
+    default: replace
-    choices: [ "replace", "add", "remove" ]
-    default: "replace"
     version_added: "1.9"
   state:
     description:
-      - When C(present), creates or updates the user account.  When C(absent),
+      - When C(absent), removes the user account if it exists.
-        removes the user account if it exists.  When C(query) (new in 1.9),
+      - When C(present), creates or updates the user account.
-        retrieves the user account details without making any changes.
+      - When C(query) (new in 1.9), retrieves the user account details
-    required: false
+        without making any changes.
-    choices:
+    choices: [ absent, present, query ]
-      - present
-      - absent
-      - query
     default: present
-    aliases: []
 notes:
      - For non-Windows targets, use the M(user) module instead.
 author:
-    - "Paul Durivage (@angstwad)"
+    - Paul Durivage (@angstwad)
-    - "Chris Church (@cchurch)"
+    - Chris Church (@cchurch)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_user_right.py

@@ -1,9 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# This file is part of Ansible
+# Copyright: (c) 2017, Ansible Project
-
-# Copyright (c) 2017 Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -13,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_user_right
@@ -31,7 +28,7 @@ options:
     - The name of the User Right as shown by the C(Constant Name) value from
       U(https://technet.microsoft.com/en-us/library/dd349804.aspx).
     - The module will return an error if the right is invalid.
-    required: True
+    required: yes
   users:
     description:
     - A list of users or groups to add/remove on the User Right.
@@ -40,14 +37,14 @@ options:
     - For local users/groups it can be in the form user-group, .\user-group,
       SERVERNAME\user-group where SERVERNAME is the name of the remote server.
     - You can also add special local accounts like SYSTEM and others.
-    required: True
+    required: yes
   action:
     description:
     - C(add) will add the users/groups to the existing right.
     - C(remove) will remove the users/groups from the existing right.
     - C(set) will replace the users/groups of the existing right.
     default: set
-    choices: [set, add, remove]
+    choices: [ add, remove, set ]
 author:
 - Jordan Borean (@jborean93)
 '''

lib/ansible/modules/windows/win_wait_for.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
-# This file is part of Ansible
+# -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub, actual code lives in the .ps1
@@ -11,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_wait_for
@@ -76,7 +75,7 @@ options:
       ensure that the file or string is present, C(absent) will check that the
       file or search string is absent or removed.
     default: started
-    choices: [ present, started, stopped, absent, drained ]
+    choices: [ absent, drained, present, started, stopped ]
   timeout:
     description:
     - The maximum number of seconds to wait for.

lib/ansible/modules/windows/win_wakeonlan.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2017, Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2017, Dag Wieers <dag@wieers.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
@@ -33,7 +19,7 @@ options:
   mac:
     description:
     - MAC address to send Wake-on-LAN broadcast packet for.
-    required: true
+    required: yes
   broadcast:
     description:
     - Network broadcast address to use for broadcasting magic Wake-on-LAN packet.
@@ -45,11 +31,11 @@ options:
 author:
 - Dag Wieers (@dagwieers)
 todo:
-  - Does not have SecureOn password support
+- Does not have SecureOn password support
 notes:
-  - This module sends a magic packet, without knowing whether it worked. It always report a change.
+- This module sends a magic packet, without knowing whether it worked. It always report a change.
-  - Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS).
+- Only works if the target system was properly configured for Wake-on-LAN (in the BIOS and/or the OS).
-  - Some BIOSes have a different (configurable) Wake-on-LAN boot order (i.e. PXE first).
+- Some BIOSes have a different (configurable) Wake-on-LAN boot order (i.e. PXE first).
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_webpicmd.py

@@ -1,22 +1,8 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2015, Peter Mounce <public@neverrunwithscissors.com>
+# Copyright: (c) 2015, Peter Mounce <public@neverrunwithscissors.com>
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
 # this is a windows documentation stub.  actual code lives in the .ps1
 # file of the same name
@@ -25,7 +11,6 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_webpicmd
@@ -34,16 +19,17 @@ short_description: Installs packages using Web Platform Installer command-line
 description:
     - Installs packages using Web Platform Installer command-line
       (U(http://www.iis.net/learn/install/web-platform-installer/web-platform-installer-v4-command-line-webpicmdexe-rtw-release)).
-    - Must be installed and present in PATH (see M(win_chocolatey) module; 'webpicmd' is the package name, and you must install 'lessmsi' first too)
+    - Must be installed and present in PATH (see M(win_chocolatey) module; 'webpicmd' is the package name, and you must install 'lessmsi' first too)?
-    - Install IIS first (see M(win_feature) module)
+    - Install IIS first (see M(win_feature) module).
 notes:
-    - accepts EULAs and suppresses reboot - you will need to check manage reboots yourself (see M(win_reboot) module)
+    - Accepts EULAs and suppresses reboot - you will need to check manage reboots yourself (see M(win_reboot) module)
 options:
   name:
     description:
-      - Name of the package to be installed
+      - Name of the package to be installed.
-    required: true
+    required: yes
-author: Peter Mounce
+author:
+- Peter Mounce (@petemounce)
 '''
 
 EXAMPLES = r'''

lib/ansible/modules/windows/win_whoami.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright (c) 2017 Ansible Project
+# Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 # this is a windows documentation stub.  actual code lives in the .ps1
@@ -11,12 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_whoami
 version_added: "2.5"
-short_description: Returns information about the current user and process
+short_description: Get information about the current user and process
 description:
 - Designed to return the same information as the C(whoami /all) command.
 - Also includes information missing from C(whoami) such as logon metadata like

lib/ansible/plugins/callback/dense.py

@@ -6,16 +6,18 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = '''
-    callback: dense
+callback: dense
-    type: stdout
+type: stdout
-    short_description: minimal stdout output
+short_description: minimal stdout output
-    extends_documentation_fragment:
+extends_documentation_fragment:
-      - default_callback
+- default_callback
-    description:
+description:
-      - When in verbose mode it will act the same as the default callback
+- When in verbose mode it will act the same as the default callback
-    version_added: "2.3"
+author:
-    requirements:
+- Dag Wieers (@dagwieers)
-      - set as stdout in configuation
+version_added: "2.3"
+requirements:
+- set as stdout in configuation
 '''
 
 from collections import MutableMapping, MutableSequence

lib/ansible/plugins/callback/mail.py

@@ -13,6 +13,8 @@ short_description: Sends failure events via email
 description:
 - This callback will report failures via email
 version_added: '2.0'
+author:
+- Dag Wieers (@dagwieers)
 requirements:
 - whitelisting in configuration
 options:

lib/ansible/plugins/lookup/filetree.py

@@ -5,19 +5,19 @@ from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type
 
 DOCUMENTATION = """
-    lookup: filetree
+lookup: filetree
-    author: Dag Wieers (@dagwieers) <dag@wieers.com>
+author: Dag Wieers (@dagwieers) <dag@wieers.com>
-    version_added: "2.4"
+version_added: "2.4"
-    short_description: recursively match all files in a directory tree
+short_description: recursively match all files in a directory tree
-    description:
+description:
-        - This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
+- This lookup enables you to template a complete tree of files on a target system while retaining permissions and ownership.
-        - Supports directories, files and symlinks, including SELinux and other file properties
+- Supports directories, files and symlinks, including SELinux and other file properties
-        - If you provide more than one path, it will implement a with_first_found logic, and will not process entries it already processed in previous paths.
+- If you provide more than one path, it will implement a with_first_found logic, and will not process entries it already processed in previous paths.
-          This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role.
+  This enables merging different trees in order of importance, or add role_vars to specific paths to influence different instances of the same role.
-    options:
+options:
-      _terms:
+  _terms:
-        description: path(s) of files to read
+    description: path(s) of files to read
-        required: True
+    required: True
 """
 
 EXAMPLES = """