More davinci script documentation

Improving the user experience and fixing the odd buglet along the way.

Work towards DPA task https://gitlab.cern.ch/lhcb-dpa/project/-/issues/102.

DaVinciSys/scripts/davinci

@@ -12,6 +12,7 @@
 """
 This script is meant to implement the Python Click functionality
 when running a DaVinci (Gaudi) application.
+
 Two possible functions have been developed to automatically handle
 the differences between jobs using data or simulated input files.
 
@@ -42,23 +43,26 @@ else:
     "--export",
     default=None,
     help=
-    "export the options in a format suitable for gaudirun.py. Filename has to be provided as argument.",
+    "Export the options in a format suitable for gaudirun.py.\nFilename has to be provided, with extension .opts.\nTypically used in conjunction with --dry-run.",
 )
 @click.option(
     "--with-defaults",
     is_flag=True,
     default=False,
     help=
-    "explicitly include default values of properties in the final configuration",
+    "Explicitly include default values of properties in the final configuration.",
 )
 @click.option(
     "--dry-run",
     is_flag=True,
     default=False,
-    help="just process the options but do not run the application",
+    help="Process the options but do not run the application.",
 )
 @click.version_option(version=APP_VERSION)
 def main(export, with_defaults, dry_run):
+    """
+    Try `davinci COMMAND --help` for information on COMMAND options available.
+    """
     assert not export or export.endswith(
         ".opts"), "--export argument must have '.opts' extension"
 
@@ -66,8 +70,8 @@ def main(export, with_defaults, dry_run):
 @main.resultcallback()
 def run_job(configurables, export=None, with_defaults=False, dry_run=None):
     """
-    This function is not invoked directly in Davinci but it is used to override the
-    default click 'result_callback' function by means of the 'resultcallback' decorator.
+    This function is not invoked directly by davinci but it is used to override the
+    default Click 'result_callback' function by means of the 'resultcallback' decorator.
     The 'result_callback' method is invoked automatically when returning the values
     of the main subcommnads: run_mc and run_data.
     """
@@ -143,18 +147,19 @@ def run_job(configurables, export=None, with_defaults=False, dry_run=None):
     is_flag=True,
     default=False,
     help=
-    "Option for running a simple DaVinci jobs without any specific configuration (.py)."
+    "Option for running a simple DaVinci job without any specific configuration (.py)."
 )
 @click.pass_context
 def run_mc(ctx, inputfiledb, joboptfile, simplejob):
     """
     DaVinci function for running jobs on simulated samples.
+
     Ctx: click.core.Context class (dict).
-    Predefined click object storing information about the invoked command.
-    All the options passed by command line which are not recognised by click are stored into the ctx.args element.
+    Predefined Click object storing information about the invoked command.
+    All options passed via the command line which are not recognised by Click are stored into the ctx.args element.
     Ctx.args is a simple array and each extra option is stored using two values: the first one is the key
     and the second one is the corresponding value.
-    Eg: --evt_max 100 will be stored as: ctx.args[0] = --evt_max, ctx.args[1] = 100
+    Ex.: --evt_max 100 will be stored as: ctx.args[0] = --evt_max, ctx.args[1] = 100
 
     Note:
         Click automatically converts "_" in "-", so this function can be invoked calling run-mc as shown in the help.
@@ -193,31 +198,33 @@ def run_mc(ctx, inputfiledb, joboptfile, simplejob):
     "If you want to use the standard TestFileDB set 'filedb-path' = '-'."
 )
 @click.option(
-    "--joboption-file",
+    "--joboptfile",
     default="",
-    help="Option file containing the job information (.yaml, .py)")
+    help="Option file containing the job information (.py, .yaml)")
 @click.pass_context
 def run_data(ctx, inputfiledb, optfile):
     """
     DaVinci function for running jobs on real data samples.
-    Ctx: click.core.Context class (dict). Predefined click object storing information about the invoked command.
-    All options passed by the command line that are not recognised by click are stored into the ctx.args element.
+
+    Ctx: click.core.Context class (dict).
+    Predefined Click object storing information about the invoked command.
+    All options passed via the command line that are not recognised by Click are stored into the ctx.args element.
     Ctx.args is a simple array and each extra option is stored using two values: the first one is the key
     and the second one is the corresponding value.
-    Eg: --evt_max 100 will be stored as: ctx.args[0] = --evt_max, ctx.args[1] = 100
+    Ex.: --evt_max 100 will be stored as: ctx.args[0] = --evt_max, ctx.args[1] = 100
 
     Note:
-       Click automatically converts "_" in "-", so this function can be invoked calling run-data as shown in the help.
+        Click automatically converts "_" in "-", so this function can be invoked calling run-data as shown in the help.
     """
 
     raise ValueError(
         'Data file with upgrade conditions are not yet available. Please use :mc function instead.'
     )
 
-    # Run on data sample
+    # Run on a data sample
     options.simulation = False
 
-    # Test file DB key request overrides inputfiledb
+    # TestFileDB key request overrides inputfiledb
     inputfiledb_key, inputfiledb_file = set_testfiledb(inputfiledb)
 
     ctx_args = (ctx.args if (len(ctx.args) > 1) else [])