Merge pull request #727 from geerlingguy/fix-haproxy-docs

Clarify HAProxy module documentation

network/haproxy.py

@@ -22,75 +22,74 @@ DOCUMENTATION = '''
 ---
 module: haproxy
 version_added: "1.9"
-short_description: An Ansible module to handle states enable/disable server and set weight to backend host in haproxy using socket commands.
+short_description: Enable, disable, and set weights for HAProxy backend servers using socket commands.
 description:
-    - The Enable Haproxy Backend Server, with
-      supports get current weight for server (default) and
-      set weight for haproxy backend server when provides.
-
-    - The Disable Haproxy Backend Server, with
-      supports get current weight for server (default) and
-      shutdown sessions while disabling backend host server.
+    - Enable, disable, and set weights for HAProxy backend servers using socket
+      commands.
 notes:
-    - "enable or disable commands are restricted and can only be issued on sockets configured for level 'admin', "
-    - "Check - http://haproxy.1wt.eu/download/1.5/doc/configuration.txt, "
-    - "Example: 'stats socket /var/run/haproxy.sock level admin'"
+    - Enable and disable commands are restricted and can only be issued on
+      sockets configured for level 'admin'. For example, you can add the line
+      'stats socket /var/run/haproxy.sock level admin' to the general section of
+      haproxy.cfg. See http://haproxy.1wt.eu/download/1.5/doc/configuration.txt.
 options:
-  state:
+  backend:
     description:
-      - describe the desired state of the given host in lb pool.
-    required: true
-    default: null
-    choices: [ "enabled", "disabled" ]
+      - Name of the HAProxy backend pool.
+    required: false
+    default: auto-detected
   host:
     description:
-      - Host (backend) to operate in Haproxy.
+      - Name of the backend host to change.
     required: true
     default: null
-  socket:
+  shutdown_sessions:
     description:
-      - Haproxy socket file name with path.
+      - When disabling a server, immediately terminate all the sessions attached
+        to the specified server. This can be used to terminate long-running
+        sessions after a server is put into maintenance mode.
     required: false
-    default: /var/run/haproxy.sock
-  backend:
+    default: false
+  socket:
     description:
-      - Name of the haproxy backend pool.
-        Required, else auto-detection applied.
+      - Path to the HAProxy socket file.
     required: false
-    default: auto-detected
-  weight:
+    default: /var/run/haproxy.sock
+  state:
     description:
-      - The value passed in argument. If the value ends with the '%' sign, then the new weight will be relative to the initially cnfigured weight. Relative weights are only permitted between 0 and 100% and absolute weights are permitted between 0 and 256.
-    required: false
+      - Desired state of the provided backend host.
+    required: true
     default: null
-  shutdown_sessions:
+    choices: [ "enabled", "disabled" ]
+  wait:
     description:
-      - When disabling server, immediately terminate all the sessions attached to the specified server. This can be used to terminate long-running sessions after a server is put into maintenance mode, for instance.
+      - Wait until the server reports a status of 'UP' when `state=enabled`, or
+        status of 'MAINT' when `state=disabled`.
     required: false
     default: false
-  wait:
+    version_added: "2.0"
+  wait_interval:
     description:
-      - Wait until the server reports a status of 'UP' when state=enabled, or status of 'MAINT' when state=disabled
+      - Number of seconds to wait between retries.
     required: false
-    default: false
+    default: 5
     version_added: "2.0"
   wait_retries:
     description:
-      - number of times to check for status after changing the state
+      - Number of times to check for status after changing the state.
     required: false
     default: 25
     version_added: "2.0"
-  wait_interval:
+  weight:
     description:
-      - number of seconds to wait between retries
+      - The value passed in argument. If the value ends with the `%` sign, then
+        the new weight will be relative to the initially configured weight.
+        Relative weights are only permitted between 0 and 100% and absolute
+        weights are permitted between 0 and 256.
     required: false
-    default: 5
-    version_added: "2.0"
+    default: null
 '''
 
 EXAMPLES = '''
-examples:
-
 # disable server in 'www' backend pool
 - haproxy: state=disabled host={{ inventory_hostname }} backend=www