validate: doc: Enhance documentation about testfile and meta fields

Part-of: <https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/5803>

subprojects/gst-devtools/docs/gst-validate-action-types.md

@@ -5,7 +5,10 @@
 ``` validate-scenario
 meta,
     [allow-errors=(boolean)],
+    [base-time=(double or string (GstClockTime))],
+    [configs=({GstStructure as string})],
     [duration=(double, int)],
+    [expected-issues=({GstStructure as string})],
     [handles-states=(boolean)],
     [ignore-eos=(boolean)],
     [is-config=(boolean)],
@@ -18,10 +21,13 @@ meta,
     [pipeline-name=(string)],
     [reverse-playback=(boolean)],
     [seek=(boolean)],
-    [summary=(string)];
+    [start-time=(double or string (GstClockTime))],
+    [summary=(string)],
+    [use-system-clock=(bool)];
 ```
 
 Scenario metadata.
+
 NOTE: it used to be called "description"
  * Implementer namespace: core
  * Is config action (meaning it will be executing right at the beginning of the execution of the pipeline)
@@ -35,12 +41,76 @@ scenario when it happens. By default a 'stop' action is generated on ERROR messa
 
   Default: false
 
+* `base-time`:(optional): The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).
+
+
+  Possible types: `double or string (GstClockTime)`
+
+  Default: None
+
+* `configs`:(optional): The `configs` field is an array of structures containing the same content as
+usual [configs](gst-validate-config.md) files.
+
+For example:
+
+``` yaml
+configs = {
+    # Set videotestsrc0 pattern value to `blue`
+    "core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
+    "$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
+}
+```
+
+Note: Since this is GstStructure syntax, we need to have the structures in the
+array as strings/within quotes.
+
+
+
+  Possible types: `{GstStructure as string}`
+
+  Default: {}
+
 * `duration`:(optional): Lets the user know the time the scenario needs to be fully executed
 
   Possible types: `double, int`
 
   Default: infinite (GST_CLOCK_TIME_NONE)
 
+* `expected-issues`:(optional): The `expected-issues` field is an array of `expected-issue` structures containing
+information about issues to expect (which can be known bugs or not).
+
+Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
+
+For example:
+
+``` yaml
+expected-issues = {
+    "expected-issue, issue-id=scenario::not-ended",
+}
+```
+Note: Since this is GstStructure syntax, we need to have the structures in the
+array as strings/within quotes.
+
+**Each issue has the following fields**:
+
+* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
+* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
+* `details`: Regex string to match the issue details `detected-on`: (string):
+             The name of the element the issue happened on `level`: (string):
+             Issue level
+* `sometimes`: (boolean): Default: `false` -  Wheteher the issue happens only
+               sometimes if `false` and the issue doesn't happen, an error will
+               be issued.
+* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
+               a bug.
+
+
+
+
+  Possible types: `{GstStructure as string}`
+
+  Default: {}
+
 * `handles-states`:(optional): Whether the scenario handles pipeline state changes from the beginning
 in that case the application should not set the state of the pipeline to anything
 and the scenario action will be executed from the beginning
@@ -123,12 +193,26 @@ It has the same effect as setting the pipeline using pipeline_name->scenario_nam
 
   Default: false
 
-* `summary`:(optional): Whether the scenario is a config only scenario (ie. explain what it does)
+* `start-time`:(optional): The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).
+
+
+  Possible types: `double or string (GstClockTime)`
+
+  Default: None
+
+* `summary`:(optional): A human readable summary of what the test/scenario does
 
   Possible types: `string`
 
   Default: 'Nothing'
 
+* `use-system-clock`:(optional): The `use-system-clock` fields lets you force the Pipeline to use the
+[`GstSystemClock`](GstSystemClock)
+
+  Possible types: `bool`
+
+  Default: false
+
 ## seek
 
 

subprojects/gst-devtools/docs/gst-validate-test-file.md

@@ -12,9 +12,8 @@ describe the validate [scenario](gst-validate-scenarios.md).
 
 # The file format
 
-A validate test file requires a `meta` structure which contains the same
+A validate test file requires a [`meta`](gst-validate-action-types.md?#meta) structure  describing
-information as the [scenario](gst-validate-scenarios.md) `meta` with some
+the test and configuring it. The `meta` structure should be either the
-additional fields described below. The `meta` structure should be either the
 first or the one following the `set-globals` structure. The `set-globals`
 structures allows you to set global variables for the rest of the
 `.validatetest` file and is a free form variables setter. For example you can
@@ -40,71 +39,7 @@ args = {
 }
 ```
 
-## configs
+## Variables
-
-The `configs` field is an array of structures containing the same content as
-usual [configs](gst-validate-config.md) files.
-
-For example:
-
-``` yaml
-configs = {
-    # Set videotestsrc0 pattern value to `blue`
-    "core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
-    "$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
-}
-```
-
-Note: Since this is GstStructure synthax, we need to have the structures in the
-array as strings/within quotes.
-
-## `base-time`
-
-The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).
-
-## `use-system-clock`
-
-The `use-system-clock` fields lets you set force the Pipeline to use the
-[`GstSystemClock`](GstSystemClock)
-
-## `start-time`
-
-The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).
-
-## expected-issues
-
-The `expected-issues` field is an array of `expected-issue` structures containing
-information about issues to expect (which can be known bugs or not).
-
-Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
-
-For example:
-
-``` yaml
-expected-issues = {
-    "expected-issue, issue-id=scenario::not-ended",
-}
-```
-
-Note: Since this is GstStructure synthax, we need to have the structures in the
-array as strings/within quotes.
-
-### Fields:
-
-* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
-* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
-* `details`: Regex string to match the issue details `detected-on`: (string):
-             The name of the element the issue happened on `level`: (string):
-             Issue level
-* `sometimes`: (boolean): Default: `false` -  Wheteher the issue happens only
-               sometimes if `false` and the issue doesn't happen, an error will
-               be issued.
-* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
-               a bug.
-
-### Variables
-
-The same way
 
 Validate testfile will define some variables to make those files relocable:
 

subprojects/gst-devtools/validate/gst/validate/doc/meta-configs.md

@@ -0,0 +1,17 @@
+The `configs` field is an array of structures containing the same content as
+usual [configs](gst-validate-config.md) files.
+
+For example:
+
+``` yaml
+configs = {
+    # Set videotestsrc0 pattern value to `blue`
+    "core, action=set-property, target-element-name=videotestsrc0, property-name=pattern, property-value=blue",
+    "$(validateflow), pad=sink1:sink, caps-properties={ width, height };",
+}
+```
+
+Note: Since this is GstStructure syntax, we need to have the structures in the
+array as strings/within quotes.
+
+**Warning**: This field is validate only for [`.validatetest`](gst-validate-test.md) files, and not `.scenario`.

subprojects/gst-devtools/validate/gst/validate/doc/meta-expected-issues.md

@@ -0,0 +1,29 @@
+The `expected-issues` field is an array of `expected-issue` structures containing
+information about issues to expect (which can be known bugs or not).
+
+Use `gst-validate-1.0 --print-issue-types` to print information about all issue types.
+
+For example:
+
+``` yaml
+expected-issues = {
+    "expected-issue, issue-id=scenario::not-ended",
+}
+```
+Note: Since this is GstStructure syntax, we need to have the structures in the
+array as strings/within quotes.
+
+**Each issue has the following fields**:
+
+* `issue-id`: (string): Issue ID - Mandatory if `summary` is not provided.
+* `summary`: (string): Summary - Mandatory if `issue-id` is not provided.
+* `details`: Regex string to match the issue details `detected-on`: (string):
+             The name of the element the issue happened on `level`: (string):
+             Issue level
+* `sometimes`: (boolean): Default: `false` -  Wheteher the issue happens only
+               sometimes if `false` and the issue doesn't happen, an error will
+               be issued.
+* `issue-url`: (string): The url of the issue in the bug tracker if the issue is
+               a bug.
+
+**Warning**: This field is validate only for [`.validatetest`](gst-validate-test.md) files, and not `.scenario`.

subprojects/gst-devtools/validate/gst/validate/gst-validate-scenario.c

@@ -58,6 +58,7 @@
 #include "gst-validate-utils.h"
 #include "gst-validate-internal.h"
 #include "validate.h"
+#include "validate-resources.h"
 #include <gst/controller/controller.h>
 #include <gst/app/app.h>
 #include <gst/validate/gst-validate-override.h>
@@ -7574,12 +7575,21 @@ register_action_types (void)
   _gst_validate_action_type = gst_validate_action_get_type ();
   _gst_validate_action_type_type = gst_validate_action_type_get_type ();
 
+  GResource *resource = validate_get_resource ();
+  g_assert (resource);
+  GBytes *meta_config_doc =
+      g_resource_lookup_data (resource, "/validate/doc/meta-configs.md",
+      G_RESOURCE_LOOKUP_FLAGS_NONE, NULL);
+  GBytes *meta_expected_issues_doc =
+      g_resource_lookup_data (resource, "/validate/doc/meta-expected-issues.md",
+      G_RESOURCE_LOOKUP_FLAGS_NONE, NULL);
+
   /*  *INDENT-OFF* */
   REGISTER_ACTION_TYPE ("meta", NULL,
       ((GstValidateActionParameter [])  {
       {
         .name = "summary",
-        .description = "Whether the scenario is a config only scenario (ie. explain what it does)",
+        .description = "A human readable summary of what the test/scenario does",
         .mandatory = FALSE,
         .types = "string",
         .possible_variables = NULL,
@@ -7708,10 +7718,53 @@ register_action_types (void)
         .possible_variables = NULL,
         .def = "false"
       },
+      {
+        .name = "base-time",
+        .description = "The `base-time` fields lets you set the Pipeline base-time as defined in [gst_element_set_base_time](gst_element_set_base_time).\n",
+        .mandatory = FALSE,
+        .types = "double or string (GstClockTime)",
+        .possible_variables = NULL,
+        .def = "None"
+      },
+      {
+        .name = "start-time",
+        .description = "The `start-time` fields lets you set the Pipeline start-time as defined in [gst_element_set_start_time](gst_element_set_start_time).\n",
+        .mandatory = FALSE,
+        .types = "double or string (GstClockTime)",
+        .possible_variables = NULL,
+        .def = "None"
+      },
+      {
+        .name = "use-system-clock",
+        .description = "The `use-system-clock` fields lets you force the Pipeline to use the\n"
+              "[`GstSystemClock`](GstSystemClock)",
+        .mandatory = FALSE,
+        .types = "bool",
+        .possible_variables = NULL,
+        .def = "false"
+      },
+      {
+        .name="configs",
+        .description=g_bytes_get_data (meta_config_doc, NULL),
+        .mandatory = FALSE,
+        .types = "{GstStructure as string}",
+        .possible_variables = NULL,
+        .def = "{}"
+      },
+      {
+        .name="expected-issues",
+        .description=g_bytes_get_data (meta_expected_issues_doc, NULL),
+        .mandatory = FALSE,
+        .types = "{GstStructure as string}",
+        .possible_variables = NULL,
+        .def = "{}"
+      },
       {NULL}
       }),
-      "Scenario metadata.\nNOTE: it used to be called \"description\"",
+      "Scenario metadata.\n\nNOTE: it used to be called \"description\"",
       GST_VALIDATE_ACTION_TYPE_CONFIG);
+  g_bytes_unref (meta_config_doc);
+  g_bytes_unref (meta_expected_issues_doc);
 
   REGISTER_ACTION_TYPE ("seek", _execute_seek,
       ((GstValidateActionParameter [])  {

subprojects/gst-devtools/validate/gst/validate/meson.build

@@ -56,10 +56,17 @@ gst_validate_enums = gnome.mkenums('gstvalidateenumtypes',
   install_header : true,
   install_dir : join_paths(get_option('includedir'), 'gstreamer-1.0/gst/validate'))
 
+
+validate_resources = gnome.compile_resources(
+    'validate-resources', 'validate.res',
+    source_dir: '.',
+    c_name: 'validate'
+)
+
 validate_deps = [gst_check_dep, gst_dep, gst_controller_dep, gstbase_dep, gstapp_dep,
                  gio_dep, gmodule_dep, gst_pbutils_dep, mathlib, json_dep]
 gstvalidate = library('gstvalidate-@0@'.format(apiversion),
-    sources: gstvalidate_sources + gst_validate_enums + runner_file,
+    sources: gstvalidate_sources + gst_validate_enums + runner_file + validate_resources,
     version : libversion,
     soversion : soversion,
     darwin_versions : osxversion,
@@ -70,7 +77,7 @@ gstvalidate = library('gstvalidate-@0@'.format(apiversion),
 
 if not static_build
   gstvalidatetracer = library('gstvalidatetracer',
-      sources: gst_validate_enums + runner_file,
+      sources: gst_validate_enums + runner_file + validate_resources,
       include_directories : [inc_dirs],
       install: true,
       c_args : [gst_c_args] + ['-D__GST_VALIDATE_PLUGIN', '-D_GNU_SOURCE', '-DBUILDING_GST_VALIDATE'],

subprojects/gst-devtools/validate/gst/validate/validate.res

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<gresources>
+  <gresource prefix="/validate/">
+    <file>doc/meta-configs.md</file>
+    <file>doc/meta-expected-issues.md</file>
+  </gresource>
+</gresources>
+