exactness docs: Add docs, fix docs, remove docs

Summary:
The Exactness tool needed usage instructions... and quite some more
fixes. There was copypasta all around.

Depends on D11634

Test Plan: Build and Enjoy

Reviewers: bu5hm4n, stefan_schmidt

Reviewed By: stefan_schmidt

Subscribers: cedric, #reviewers, #committers

Tags: #efl

Differential Revision: https://phab.enlightenment.org/D11637

4 files changed, 96 insertions, 44 deletions

diff --git a/src/bin/exactness/exactness.c b/src/bin/exactness/exactness.c
index 6599ef7741..c99fceeb99 100644
--- a/src/bin/exactness/exactness.c
+++ b/src/bin/exactness/exactness.c
@@ -417,22 +417,51 @@ _errors_sort_cb(List_Entry *a, List_Entry *b)
 
 static const Ecore_Getopt optdesc = {
   "exactness",
-  "%prog [options] <-r|-p|-i|-s> <list file>",
+  "%prog [options] <-p|-i|-s> <test list file>",
   PACKAGE_VERSION,
-  "(C) 2013 Enlightenment",
+  "(C) 2013-2020 Enlightenment",
   "BSD",
-  "A pixel perfect test suite for EFL based applications.",
+  "A pixel-perfect test suite for EFL-based applications.\n"
+  "\n"
+  "This binary allows running the individual tools `exactness_record` and\n"
+  "`exactness_play` in batch for a set of tests specified in a test list file.\n"
+  "\n"
+  "To obtain the reference templates (the \"golden\" files):\n"
+  "1.For each tested application, run `exactness_record` to launch the\n"
+  "   application and record actions like keystrokes and mouse clicks.\n"
+  "   This produces a test file with `.exu` extension.\n"
+  "2.Run `exactness` in init mode (-i) to execute the stored actions in all\n"
+  "   the tests in the test list file and obtain screenshots.\n"
+  "   The screenshots are embedded into the test `.exu` file.\n"
+  "\n"
+  "To check if the application currently matches the reference templates:\n"
+  "1.Run `exactness` in play mode (-p) to execute the stored actions in all\n"
+  "   the tests in the test list file and compare the obtained screenshots\n"
+  "   with the stored versions (the reference templates).\n"
+  "   If mismatches are detected an error report is produced, including\n"
+  "   a graphical diff of the screenshots.\n"
+  "\n"
+  "The test list file contains one line per test. Each line starts with the\n"
+  "test file name (without the `.exu` extension), a space and then the command\n"
+  "to execute, including parameters if any. # indicates a comment.\n"
+  "Example:\n"
+  "separator elementary_test -to Separator",
   0,
   {
-    ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files.", ECORE_GETOPT_TYPE_STR),
-    ECORE_GETOPT_STORE_STR('o', "output", "The location of the images."),
+    ECORE_GETOPT_APPEND('b', "base-dir", "The location of the exu files. Defaults to `./recordings/`.",
+      ECORE_GETOPT_TYPE_STR),
+    ECORE_GETOPT_STORE_STR('o', "output", "The location of the images. Defaults to `./`."),
     ECORE_GETOPT_STORE_STR('w', "wrap", "Use a custom command to launch the tests (e.g valgrind)."),
-    ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel."),
-    ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode."),
-    ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode."),
-    ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode."),
-    ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot."),
-    ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots."),
+    ECORE_GETOPT_STORE_USHORT('j', "jobs", "The number of jobs to run in parallel. Defaults to 1."),
+    ECORE_GETOPT_STORE_TRUE('p', "play", "Run in play mode. Actions are executed and obtained "
+      "screenshots are compared to the stored version (golden templates)."),
+    ECORE_GETOPT_STORE_TRUE('i', "init", "Run in init mode. Actions are executed and obtained "
+      "screenshots are stored to be used as golden templates in the future."),
+    ECORE_GETOPT_STORE_TRUE('s', "simulation", "Run in simulation mode. Actions are executed and "
+      "displayed but no screenshot is obtained. Useful for debugging."),
+    ECORE_GETOPT_STORE_TRUE(0, "scan-objects", "Extract information of all the objects at every shot (UNUSED)."),
+    ECORE_GETOPT_STORE_TRUE(0, "disable-screenshots", "Disable screenshots. Only checks that actions "
+      "can be performed and the application does not crash."),
     ECORE_GETOPT_STORE_STR('f', "fonts-dir", "Specify a directory of the fonts that should be used."),
     ECORE_GETOPT_STORE_TRUE(0, "stabilize-shots", "Wait for the frames to be stable before taking the shots."),
     ECORE_GETOPT_COUNT('v', "verbose", "Turn verbose messages on."),
@@ -502,14 +531,14 @@ main(int argc, char *argv[])
      }
    else if (args == argc)
      {
-        fprintf(stderr, "Expected test list as the last argument..\n");
+        fprintf(stderr, "Expected test list file as the last argument..\n");
         ecore_getopt_help(stderr, &optdesc);
         ret = 1;
         goto end;
      }
    else if (mode_play + mode_init + mode_simulation != 1)
      {
-        fprintf(stderr, "At least and only one of the running modes can be set.\n");
+        fprintf(stderr, "Exactly one running mode must be set.\n");
         ecore_getopt_help(stderr, &optdesc);
         ret = 1;
         goto end;
@@ -525,7 +554,7 @@ main(int argc, char *argv[])
 
    if (!test_list)
      {
-        fprintf(stderr, "No matching tests found in '%s'\n", list_file);
+        fprintf(stderr, "No matching tests found in list file '%s'\n", list_file);
         ret = 1;
         goto end;
      }
@@ -533,7 +562,7 @@ main(int argc, char *argv[])
    /* Pre-run summary */
    fprintf(stderr, "Running with settings:\n");
    fprintf(stderr, "\tConcurrent jobs: %d\n", _max_jobs);
-   fprintf(stderr, "\tTest list: %s\n", list_file);
+   fprintf(stderr, "\tTest list file: %s\n", list_file);
    fprintf(stderr, "\tBase dirs:\n");
    EINA_LIST_FOREACH(_base_dirs, itr, base_dir)
       fprintf(stderr, "\t\t%s\n", base_dir);
diff --git a/src/bin/exactness/exactness_play.in b/src/bin/exactness/exactness_play.in
index 650826f871..38200d9ba1 100644
--- a/src/bin/exactness/exactness_play.in
+++ b/src/bin/exactness/exactness_play.in
@@ -4,18 +4,23 @@ import argparse
 import subprocess
 import os
 
-parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.'
-                                              '\tF1 - Request stabilization\n'
-                                              '\tF2 - Request shot\n'
-                                              '\tF3 - Request to save the scenario\n')
-parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*')
-parser.add_argument('-o', '--output', metavar='output', help=" Set the destination for the shots.\n"
-          " If a .exu is given, the shots are stored in the file.\n"
-          " Otherwise the given path is considered as a directory\n"
-          " where shots will be stored.\n"
-          " If omitted, the output type (exu or dir) is determined\n"
-          " by the given test extension (resp. exu or rec).", type=str)
-parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str)
+parser = argparse.ArgumentParser(description='A recorded scenario player for EFL-based applications.\n\n'
+  'Actions recorded with `exactness_record` can be played back with this\n'
+  'application and screenshots obtained. It is typically more convenient to\n'
+  'use the `exactness` wrapper in "play" mode to process files in batches.',
+  formatter_class=argparse.RawDescriptionHelpFormatter,
+  epilog='Example:\n'
+  'exactness_play -s -t my_app.exu -- my_app --app --arguments')
+parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. '
+  'Use a -- if you need to provide arguments to the app.',
+  type=str, nargs='*')
+parser.add_argument('-o', '--output', metavar='output', help="Destination for the shots. "
+          "If a `.exu` file is given, the shots are stored in the file. "
+          "Otherwise the given path is considered as a directory "
+          "where shots will be stored. "
+          "If omitted, the output type (exu or dir) is determined "
+          "by the given test extension (resp. exu or rec).", type=str)
+parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test.', type=str)
 parser.add_argument('-s', '--show-on-screen', help='Show on screen', action='store_true', default=False)
 parser.add_argument('--scan-objects', help='Extract information of all the objects at every shot.', action='store_true')
 parser.add_argument('--external-injection', help='Expect events injection via Eina debug channel.', action='store_true')
@@ -24,9 +29,9 @@ parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Specify a dire
 parser.add_argument('--stabilize-shots', help='Wait for the frames to be stable before taking the shots.', action='store_true')
 parser.add_argument('--speed', metavar='speed', help='Set the speed used to play the given test (default 1.0).', type=float, default=1.0)
 parser.add_argument('-v', '--verbose', help='Turn verbose messages on', action='store_true')
-parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true')
-parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true')
-parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true')
+parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true')
+parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true')
+parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true')
 
 G = parser.parse_args()
 
@@ -35,7 +40,7 @@ if G.license:
   exit(0)
 
 if G.copyright:
-  print("(C) 2017 Enlightenment.")
+  print("(C) 2017-2020 Enlightenment.")
   exit(0)
 
 if G.version:
diff --git a/src/bin/exactness/exactness_record.in b/src/bin/exactness/exactness_record.in
index 9c6d4cf4fd..377d465199 100644
--- a/src/bin/exactness/exactness_record.in
+++ b/src/bin/exactness/exactness_record.in
@@ -4,16 +4,31 @@ import argparse
 import subprocess
 import os
 
-parser = argparse.ArgumentParser(description='A scenario recorder for EFL based applications.'
-                                              '\tF1 - Request stabilization\n'
-                                              '\tF2 - Request shot\n'
-                                              '\tF3 - Request to save the scenario\n')
-parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here.', type=str, nargs='*')
-parser.add_argument('-t', '--tests', metavar='tests', help='Name of the filename where to store the test.', type=str)
-parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Specify a directory of the fonts that should be used.', type=str)
-parser.add_argument('-L', '--license', help='the path where to find the meson build directory', action='store_true')
-parser.add_argument('-C', '--copyright', help='the path where to find the meson build directory', action='store_true')
-parser.add_argument('-V', '--version', help='the path where to find the meson build directory', action='store_true')
+parser = argparse.ArgumentParser(description='A scenario recorder for EFL-based applications.\n\n'
+  'This records all actions the user performs on an EFL application (like keystrokes\n'
+  'and mouse clicks) and stores them on a file.\n'
+  'Later on, the `exactness` or `exactness_play` commands can be used to play\n'
+  'back these actions and obtain screenshots.\n'
+  '\n'
+  'While running this application, use the following keys to control the process:\n'
+  '\tF1 - Request stabilization.\n'
+  '\tF2 - Request screenshot.\n'
+  '\tF3 - Request to save the scenario.\n'
+  '\n'
+  'Note: If you don\'t press F3 at least once, no output file will be generated.',
+  formatter_class=argparse.RawDescriptionHelpFormatter,
+  epilog='Example:\n'
+  'exactness_record -t my_app.exu -- my_app --app --arguments')
+parser.add_argument('app', metavar='app', help='The app to run. You can also pass environment variables here. '
+  'Use a -- if you need to provide arguments to the app.',
+  type=str, nargs='*')
+parser.add_argument('-t', '--tests', metavar='tests', help='Name of the file where to store the test. '
+  'It is recommended to use the `.exu` extension.', type=str)
+parser.add_argument('-f', '--fontsdir', metavar='fontsdir', help='Directory of the fonts that should be used.',
+  type=str)
+parser.add_argument('-L', '--license', help='Print license information and exit.', action='store_true')
+parser.add_argument('-C', '--copyright', help='Print copyright information and exit.', action='store_true')
+parser.add_argument('-V', '--version', help='Print version information and exit.', action='store_true')
 
 G = parser.parse_args()
 
@@ -22,7 +37,7 @@ if G.license:
   exit(0)
 
 if G.copyright:
-  print("(C) 2017 Enlightenment.")
+  print("(C) 2017-2020 Enlightenment.")
   exit(0)
 
 if G.version:
diff --git a/src/bin/exactness/inspect.c b/src/bin/exactness/inspect.c
index 68da3548a3..1e1dc48018 100644
--- a/src/bin/exactness/inspect.c
+++ b/src/bin/exactness/inspect.c
@@ -1239,9 +1239,12 @@ static const Ecore_Getopt optdesc = {
   "exactness_inspect",
   "%prog [options] [<exu file> | <file1 file2>]",
   NULL,
-  "(C) 2016 Enlightenment",
+  "(C) 2016-2020 Enlightenment",
   "BSD",
-  "Inspector for Exactness",
+  "Inspector for Exactness\n"
+  "\n"
+  "Dumps the contents of `.exu` files obtained with `exactness_record` or"
+  "`exactness -i` in an easy-to-examine way.",
   0,
   {
     ECORE_GETOPT_STORE_USHORT('d', "delay", "Delay the given recording by a given time (in milliseconds)."),