docs/revent: Clarify the naming conventions for revent recordings

As per https://github.com/ARM-software/workload-automation/issues/968
the current documentation for detailing the naming scheme for an revent
recording is unclear. Reword the descriptions focusing on the typical
usecase rather then based on a customized target class.

doc/source/developer_information/developer_reference/revent.rst

@@ -5,10 +5,12 @@ Convention for Naming revent Files for Revent Workloads
 -------------------------------------------------------------------------------
 
 There is a convention for naming revent files which you should follow if you
-want to record your own revent files. Each revent file must start with the
+want to record your own revent files. Each revent file must be called (case sensitive)
-device name(case sensitive) then followed by a dot '.' then the stage name
+``<device name>.<stage>.revent``,
-then '.revent'. All your custom revent files should reside at
+where ``<device name>`` is the name of your device (as defined by the model
-``'~/.workload_automation/dependencies/WORKLOAD NAME/'``. These are the current
+name of your device which can be retrieved with
+``adb shell getprop ro.product.model`` or by the ``name`` attribute of your
+customized device class), and ``<stage>`` is one of the following currently
 supported stages:
 
         :setup: This stage is where the application is loaded (if present). It is
@@ -26,10 +28,12 @@ Only the run stage is mandatory, the remaining stages will be replayed if a
 recording is present otherwise no actions will be performed for that particular
 stage.
 
-For instance, to add a custom revent files for a device named "mydevice" and
+All your custom revent files should reside at
-a workload name "myworkload", you need to add the revent files to the directory
+``'$WA_USER_DIRECTORY/dependencies/WORKLOAD NAME/'``. So
-``/home/$WA_USER_HOME/dependencies/myworkload/revent_files`` creating it if
+typically to add a custom revent files for a device named "mydevice" and a
-necessary. ::
+workload name "myworkload", you would need to add the revent files to the
+directory ``~/.workload_automation/dependencies/myworkload/revent_files``
+creating the directory structure if necessary. ::
 
     mydevice.setup.revent
     mydevice.run.revent

doc/source/user_information/how_tos/revent.rst

@@ -14,9 +14,9 @@ Using revent with workloads
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Some workloads (pretty much all games) rely on recorded revents for their
-execution. ReventWorkloads will require between 1 and 4 revent files be be ran.
+execution. ReventWorkloads require between 1 and 4 revent files to be ran.
-There is one mandatory recording ``run`` for performing the actual execution of
+There is one mandatory recording, ``run``, for performing the actual execution of
-the workload and the remaining are optional. ``setup`` can be used to perform
+the workload and the remaining stages are optional. ``setup`` can be used to perform
 the initial setup (navigating menus, selecting game modes, etc).
 ``extract_results`` can be used to perform any actions after the main stage of
 the workload for example to navigate a results or summary screen of the app. And
@@ -26,17 +26,21 @@ exiting the app.
 Because revents are very device-specific\ [*]_, these files would need to
 be recorded for each device.
 
-The files must be called ``<device name>.(setup|run|extract_results|teardown).revent``
+The files must be called ``<device name>.(setup|run|extract_results|teardown).revent``,
-, where ``<device name>`` is the name of your device (as defined by the ``name``
+where ``<device name>`` is the name of your device (as defined by the model
-attribute of your device's class). WA will look for these files in two
+name of your device which can be retrieved with
-places: ``<install dir>/wa/workloads/<workload name>/revent_files``
+``adb shell getprop ro.product.model`` or by the ``name`` attribute of your
-and ``~/.workload_automation/dependencies/<workload name>``. The first
+customized device class).
-location is primarily intended for revent files that come with WA (and if
+
+WA will look for these files in two places:
+``<installdir>/wa/workloads/<workload name>/revent_files`` and
+``$WA_USER_DIRECTORY/dependencies/<workload name>``. The
+first location is primarily intended for revent files that come with WA (and if
 you did a system-wide install, you'll need sudo to add files there), so it's
-probably easier to use the second location for the files you record. Also,
+probably easier to use the second location for the files you record. Also, if
-if revent files for a workload exist in both locations, the files under
+revent files for a workload exist in both locations, the files under
-``~/.workload_automation/dependencies`` will be used in favour of those
+``$WA_USER_DIRECTORY/dependencies`` will be used in favour
-installed with WA.
+of those installed with WA.
 
 .. [*] It's not just about screen resolution -- the event codes may be different
        even if devices use the same screen.