server: Express inability to deploy a server in example doc strings

The doc strings for the examples have not been good enough to express
that the module is requiring an existing server and that is not able to
deploy a new server.

README-server.md

@@ -39,7 +39,7 @@ ipaserver.test.local
 ```
 
 
-Example playbook to make sure server "server.example.com" is present:
+Example playbook to make sure server "server.example.com" is already present in the topology:
 
 ```yaml
 ---
@@ -53,8 +53,10 @@ Example playbook to make sure server "server.example.com" is present:
       name: server.example.com
 ```
 
+This task is not deploying a new server, it is only checking if the server eists. It will therefore fail if the server does not exist.
 
-Example playbook to make sure server "server.example.com" is present with location mylocation:
+
+Example playbook to make sure server "server.example.com" has location mylocation:
 
 ```yaml
 ---
@@ -70,7 +72,7 @@ Example playbook to make sure server "server.example.com" is present with locati
 ```
 
 
-Example playbook to make sure server "server.example.com" is present without a location:
+Example playbook to make sure server "server.example.com" does not have a location:
 
 ```yaml
 ---
@@ -86,7 +88,7 @@ Example playbook to make sure server "server.example.com" is present without a l
 ```
 
 
-Example playbook to make sure server "server.example.com" is present with service weight 1:
+Example playbook to make sure server "server.example.com" has service weight 1:
 
 ```yaml
 ---
@@ -102,7 +104,7 @@ Example playbook to make sure server "server.example.com" is present with servic
 ```
 
 
-Example playbook to make sure server "server.example.com" is present without service weight:
+Example playbook to make sure server "server.example.com" does not have a service weight:
 
 ```yaml
 ---
@@ -118,7 +120,7 @@ Example playbook to make sure server "server.example.com" is present without ser
 ```
 
 
-Example playbook to make sure server "server.example.com" is present and hidden:
+Example playbook to make sure server "server.example.com" is hidden:
 
 ```yaml
 ---
@@ -134,7 +136,7 @@ Example playbook to make sure server "server.example.com" is present and hidden:
 ```
 
 
-Example playbook to make sure server "server.example.com" is present and not hidden:
+Example playbook to make sure server "server.example.com" is not hidden:
 
 ```yaml
 ---
@@ -150,7 +152,7 @@ Example playbook to make sure server "server.example.com" is present and not hid
 ```
 
 
-Example playbook to make sure server "server.example.com" is absent:
+Example playbook to make sure server "server.example.com" is absent from the topology:
 
 ```yaml
 ---
@@ -166,7 +168,7 @@ Example playbook to make sure server "server.example.com" is absent:
 ```
 
 
-Example playbook to make sure server "server.example.com" is absent in continuous mode in error case:
+Example playbook to make sure server "server.example.com" is absent from the topology in continuous mode to ignore errors:
 
 ```yaml
 ---
@@ -183,7 +185,7 @@ Example playbook to make sure server "server.example.com" is absent in continuou
 ```
 
 
-Example playbook to make sure server "server.example.com" is absent with last of role check skip:
+Example playbook to make sure server "server.example.com" is absent from the topology with skipping the last of role check:
 
 ```yaml
 ---
@@ -200,7 +202,7 @@ Example playbook to make sure server "server.example.com" is absent with last of
 ```
 
 
-Example playbook to make sure server "server.example.com" is absent iwith topology disconnect check skip:
+Example playbook to make sure server "server.example.com" is absent from the topology with skipping the topology disconnect check:
 
 ```yaml
 ---
@@ -217,7 +219,24 @@ Example playbook to make sure server "server.example.com" is absent iwith topolo
 ```
 
 
-MORE EXAMPLE PLAYBOOKS HERE
+Example playbook to make sure server "server.example.com" is absent from the domain in force mode even if it does not exist:
+
+```yaml
+---
+- name: Playbook to manage IPA server.
+  hosts: ipaserver
+  become: yes
+
+  tasks:
+  - ipaserver:
+      ipaadmin_password: SomeADMINpassword
+      name: server.example.com
+      force: yes
+      state: absent
+```
+
+This task will always report a change.
+
 
 
 Variables

plugins/modules/ipaserver.py

@@ -99,69 +99,71 @@ options:
 """
 
 EXAMPLES = """
-# Ensure server server.example.com is present
+# Ensure server server.example.com is already present in the topology
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
 
-# Ensure server server.example.com is absent
+# Ensure server server.example.com is absent from the topology
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     state: absent
 
-# Ensure server server.example.com is present with location mylocation
+# Ensure server server.example.com has location mylocation
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     location: mylocation
 
-# Ensure server server.example.com is present without a location
+# Ensure server server.example.com does not have a location
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     location: ""
 
-# Ensure server server.example.com is present with service weight 1
+# Ensure server server.example.com has service weight 1
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     service_weight: 1
 
-# Ensure server server.example.com is present without service weight
+# Ensure server server.example.com does not have a service weight
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     service_weight: -1
 
-# Ensure server server.example.com is present and hidden
+# Ensure server server.example.com is hidden
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     hidden: yes
 
-# Ensure server server.example.com is present and not hidden
+# Ensure server server.example.com is not hidden
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     hidden: no
 
-# Ensure server server.example.com is absent in continuous mode in error case
+# Ensure server server.example.com is absent from the topology in continuous
+# mode to ignore errors
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     continue: yes
     state: absent
 
-# Ensure server server.example.com is absent with last of role check skip
+# Ensure server "server.example.com" is absent from the topology with skipping
+# the last of role check
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com
     ignore_last_of_role: yes
     state: absent
 
-# Ensure server server.example.com is absent with topology disconnect check
+# Ensure server server "server.example.com" is absent from the topology with
-# skip
+# skipping the topology disconnect check
 - ipaserver:
     ipaadmin_password: SomeADMINpassword
     name: server.example.com