From 8edb3ad5c2b719bebf2e04121f54b9aba3d50875 Mon Sep 17 00:00:00 2001
From: Will Miller <willm@stackhpc.com>
Date: Wed, 12 Sep 2018 14:20:38 +0000
Subject: [PATCH] Improve comments for override file variables

---
 ansible/host_vars/localhost  | 12 +++++++-----
 ansible/override.yml.example | 26 ++++++++++++++++++++++++--
 2 files changed, 31 insertions(+), 7 deletions(-)

diff --git a/ansible/host_vars/localhost b/ansible/host_vars/localhost
index 84e53e2..a19f882 100644
--- a/ansible/host_vars/localhost
+++ b/ansible/host_vars/localhost
@@ -35,15 +35,17 @@ node_types: {}
 # For example:
 #
 # specs:
-#     # Required.
+#     # The type in `node_types` that this spec refers to. Required.
 #   - type: type0
-#     # Required.
+#     # The number of nodes to create of this spec. Required.
 #     count: 4
-#     # Optional.
+#     # The Ironic configuration for nodes of this spec. Optional.
 #     ironic_config:
-#       # Required.
+#       # The resource class that nodes of this spec should use in Ironic.
+#       # Required if `ironic_config` has been specified.
 #       resource_class: my_rc
-#       # Optional - defaults to [].
+#       # Traits that nodes of this spec should have in Ironic. Optional -
+#       # defaults to [].
 #       traits: []
 #       # A dict of key-value pairs to be set as properties on the Ironic
 #       # nodes. Can be used to set capabilities. Optional - defaults to {}.
diff --git a/ansible/override.yml.example b/ansible/override.yml.example
index 01afc93..8d99f7f 100644
--- a/ansible/override.yml.example
+++ b/ansible/override.yml.example
@@ -2,22 +2,44 @@
 # This is an example override file, which can be used as a template for your
 # own override file.
 
+# node_types is a dict that defines different sets of node specifications,
+# keyed by a 'node type name' to associate with each set of specifications.
 node_types:
+  # The type name.
   type0:
+    # The amount of RAM, in mebibytes.
     memory_mb: 1024
+    # The number of virtual CPUs.
     vcpus: 1
+    # A list of volumes, each with a capacity.
     volumes:
       - capacity: 2GB
+    # A list of physical network names to connect to. These physical network
+    # names should be keyed in `physnet_mappings` in each hypervisor's host
+    # vars.
     physical_networks:
       - physnet0
 
+# specs is a list of configurations of nodes to be created. Each configuration
+# can specify the number of nodes to be created, the type (from `node_types`)
+# of these nodes, and optionally configuration for the Ironic nodes to be
+# enroled from these nodes. If `ironic_config` is not set, Ironic enrolment
+# will be skipped for that spec.
 specs:
+    # The type in `node_types` that this spec refers to. Required.
   - type: type0
+    # The number of nodes to create of this spec. Required.
     count: 3
+    # The Ironic configuration for nodes of this spec. Optional.
     ironic_config:
+      # The resource class that nodes of this spec should use in Ironic.
+      # Required if `ironic_config` has been specified.
       resource_class: my_rc
 
-# Remember that these mappings will apply to all hosts unless specific mappings
-# are specified in individual host_vars files.
+# Map physical network names to their source device. This can be either an
+# existing interface or an existing bridge.
+# Remember that if the mappings are specified in this file, they will apply to
+# all hosts unless specific mappings are specified in individual host_vars
+# files.
 physnet_mappings:
   physnet0: brfoo