utils: Add helper function for marking types as plugin API

This can be used to mark additional types exposed by plugins (i.e.
enums, flags and GObjects) via properties, signals or pad templates as
plugin API. They can then be picked up by the documentation for the
plugin.

Not all types exposed by plugins are documented automatically because
they might come from an external library and should be documented from
there instead.

gst/gstquark.c

@@ -79,7 +79,7 @@ static const gchar *_quark_strings[] = {
   "GstMessageDeviceChanged", "device-changed", "trickmode-interval",
   "GstEventInstantRateChange",
   "GstEventInstantRateSyncTime", "GstMessageInstantRateRequest",
-  "upstream-running-time", "base", "offset",
+  "upstream-running-time", "base", "offset", "plugin-api"
 };
 
 GQuark _priv_gst_quark_table[GST_QUARK_MAX];

gst/gstquark.h

@@ -228,7 +228,8 @@ typedef enum _GstQuarkId
   GST_QUARK_UPSTREAM_RUNNING_TIME = 197,
   GST_QUARK_BASE = 198,
   GST_QUARK_OFFSET = 199,
-  GST_QUARK_MAX = 200
+  GST_QUARK_PLUGIN_API = 200,
+  GST_QUARK_MAX = 201
 } GstQuarkId;
 
 extern GQuark _priv_gst_quark_table[GST_QUARK_MAX];

gst/gstutils.c

@@ -44,6 +44,7 @@
 #include "gstinfo.h"
 #include "gstparse.h"
 #include "gstvalue.h"
+#include "gstquark.h"
 #include "gst-i18n-lib.h"
 #include "glib-compat-private.h"
 #include <math.h>
@@ -4516,3 +4517,43 @@ invalid:
     return FALSE;
   }
 }
+
+/**
+ * gst_type_mark_as_plugin_api:
+ * @type: a GType
+ *
+ * Marks @type as plugin API. This should be called in `class_init` of
+ * elements that expose new types (i.e. enums, flags or internal GObjects) via
+ * properties, signals or pad templates.
+ *
+ * Types exposed by plugins are not automatically added to the documentation
+ * as they might originate from another library and should in that case be
+ * documented via that library instead.
+ *
+ * By marking a type as plugin API it will be included in the documentation of
+ * the plugin that defines it.
+ *
+ * Since: 1.18
+ */
+void
+gst_type_mark_as_plugin_api (GType type)
+{
+  g_type_set_qdata (type, GST_QUARK (PLUGIN_API), GINT_TO_POINTER (TRUE));
+}
+
+/**
+ * gst_type_is_plugin_api:
+ * @type: a GType
+ *
+ * Checks if @type is plugin API. See gst_type_mark_as_plugin_api() for
+ * details.
+ *
+ * Returns: %TRUE if @type is plugin API or %FALSE otherwise.
+ *
+ * Since: 1.18
+ */
+gboolean
+gst_type_is_plugin_api (GType type)
+{
+  return ! !GPOINTER_TO_INT (g_type_get_qdata (type, GST_QUARK (PLUGIN_API)));
+}

gst/gstutils.h

@@ -1204,6 +1204,11 @@ gboolean      gst_calculate_linear_regression   (const GstClockTime * xy,
                                                  GstClockTime * b, GstClockTime * xbase,
                                                  gdouble * r_squared);
 
+GST_API
+void          gst_type_mark_as_plugin_api       (GType type);
+
+GST_API
+gboolean      gst_type_is_plugin_api            (GType type);
 
 G_END_DECLS