win_timezone: Add diff support, integration tests (#25284)

* win_timezone: Add diff support, integration tests

This PR includes:

- Diff support
- Returns both previous_timezone and timezone
- Adds integration tests
- More examples
- Improved documentation

* Merged the changes from jborean93's PR

lib/ansible/modules/windows/win_timezone.ps1

@@ -21,55 +21,66 @@
 
 $params = Parse-Args $args -supports_check_mode $true
 $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "bool" -default $false
+$diff_support = Get-AnsibleParam -obj $params -name "_ansible_diff" -type "bool" -default $false
 
 $timezone = Get-AnsibleParam -obj $params -name "timezone" -type "str" -failifempty $true
 
 $result = @{
     changed = $false
+    previous_timezone = $timezone
+    timezone = $timezone
 }
 
 Try {
     # Get the current timezone set
-    $currentTZ = $(tzutil.exe /g)
+    $result.previous_timezone = $(tzutil.exe /g)
     If ($LASTEXITCODE -ne 0) {
         Throw "An error occurred when getting the current machine's timezone setting."
     }
 
-    If ( $currentTZ -eq $timezone ) {
-        Exit-Json $result "$timezone is already set on this machine"
+    if ( $result.previous_timezone -eq $timezone ) {
+        Exit-Json $result "Timezone '$timezone' is already set on this machine"
     } Else {
-        $tzExists = $false
-        #Check that timezone can even be set (if it is listed from tzutil as an available timezone to the machine)
+        # Check that timezone is listed as an available timezone to the machine
         $tzList = $(tzutil.exe /l)
         If ($LASTEXITCODE -ne 0) {
             Throw "An error occurred when listing the available timezones."
         }
+
+        $tzExists = $false
         ForEach ($tz in $tzList) {
             If ( $tz -eq $timezone ) {
                 $tzExists = $true
                 break
             }
         }
+        if (-not $tzExists) {
+            Fail-Json $result "The specified timezone: $timezone isn't supported on the machine."
+        }
 
-        If ( $tzExists ) {
-            if (-not $check_mode) {
-                tzutil.exe /s "$timezone"
-                If ($LASTEXITCODE -ne 0) {
-                    Throw "An error occurred when setting the specified timezone with tzutil."
-                }
-                $newTZ = $(tzutil.exe /g)
-                If ($LASTEXITCODE -ne 0) {
-                    Throw "An error occurred when getting the current machine's timezone setting."
-                }
+        if ($check_mode) {
+            $result.changed = $true
+        } else {
+            tzutil.exe /s "$timezone"
+            if ($LASTEXITCODE -ne 0) {
+                Throw "An error occurred when setting the specified timezone with tzutil."
+            }
 
-                If ( $timezone -eq $newTZ ) {
-                    $result.changed = $true
-                }
-            } else {
+            $new_timezone = $(tzutil.exe /g)
+            if ($LASTEXITCODE -ne 0) {
+                Throw "An error occurred when getting the current machine's timezone setting."
+            }
+
+            if ($timezone -eq $new_timezone) {
                 $result.changed = $true
             }
-        } Else {
-            Fail-Json $result "The specified timezone: $timezone isn't supported on the machine."
+        }
+
+        if ($diff_support) {
+            $result.diff = @{
+                before = "$($result.previous_timezone)`n"
+                after = "$timezone`n"
+            }
         }
     }
 } Catch {

lib/ansible/modules/windows/win_timezone.py

@@ -25,28 +25,51 @@ ANSIBLE_METADATA = {'metadata_version': '1.0',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
 DOCUMENTATION = r'''
 ---
 module: win_timezone
-version_added: "2.1"
+version_added: '2.1'
 short_description: Sets Windows machine timezone
 description:
-    - Sets machine time to the specified timezone, the module will check if the provided timezone is supported on the machine.
+- Sets machine time to the specified timezone.
 options:
   timezone:
     description:
-      - Timezone to set to.  Example Central Standard Time
+    - Timezone to set to. Example Central Standard Time
     required: true
-
+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
+  U(https://msdn.microsoft.com/en-us/library/ms912391.aspx)
+- 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
 '''
 
-
 EXAMPLES = r'''
-  # Set machine's timezone to Central Standard Time
+- name: Set timezone to 'Romance Standard Time' (GMT+01:00)
   win_timezone:
-    timezone: "Central Standard Time"
+    timezone: Romance Standard Time
+
+- name: Set timezone to 'GMT Standard Time' (GMT)
+  win_timezone:
+    timezone: GMT Standard Time
+
+- name: Set timezone to 'Central Standard Time' (GMT-06:00)
+  win_timezone:
+    timezone: Central Standard Time
 '''
 
-RETURN = r'''# '''
+RETURN = r'''
+previous_timezone:
+    description: The previous timezone if it was changed, otherwise the existing timezone
+    returned: success
+    type: string
+    sample: Central Standard Time
+timezone:
+    description: The current timezone (possibly changed)
+    returned: success
+    type: string
+    sample: Central Standard Time
+'''