analytics: Add missing documentation

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

girs/GstAnalytics-1.0.gir

@@ -134,6 +134,7 @@ identified by @id is stored.</doc>
         <type name="RelationMeta" c:type="GstAnalyticsRelationMeta*"/>
       </field>
       <method name="get_id" c:identifier="gst_analytics_mtd_get_id" version="1.24">
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">Get instance id</doc>
         <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h"/>
         <return-value transfer-ownership="none">
           <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">Id of @instance</doc>
@@ -141,8 +142,7 @@ identified by @id is stored.</doc>
         </return-value>
         <parameters>
           <instance-parameter name="instance" transfer-ownership="none">
-            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">Instance of #GstAnalyticsMtd
+            <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">Instance of #GstAnalyticsMtd</doc>
-Get instance id</doc>
             <type name="Mtd" c:type="GstAnalyticsMtd*"/>
           </instance-parameter>
         </parameters>
@@ -682,13 +682,12 @@ otherwise this method return FALSE and @rlt is invalid.</doc>
         </parameters>
       </method>
       <method name="get_relation" c:identifier="gst_analytics_relation_meta_get_relation" version="1.24">
-        <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h"/>
+        <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">Get relations between first and second analysis-meta.
-        <return-value transfer-ownership="none">
-          <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">relation description between first and second analysis-meta.
-
-Get relations between first and second analysis-meta.
 Ids (@an_meta_first_id and @an_meta_second_id) must be from a call to
 @gst_analytics_mtd_get_id (handle).</doc>
+        <source-position filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h"/>
+        <return-value transfer-ownership="none">
+          <doc xml:space="preserve" filename="../subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c">relation description between first and second analysis-meta.</doc>
           <type name="RelTypes" c:type="GstAnalyticsRelTypes"/>
         </return-value>
         <parameters>

subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsclassificationmtd.c

@@ -24,6 +24,22 @@
 
 #include "gstanalyticsclassificationmtd.h"
 
+/**
+ * SECTION:gstanalyticsclassificationtd
+ * @title: GstAnalyticsClsMtd
+ * @short_description: An analytics metadata for classification inside a #GstAnalyticsRelationMeta
+ * @symbols:
+ * - GstAnalyticsClsMtd
+ * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta
+ *
+ * This type of metadata holds classification, it is generally used in
+ * relationship with another metadata type to enhance its content. For example,
+ * it can enhance the classifcation of an object detection held by the
+ * #GstAnalyticsODMtd metadata type.
+ *
+ * Since: 1.24
+ */
+
 static const GstAnalyticsMtdImpl cls_impl = {
   "classification",
   NULL

subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c

@@ -26,6 +26,24 @@
 
 #include <gst/video/video.h>
 
+/**
+ * SECTION:gstanalyticsmeta
+ * @title: GstAnalyticsRelationMeta
+ * @short_description: A GstMeta for analytics metadata
+ * @symbols:
+ * - GstAnalyticsRelationMeta
+ * - GstAnalyticsMtd
+ * @see_also: #GstAnalyticsODMtd, #GstAnalyticsClsMtd, #GstAnalyticsTrackingMtd
+ *
+ * The #GstAnalyticsRelationMeta is a #GstMeta that can contain a large number
+ * of results from the analysis of a meta. Each result can be accessed by
+ * using its id, or more conviently, by using a #GstAnalyticsMtd. A matrix
+ * of relationships between the various metadata is also defined and can be
+ * filled by the analysis processes.
+ *
+ * Since: 1.24
+ */
+
 GST_DEBUG_CATEGORY_STATIC (an_relation_meta_debug);
 #define GST_CAT_AN_RELATION an_relation_meta_debug
 

subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h

@@ -30,8 +30,15 @@
 #include <gst/analytics/analytics-meta-prelude.h>
 
 G_BEGIN_DECLS
+
+/**
+ * GST_INF_RELATION_SPAN:
+ * Passes to functions asking for a relation span when the span is
+ * infinite.
+ *
+ * Since: 1.24
+ */
 #define GST_INF_RELATION_SPAN -1
-#define GST_AN_RELATION_META_TAG "GST-ANALYSIS-RELATION-META-TAG"
 typedef struct _GstAnalyticsMtd GstAnalyticsMtd;
 
 /**
@@ -53,9 +60,25 @@ typedef guintptr GstAnalyticsMtdType;
 
 #define GST_ANALYTICS_MTD_TYPE_ANY (0)
 
+/**
+ * GST_ANALYTICS_MTD_CAST: (skip)
+ *
+ * Since: 1.24
+ */
 #define GST_ANALYTICS_MTD_CAST(mtd) \
     ((GstAnalyticsMtd *)(mtd))
 
+/**
+ * GstAnalyticsRelationMeta:
+ *
+ * An opaque #GstMeta that can be used to hold various types of results
+ * from analysis processes.
+ *
+ * The content should be accessed through the API.
+ *
+ * Since: 1.24
+ */
+
 typedef struct _GstAnalyticsRelationMeta GstAnalyticsRelationMeta;
 
 /**
@@ -75,6 +98,19 @@ struct _GstAnalyticsMtd
   GstAnalyticsRelationMeta *meta;
 };
 
+/**
+ * GstAnalyticsMtdImpl:
+ * @name: The name of the metadata type
+ * @mtd_meta_transform: A pointer to a function that will be called
+ * when the containing meta is transform to potentially copy the data
+ * into a new Mtd into the new meta.
+ *
+ * This structure must be provided when registering a new type of Mtd. It must
+ * have a static lifetime (never be freed).
+ *
+ * Since: 1.24
+ */
+
 typedef struct {
   const char *name;
 
@@ -82,6 +118,7 @@ typedef struct {
                                   GstBuffer *buffer, GQuark type,
                                   gpointer data);
 
+  /*< private >*/
   gpointer _reserved[GST_PADDING_LARGE];
 } GstAnalyticsMtdImpl;
 

subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjectdetectionmtd.c

@@ -26,6 +26,20 @@
 
 #include <gst/video/video.h>
 
+/**
+ * SECTION:gstanalyticsobjectdetectionmtd
+ * @title: GstAnalyticsODMtd
+ * @short_description: An analytics metadata for object dection inside a #GstAnalyticsRelationMeta
+ * @symbols:
+ * - GstAnalyticsODMtd
+ * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta
+ *
+ * This type of metadata holds the position of detected object inside the
+ * image, along with the probabily of each detection.
+ *
+ * Since: 1.24
+ */
+
 typedef struct _GstAnalyticsODMtdData GstAnalyticsODMtdData;
 
 /**

subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjecttrackingmtd.c

@@ -24,6 +24,22 @@
 
 #include "gstanalyticsobjecttrackingmtd.h"
 
+/**
+ * SECTION:gstanalyticsobjecttrackingmtd
+ * @title: GstAnalyticsTrackingMtd
+ * @short_description: An analytics metadata for tracking inside a #GstAnalyticsRelationMeta
+ * @symbols:
+ * - GstAnalyticsTrackingMtd
+ * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta
+ *
+ * This type of metadata holds tracking information. In many cases, it is
+ * desired to track an object across many frames. This type of metadata holds
+ * information about the tracking, for example, it can be used alongside a
+ * #GstAnalyticsODMtd to track an object.
+ *
+ * Since: 1.24
+ */
+
 typedef struct _GstAnalyticsTrackingMtdData GstAnalyticsTrackingMtdData;
 
 /**