Docs: Clean up 'win_service' module docs (#46407)

* Docs: Clean up 'win_service' module docs

This is part of a series of module doc cleanups.

* Fix typo pause vs paused

* Use both YAML list syntaxes

lib/ansible/modules/windows/win_service.py

@@ -11,11 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 DOCUMENTATION = r'''
 ---
 module: win_service
-version_added: "1.7"
+version_added: '1.7'
 short_description: Manage and query Windows services
 description:
-    - Manage and query Windows services.
+- Manage and query Windows services.
-    - For non-Windows targets, use the M(service) module instead.
+- For non-Windows targets, use the M(service) module instead.
 options:
   dependencies:
     description:
@@ -25,7 +25,7 @@ options:
     - This works by C(dependency_action) to either add/remove or set the
       services in this list.
     type: list
-    version_added: "2.3"
+    version_added: '2.3'
   dependency_action:
     description:
     - Used in conjunction with C(dependency) to either add the dependencies to
@@ -33,24 +33,27 @@ options:
     - Remove the dependencies to the existing dependencies.
     - Set the dependencies to only the values in the list replacing the
       existing dependencies.
+    type: str
     choices: [ add, remove, set ]
     default: set
-    version_added: "2.3"
+    version_added: '2.3'
   desktop_interact:
     description:
-      - Whether to allow the service user to interact with the desktop.
+    - Whether to allow the service user to interact with the desktop.
-      - This should only be set to C(yes) when using the LocalSystem username.
+    - This should only be set to C(yes) when using the C(LocalSystem) username.
     type: bool
-    default: 'no'
+    default: no
-    version_added: "2.3"
+    version_added: '2.3'
   description:
     description:
       - The description to set for the service.
-    version_added: "2.3"
+    type: str
+    version_added: '2.3'
   display_name:
     description:
       - The display name to set for the service.
-    version_added: "2.3"
+    type: str
+    version_added: '2.3'
   force_dependent_services:
     description:
     - If C(yes), stopping or restarting a service with dependent services will
@@ -58,50 +61,55 @@ options:
     - If C(no), stopping or restarting a service with dependent services may
       fail.
     type: bool
-    default: 'no'
+    default: no
-    version_added: "2.3"
+    version_added: '2.3'
   name:
     description:
-      - Name of the service.
+    - Name of the service.
-      - If only the name parameter is specified, the module will report
+    - If only the name parameter is specified, the module will report
-        on whether the service exists or not without making any changes.
+      on whether the service exists or not without making any changes.
     required: yes
+    type: str
   path:
     description:
-      - The path to the executable to set for the service.
+    - The path to the executable to set for the service.
-    version_added: "2.3"
+    version_added: '2.3'
   password:
     description:
-      - The password to set the service to start as.
+    - The password to set the service to start as.
-      - This and the C(username) argument must be supplied together.
+    - This and the C(username) argument must be supplied together.
-      - If specifying LocalSystem, NetworkService or LocalService this field
+    - If specifying C(LocalSystem), C(NetworkService) or C(LocalService) this field
-        must be an empty string and not null.
+      must be an empty string and not null.
-    version_added: "2.3"
+    version_added: '2.3'
   start_mode:
     description:
-      - Set the startup type for the service.
+    - Set the startup type for the service.
-      - C(delayed) added in Ansible 2.3
+    - A newly created service will default to C(auto).
+    - C(delayed) added in Ansible 2.3
     choices: [ auto, delayed, disabled, manual ]
   state:
     description:
-      - C(started)/C(stopped)/C(absent)/C(pause) are idempotent actions that will not run
+    - The desired state of the service.
-        commands unless necessary.
+    - C(started)/C(stopped)/C(absent)/C(paused) are idempotent actions that will not run
-      - C(restarted) will always bounce the service.
+      commands unless necessary.
-      - C(absent) added in Ansible 2.3
+    - C(restarted) will always bounce the service.
-      - C(pause) was added in Ansible 2.4
+    - C(absent) was added in Ansible 2.3
-      - Only services that support the paused state can be paused, you can
+    - C(paused) was added in Ansible 2.4
-        check the return value C(can_pause_and_continue).
+    - Only services that support the paused state can be paused, you can
-      - You can only pause a service that is already started.
+      check the return value C(can_pause_and_continue).
+    - You can only pause a service that is already started.
+    - A newly created service will default to C(stopped).
     choices: [ absent, paused, started, stopped, restarted ]
   username:
     description:
-      - The username to set the service to start as.
+    - The username to set the service to start as.
-      - This and the C(password) argument must be supplied together when using
+    - This and the C(password) argument must be supplied together when using
-        a local or domain account.
+      a local or domain account.
-      - Set to C(LocalSystem) to use the SYSTEM account.
+    - Set to C(LocalSystem) to use the SYSTEM account.
-    version_added: "2.3"
+    - A newly created service will default to C(LocalSystem).
+    version_added: '2.3'
 notes:
-    - For non-Windows targets, use the M(service) module instead.
+- For non-Windows targets, use the M(service) module instead.
 author:
 - Chris Hoffman (@chrishoffman)
 '''
@@ -123,7 +131,12 @@ EXAMPLES = r'''
     name: Netlogon
     state: paused
 
-# a new service will also default to the following values:
+- name: Ensure that WinRM is started when the system has settled
+  win_service:
+    name: WinRM
+    start_mode: delayed
+
+# A new service will also default to the following values:
 # - username: LocalSystem
 # - state: stopped
 # - start_mode: auto
@@ -168,7 +181,7 @@ EXAMPLES = r'''
     name: service name
     state: restarted
     username: LocalSystem
-    password: ""
+    password: ''
 
 - name: Set the log on user to Local System and allow it to interact with the desktop
   win_service:
@@ -183,30 +196,32 @@ EXAMPLES = r'''
     name: service name
     state: restarted
     username: NT AUTHORITY\NetworkService
-    password: ""
+    password: ''
 
 - name: Set the log on user to Local Service
   win_service:
     name: service name
     state: restarted
     username: NT AUTHORITY\LocalService
-    password: ""
+    password: ''
 
 - name: Set dependencies to ones only in the list
   win_service:
     name: service name
-    dependencies: ['service1', 'service2']
+    dependencies: [ service1, service2 ]
 
 - name: Add dependencies to existing dependencies
   win_service:
     name: service name
-    dependencies: ['service1', 'service2']
+    dependencies: [ service1, service2 ]
     dependency_action: add
 
 - name: Remove dependencies from existing dependencies
   win_service:
     name: service name
-    dependencies: ['service1', 'service2']
+    dependencies:
+    - service1
+    - service2
     dependency_action: remove
 '''