docs: More docs

Author: Alan Christie

workflow/workflow_validator.py

@@ -2,30 +2,32 @@
 
 A module that provides workflow validation at levels beyond the schema. A workflow
 definition is a complex structure, and not all of its content can be checked using
-a JSON/YAML schema alone. This module provides various 'levels' of workflow
-inspection of the workflow in increasing levels of validation: -
+a JSON/YAML schema alone. This module provides a number of validation levels
+with increasing levels of 'inspection'. The levels are called CREATE, RUN, and
+TAG.
 
-- CREATE
-- RUN
-- TAG
+    CREATE level validation simply checks that the workflow complies with the schema.
+    Workflows are permitted in the DM that do not comply with the schema. This is
+    becuase the DM is also used as a persistent store for Wwrfklows while editing - this
+    allows a user to 'save' a workflow that is incomplete with the intention of
+    adjusting it at a later date prior to execution.
 
-CREATE level validation simply checks that the workflow complies with the schema.
-Workflows are permitted in the DM that do not comply with the schema. This is becuase
-the DM is also used as a persistent store for Wwrfklows while editing - this
-allows a user to 'save' a workflow that is incomplete with the intention of adjusting
-it at a later date prior to execution.
+    TAG level validation takes things a little further. In 'production' mode
+    tagging is required prior to exeution. TAG level validatioin ensures that a workflow
+    _should_ run if it is run - for examplke variable names are all correctly defined
+    and there are no duplicates.
 
-TAG level validation takes things a little further. In 'production' mode
-tagging is required prior to exeution. TAG level validatioin ensures that a workflow
-_should_ run if it is run - for examplke variable names are all correctly defined
-and there are no duplicates.
-
-RUN level extends TAG level validation by ensuring, for example, all the
-workflow variables are defined.
+    RUN level extends TAG level validation by ensuring, for example, all the
+    workflow variables are defined.
 
 Validation is designed to allow a more relaxed engine implementation, negating the
 need for the engine to 'check', for example, that variables exist - the validator
-ensures they do.
+ensures they do so that the engine can concentrate on laucnhing steps rather than
+implementing swatchs of lines of logic to protect against mal-use.
+
+It is the Data Manager that is responsible for invoking the validator. It does this
+prior to allowing a user to run a workflow. When the engine receives a 'Workflow Start'
+message it can be sure that the chosen workflow can run.
 
 Module philosophy
 -----------------