From 8ff13db17cc121120304072b8b92b8f3f985d017 Mon Sep 17 00:00:00 2001
From: Jorgen <jur.public@xs4all.nl>
Date: Fri, 30 Nov 2018 17:12:19 +0100
Subject: [PATCH] Add Windows example of raw command (#47153)

* Add Windows example of raw command

Perform shutdown of Windows OS using Microsoft.PowerShell.Management module

* Capitalized cmdlet, remove quotes and improve description

This commit also cleans up some of the description sections.

* Use another example as suggested by jborean93

I was happy to merge this before I noticed jborean93 objected to the example :-/

* Fix whitespace issue
---
 lib/ansible/modules/commands/raw.py | 37 ++++++++++++++++-------------
 1 file changed, 21 insertions(+), 16 deletions(-)

diff --git a/lib/ansible/modules/commands/raw.py b/lib/ansible/modules/commands/raw.py
index 74cc676398b..a7cc916a61a 100644
--- a/lib/ansible/modules/commands/raw.py
+++ b/lib/ansible/modules/commands/raw.py
@@ -1,5 +1,6 @@
-# this is a virtual module that is entirely implemented server side
-# Copyright: Ansible Project
+# This is a virtual module that is entirely implemented server side
+
+# Copyright: (c) 2012, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
@@ -11,7 +12,7 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'supported_by': 'core'}
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: raw
 short_description: Executes a low-down and dirty SSH command
@@ -19,25 +20,26 @@ version_added: historical
 options:
   free_form:
     description:
-      - the raw module takes a free form command to run. There is no parameter actually named 'free form'; see the examples!
+      - The raw module takes a free form command to run. There is no parameter actually named 'free form'; see the examples!
     required: true
   executable:
     description:
-      - change the shell used to execute the command. Should be an absolute path to the executable.
-      - when using privilege escalation (C(become)), a default shell will be assigned if one is not provided
+      - Change the shell used to execute the command. Should be an absolute path to the executable.
+      - When using privilege escalation (C(become)) a default shell will be assigned if one is not provided
         as privilege escalation requires a shell.
-    required: false
     version_added: "1.0"
 description:
      - Executes a low-down and dirty SSH command, not going through the module
-       subsystem. This is useful and should only be done in a few cases. A common
+       subsystem.
+     - This is useful and should only be done in a few cases. A common
        case is installing C(python) on a system without python installed by default.
        Another is speaking to any devices such as
        routers that do not have any Python installed. In any other case, using
-       the M(shell) or M(command) module is much more appropriate. Arguments
-       given to C(raw) are run directly through the configured remote shell.
-       Standard output, error output and return code are returned when
-       available. There is no change handler support for this module.
+       the M(shell) or M(command) module is much more appropriate.
+     - Arguments given to C(raw) are run directly through the configured remote shell.
+     - Standard output, error output and return code are returned when
+       available.
+     - There is no change handler support for this module.
      - This module does not require python on the remote system, much like
        the M(script) module.
      - This module is also supported for Windows targets.
@@ -47,7 +49,7 @@ notes:
       onto the machine."
     - If you want to execute a command securely and predictably, it may be
       better to use the M(command) or M(shell) modules instead.
-    - the C(environment) keyword does not work with raw normally, it requires a shell
+    - The C(environment) keyword does not work with raw normally, it requires a shell
       which means it only works if C(executable) is set or using the module
       with privilege escalation (C(become)).
     - This module is also supported for Windows targets.
@@ -56,7 +58,7 @@ author:
     - Michael DeHaan
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 - name: Bootstrap a host without python2 installed
   raw: dnf install -y python2 python2-dnf libselinux-python
 
@@ -65,6 +67,9 @@ EXAMPLES = '''
   args:
     executable: /bin/bash
 
-- name: safely use templated variables. Always use quote filter to avoid injection issues.
-  raw: "{{package_mgr|quote}} {{pkg_flags|quote}} install {{python|quote}}"
+- name: Safely use templated variables. Always use quote filter to avoid injection issues.
+  raw: "{{ package_mgr|quote }} {{ pkg_flags|quote }} install {{ python|quote }}"
+
+- name: List user accounts on a Windows system
+  raw: Get-WmiObject -Class Win32_UserAccount
 '''