Deprecated restart option in win_feature, added return docs

lib/ansible/modules/windows/win_feature.ps1

@@ -30,6 +30,8 @@ $check_mode = Get-AnsibleParam -obj $params -name "_ansible_check_mode" -type "b
 
 $name = Get-AnsibleParam -obj $params -name "name" -type "str" -failifempty $true
 $state = Get-AnsibleParam -obj $params -name "state" -type "str" -default "present" -validateset "present","absent"
+
+# DEPRECATED 2.4, potential removal in 2.6+
 $restart = Get-AnsibleParam -obj $params -name "restart" -type "bool" -default $false
 $includesubfeatures = Get-AnsibleParam -obj $params -name "include_sub_features" -type "bool" -default $false
 $includemanagementtools = Get-AnsibleParam -obj $params -name "include_management_tools" -type "bool" -default $false
@@ -37,6 +39,9 @@ $source = Get-AnsibleParam -obj $params -name "source" -type "str"
 
 $name = $name -split ',' | % { $_.Trim() }
 
+If ($restart) {
+    Add-DeprecationWarning -obj $result -message "The 'restart' parameter causes instability. Use the 'win_reboot' action conditionally on 'reboot_required' return value instead" -version 2.6
+}
 
 # Determine which cmdlets we need to work with. Then we can set options appropriate for the cmdlet
 $installWF= $false
@@ -133,9 +138,12 @@ If ($featureresult.FeatureResult)
             id = $item.Id
             display_name = $item.DisplayName
             message = $message
-            restart_needed = $item.RestartNeeded.ToString() | ConvertTo-Bool
+            reboot_required = $item.RestartNeeded.ToString() | ConvertTo-Bool
             skip_reason = $item.SkipReason.ToString()
             success = $item.Success.ToString() | ConvertTo-Bool
+
+            # DEPRECATED 2.4, potential removal in 2.6+ (standardize naming to "reboot_required")
+            restart_needed = $item.RestartNeeded.ToString() | ConvertTo-Bool
         }
     }
     $result.changed = $true
@@ -144,7 +152,10 @@ If ($featureresult.FeatureResult)
 $result.feature_result = $installed_features
 $result.success = ($featureresult.Success.ToString() | ConvertTo-Bool)
 $result.exitcode = $featureresult.ExitCode.ToString()
-$result.restart_needed = ($featureresult.RestartNeeded.ToString() | ConvertTo-Bool)
+$result.reboot_required = ($featureresult.RestartNeeded.ToString() | ConvertTo-Bool)
+
+# DEPRECATED 2.4, potential removal in 2.6+ (standardize naming to "reboot_required")
+$result.restart_needed = $result.reboot_required
 
 If ($result.success) {
     Exit-Json $result

lib/ansible/modules/windows/win_feature.py

@@ -49,6 +49,8 @@ options:
   restart:
     description:
       - Restarts the computer automatically when installation is complete, if restarting is required by the roles or features installed.
+      - DEPRECATED in Ansible 2.4, as unmanaged reboots cause numerous issues under Ansible. Check the C(reboot_required) return value
+        from this module to determine if a reboot is necessary, and if so, use the M(win_reboot) action to perform it.
     choices:
       - yes
       - no
@@ -101,3 +103,64 @@ EXAMPLES = r'''
     include_sub_features: True
     include_management_tools: True
 '''
+
+RETURN = r'''
+exitcode:
+    description: The stringified exit code from the feature installation/removal command
+    returned: always
+    type: string
+    sample: Success
+feature_result:
+    description: List of features that were installed or removed
+    returned: success
+    type: complex
+    sample:
+    contains:
+        display_name:
+            description: Feature display name
+            returned: always
+            type: string
+            sample: "Telnet Client"
+        id:
+            description: A list of KB article IDs that apply to the update
+            returned: always
+            type: int
+            sample: 44
+        message:
+            description: Any messages returned from the feature subsystem that occurred during installation or removal of this feature
+            returned: always
+            type: list of strings
+            sample: []
+        reboot_required:
+            description: True when the target server requires a reboot as a result of installing or removing this feature
+            returned: always
+            type: boolean
+            sample: True
+        restart_needed:
+            description: DEPRECATED in Ansible 2.4 (refer to C(reboot_required) instead). True when the target server requires a reboot as a
+                         result of installing or removing this feature
+            returned: always
+            type: boolean
+            sample: True
+        skip_reason:
+            description: The reason a feature installation or removal was skipped
+            returned: always
+            type: string
+            sample: NotSkipped
+        success:
+            description: If the feature installation or removal was successful
+            returned: always
+            type: boolean
+            sample: True
+reboot_required:
+    description: True when the target server requires a reboot to complete updates (no further updates can be installed until after a reboot)
+    returned: success
+    type: boolean
+    sample: True
+restart_needed:
+    description: DEPRECATED in Ansible 2.4 (refer to C(reboot_required) instead). True when the target server requires a reboot to complete updates
+                 (no further updates can be installed until after a reboot)
+    returned: success
+    type: boolean
+    sample: True
+'''