validate: Add/fix various annotations

And fix monitor constructors to correctly check for valid arguments.

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

subprojects/gst-devtools/validate/gst/validate/gst-validate-bin-monitor.c

@@ -194,25 +194,18 @@ gst_validate_bin_monitor_init (GstValidateBinMonitor * bin_monitor)
  * @runner: (transfer none): a #GstValidateRunner
  * @parent: (nullable): The parent of the new monitor
  *
- * Returns: (transfer full): A #GstValidateBinMonitor or NULL
+ * Returns: (transfer full): A #GstValidateBinMonitor
  */
 GstValidateBinMonitor *
 gst_validate_bin_monitor_new (GstBin * bin, GstValidateRunner * runner,
     GstValidateMonitor * parent)
 {
-  GstValidateBinMonitor *monitor =
+  g_return_val_if_fail (GST_IS_BIN (bin), NULL);
+  g_return_val_if_fail (runner != NULL, NULL);
+
+  return
       g_object_new (GST_TYPE_VALIDATE_BIN_MONITOR, "object",
       bin, "validate-runner", runner, "validate-parent", parent, NULL);
-  GstObject *target =
-      gst_validate_monitor_get_target (GST_VALIDATE_MONITOR (monitor));
-
-  if (target == NULL) {
-    g_object_unref (monitor);
-    return NULL;
-  }
-  gst_object_unref (target);
-
-  return monitor;
 }
 
 static void

subprojects/gst-devtools/validate/gst/validate/gst-validate-element-monitor.c

@@ -155,31 +155,17 @@ gst_validate_element_monitor_init (GstValidateElementMonitor * element_monitor)
  * @runner: (transfer none): a #GstValidateRunner
  * @parent: (nullable): The parent of the new monitor
  *
- * Returns: (transfer full): A #GstValidateElementMonitor or NULL
+ * Returns: (transfer full): A #GstValidateElementMonitor
  */
 GstValidateElementMonitor *
 gst_validate_element_monitor_new (GstElement * element,
     GstValidateRunner * runner, GstValidateMonitor * parent)
 {
-  GstValidateElementMonitor *monitor;
+  g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
-  GstElement *target;
+  g_return_val_if_fail (runner != NULL, NULL);
 
-  g_return_val_if_fail (element != NULL, NULL);
+  return g_object_new (GST_TYPE_VALIDATE_ELEMENT_MONITOR, "object", element,
-
-  monitor = g_object_new (GST_TYPE_VALIDATE_ELEMENT_MONITOR, "object", element,
       "validate-runner", runner, "validate-parent", parent, NULL);
-
-  target =
-      GST_ELEMENT (gst_validate_monitor_get_target (GST_VALIDATE_MONITOR
-          (monitor)));
-
-  if (!target) {
-    g_object_unref (monitor);
-    return NULL;
-  }
-
-  gst_object_unref (target);
-  return monitor;
 }
 
 static GstElement *

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

@@ -77,7 +77,7 @@ _get_reporting_level (GstValidateReporter * monitor)
  * gst_validate_monitor_get_pipeline:
  * @monitor: The monitor to get the pipeline from
  *
- * Returns: (transfer full)(nullable): The pipeline in which @monitor
+ * Returns: (transfer full) (nullable): The pipeline in which @monitor
  * target is in.
  */
 GstPipeline *
@@ -90,7 +90,7 @@ gst_validate_monitor_get_pipeline (GstValidateMonitor * monitor)
  * gst_validate_monitor_get_target:
  * @monitor: The monitor to get the target from
  *
- * Returns: (transfer full)(nullable): The target object
+ * Returns: (transfer full) (nullable): The target object
  */
 GstObject *
 gst_validate_monitor_get_target (GstValidateMonitor * monitor)
@@ -317,7 +317,7 @@ gst_validate_monitor_setup (GstValidateMonitor * monitor)
  * gst_validate_monitor_get_element
  * @monitor: The monitor
  *
- * Returns: (transfer none): The GstElement associated with @monitor
+ * Returns: (transfer none) (nullable): The GstElement associated with @monitor
  */
 GstElement *
 gst_validate_monitor_get_element (GstValidateMonitor * monitor)
@@ -331,6 +331,12 @@ gst_validate_monitor_get_element (GstValidateMonitor * monitor)
   return element;
 }
 
+/**
+ * gst_validate_monitor_get_element_name
+ * @monitor: The monitor
+ *
+ * Returns: (transfer full) (nullable): The name of the element associated with @monitor
+ */
 gchar *
 gst_validate_monitor_get_element_name (GstValidateMonitor * monitor)
 {

subprojects/gst-devtools/validate/gst/validate/gst-validate-pad-monitor.c

@@ -1041,25 +1041,18 @@ gst_validate_pad_monitor_init (GstValidatePadMonitor * pad_monitor)
  * @runner: (transfer none): a #GstValidateRunner
  * @parent: (nullable): The parent of the new monitor
  *
- * Returns: (transfer full): A #GstValidatePadMonitor or NULL
+ * Returns: (transfer full): A #GstValidatePadMonitor
  */
 GstValidatePadMonitor *
 gst_validate_pad_monitor_new (GstPad * pad, GstValidateRunner * runner,
     GstValidateElementMonitor * parent)
 {
-  GstValidatePadMonitor *monitor = g_object_new (GST_TYPE_VALIDATE_PAD_MONITOR,
+  g_return_val_if_fail (GST_IS_PAD (pad), NULL);
+  g_return_val_if_fail (runner != NULL, NULL);
+
+  return g_object_new (GST_TYPE_VALIDATE_PAD_MONITOR,
       "object", pad, "validate-runner", runner, "validate-parent",
       parent, NULL);
-  GstObject *target =
-      gst_validate_monitor_get_target (GST_VALIDATE_MONITOR (monitor));
-
-  if (target == NULL) {
-    g_object_unref (monitor);
-    return NULL;
-  }
-
-  gst_object_unref (target);
-  return monitor;
 }
 
 static GstElement *

subprojects/gst-devtools/validate/gst/validate/gst-validate-pipeline-monitor.c

@@ -826,24 +826,22 @@ done:
  * @runner: (transfer none): a #GstValidateRunner
  * @parent: (nullable): The parent of the new monitor
  *
- * Returns: (transfer full): A #GstValidatePipelineMonitor or NULL
+ * Returns: (transfer full): A #GstValidatePipelineMonitor
  */
 GstValidatePipelineMonitor *
 gst_validate_pipeline_monitor_new (GstPipeline * pipeline,
     GstValidateRunner * runner, GstValidateMonitor * parent)
 {
   GstBus *bus;
-  GstValidatePipelineMonitor *monitor =
+  GstValidatePipelineMonitor *monitor;
+
+  g_return_val_if_fail (GST_IS_PIPELINE (pipeline), NULL);
+  g_return_val_if_fail (runner != NULL, NULL);
+
+  monitor =
       g_object_new (GST_TYPE_VALIDATE_PIPELINE_MONITOR, "object",
       pipeline, "validate-runner", runner, "validate-parent", parent,
       "pipeline", pipeline, NULL);
-  GstObject *target =
-      gst_validate_monitor_get_target (GST_VALIDATE_MONITOR (monitor));
-
-  if (target == NULL) {
-    g_object_unref (monitor);
-    return NULL;
-  }
 
   gst_validate_pipeline_monitor_create_scenarios (GST_VALIDATE_BIN_MONITOR
       (monitor));
@@ -865,7 +863,6 @@ gst_validate_pipeline_monitor_new (GstPipeline * pipeline,
     monitor->is_playbin = TRUE;
   else if (g_strcmp0 (G_OBJECT_TYPE_NAME (pipeline), "GstPlayBin3") == 0)
     monitor->is_playbin3 = TRUE;
-  gst_object_unref (target);
 
   return monitor;
 }

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

@@ -209,14 +209,14 @@ MAKE_GETTER_COPY (gchar *, reporter_name, g_strdup);
 /**
  * gst_validate_report_get_trace:
  *
- * Returns: (transfer full): report backtrace
+ * Returns: (transfer full) (nullable): report backtrace
  * Since: 1.22
  */
 MAKE_GETTER_COPY (gchar *, trace, g_strdup);
 /**
  * gst_validate_report_get_dotfile_name:
  *
- * Returns: (transfer full): report dot file name
+ * Returns: (transfer full) (nullable): report dot file name
  * Since: 1.22
  */
 MAKE_GETTER_COPY (gchar *, dotfile_name, g_strdup);
@@ -744,6 +744,12 @@ gst_validate_report_deinit (void)
   g_clear_object (&server_connection);
 }
 
+/**
+ * gst_validate_issue_from_id:
+ * @issue_id: The issue id
+ *
+ * Returns: (nullable): The issue if found or NULL otherwise
+ */
 GstValidateIssue *
 gst_validate_issue_from_id (GstValidateIssueId issue_id)
 {

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

@@ -139,7 +139,7 @@ gst_validate_reporter_get_reporting_level (GstValidateReporter * reporter)
  * gst_validate_reporter_get_pipeline:
  * @reporter: The reporter to get the pipeline from
  *
- * Returns: (transfer full)(nullable): The #GstPipeline
+ * Returns: (transfer full) (nullable): The #GstPipeline
  */
 GstPipeline *
 gst_validate_reporter_get_pipeline (GstValidateReporter * reporter)
@@ -153,6 +153,13 @@ gst_validate_reporter_get_pipeline (GstValidateReporter * reporter)
   return NULL;
 }
 
+/**
+ * gst_validate_reporter_get_report:
+ * @reporter: The reporter to get the report from
+ * @issue_id: The issue id to get the report from
+ *
+ * Returns: (transfer none) (nullable): The #GstValidateReport
+ */
 GstValidateReport *
 gst_validate_reporter_get_report (GstValidateReporter * reporter,
     GstValidateIssueId issue_id)
@@ -410,9 +417,9 @@ gst_validate_reporter_report_simple (GstValidateReporter * reporter,
 /**
  * gst_validate_reporter_set_name:
  * @reporter: The reporter to set the name on
- * @name: (transfer full): The name of the reporter
+ * @name: (transfer full) (nullable): The name of the reporter
  *
- * Sets @ name on @reporter
+ * Sets @name on @reporter
  */
 void
 gst_validate_reporter_set_name (GstValidateReporter * reporter, gchar * name)
@@ -424,6 +431,14 @@ gst_validate_reporter_set_name (GstValidateReporter * reporter, gchar * name)
   priv->name = name;
 }
 
+/**
+ * gst_validate_reporter_get_name:
+ * @reporter: The reporter to get the name from
+ *
+ * Gets @name of @reporter
+ *
+ * Returns: (transfer none) (nullable): The name of the reporter
+ */
 const gchar *
 gst_validate_reporter_get_name (GstValidateReporter * reporter)
 {
@@ -436,7 +451,7 @@ gst_validate_reporter_get_name (GstValidateReporter * reporter)
  * gst_validate_reporter_get_runner:
  * @reporter: The reporter to get the runner from
  *
- * Returns: (transfer full)(nullable): The runner
+ * Returns: (transfer full) (nullable): The runner
  */
 GstValidateRunner *
 gst_validate_reporter_get_runner (GstValidateReporter * reporter)

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

@@ -324,7 +324,7 @@ gst_validate_scenario_intercept_report (GstValidateReporter * reporter,
  * gst_validate_scenario_get_pipeline:
  * @scenario: The scenario to retrieve a pipeline from
  *
- * Returns: (transfer full): The #GstPipeline the scenario is running
+ * Returns: (transfer full) (nullable): The #GstPipeline the scenario is running
  * against
  */
 GstElement *
@@ -5378,7 +5378,7 @@ gst_validate_scenario_from_structs (GstValidateRunner * runner,
  * @pipeline: The pipeline to run the scenario on
  * @scenario_name: The name (or path) of the scenario to run
  *
- * Returns: (transfer full): A #GstValidateScenario or NULL
+ * Returns: (transfer full) (nullable): A #GstValidateScenario or NULL
  */
 GstValidateScenario *
 gst_validate_scenario_factory_create (GstValidateRunner *
@@ -6375,7 +6375,7 @@ gst_validate_action_set_done (GstValidateAction * action)
  *
  * Retrieve the scenario from which @action is executed.
  *
- * Returns: (transfer full): The scenario from which the action is being executed.
+ * Returns: (transfer full) (nullable): The scenario from which the action is being executed.
  */
 GstValidateScenario *
 gst_validate_action_get_scenario (GstValidateAction * action)