gst: Add APIs to allow documentation for element to be skipped

Dynamically registered elements (hardware element in most cases)
may or may not be available on a system and properties may be different
per system.
This new API will make documentation skipping possible in programmable way.

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

diff --git a/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c b/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c
index f530f86..653086a 100644 (file)
--- a/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c
+++ b/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c
@@ -917,6 +917,10 @@ main (int argc, char *argv[])
     for (tmp = features; tmp; tmp = tmp->next) {
       GstPluginFeature *feature = tmp->data;
       if (GST_IS_ELEMENT_FACTORY (feature)) {
+        GstElementFactory *factory = GST_ELEMENT_FACTORY (feature);
+        if (gst_element_factory_get_skip_documentation (factory))
+          continue;
+
         if (!f)
           g_string_append_printf (json, ",");
         _add_element_details (json, other_types, seen_other_types, feature);

diff --git a/subprojects/gstreamer/gst/gstelement.c b/subprojects/gstreamer/gst/gstelement.c
index 7dab1dc..112ee47 100644 (file)
--- a/subprojects/gstreamer/gst/gstelement.c
+++ b/subprojects/gstreamer/gst/gstelement.c
@@ -166,6 +166,10 @@ static GThreadPool *gst_element_pool = NULL;
 /* this is used in gstelementfactory.c:gst_element_register() */
 GQuark __gst_elementclass_factory = 0;
 
+/* used for gst_element_type_set_skip_documentation() and
+ * gst_element_factory_get_skip_documentation() */
+GQuark __gst_elementclass_skip_doc = 0;
+
 GType
 gst_element_get_type (void)
 {
@@ -191,6 +195,8 @@ gst_element_get_type (void)
 
     __gst_elementclass_factory =
         g_quark_from_static_string ("GST_ELEMENTCLASS_FACTORY");
+    __gst_elementclass_skip_doc =
+        g_quark_from_static_string ("GST_ELEMENTCLASS_SKIP_DOCUMENTATION");
     g_once_init_leave (&gst_element_type, _type);
   }
   return gst_element_type;

diff --git a/subprojects/gstreamer/gst/gstelementfactory.c b/subprojects/gstreamer/gst/gstelementfactory.c
index a36a54f..7ce1fca 100644 (file)
--- a/subprojects/gstreamer/gst/gstelementfactory.c
+++ b/subprojects/gstreamer/gst/gstelementfactory.c
@@ -77,6 +77,7 @@ static void gst_element_factory_cleanup (GstElementFactory * factory);
 
 /* this is defined in gstelement.c */
 extern GQuark __gst_elementclass_factory;
+extern GQuark __gst_elementclass_skip_doc;
 
 #define _do_init \
 { \
@@ -327,6 +328,60 @@ detailserror:
   }
 }
 
+/**
+ * gst_element_type_set_skip_documentation:
+ * @type: a #GType of element
+ *
+ * Marks @type as "documentation should be skipped".
+ * Can be useful for dynamically registered element to be excluded from
+ * plugin documentation system.
+ *
+ * Example:
+ * ```c
+ * GType my_type;
+ * GTypeInfo my_type_info;
+ *
+ * // Fill "my_type_info"
+ * ...
+ *
+ * my_type = g_type_register_static (GST_TYPE_MY_ELEMENT, "my-type-name",
+ *    &my_type_info, 0);
+ * gst_element_type_set_skip_documentation (my_type);
+ * gst_element_register (plugin, "my-plugin-feature-name", rank, my_type);
+ * ```
+ *
+ * Since: 1.20
+ */
+void
+gst_element_type_set_skip_documentation (GType type)
+{
+  g_return_if_fail (g_type_is_a (type, GST_TYPE_ELEMENT));
+
+  g_type_set_qdata (type, __gst_elementclass_skip_doc, GINT_TO_POINTER (1));
+}
+
+/**
+ * gst_element_factory_get_skip_documentation:
+ * @factory: a #GstElementFactory to query documentation skip
+ *
+ * Queries whether registered element managed by @factory needs to
+ * be excluded from documentation system or not.
+ *
+ * Returns: %TRUE if documentation should be skipped
+ *
+ * Since: 1.20
+ */
+gboolean
+gst_element_factory_get_skip_documentation (GstElementFactory * factory)
+{
+  g_return_val_if_fail (GST_IS_ELEMENT_FACTORY (factory), TRUE);
+
+  if (g_type_get_qdata (factory->type, __gst_elementclass_skip_doc))
+    return TRUE;
+
+  return FALSE;
+}
+
 static gboolean
 gst_element_factory_property_valist_to_array (const gchar * first,
     va_list properties, GType object_type, guint * n, const gchar ** names[],

diff --git a/subprojects/gstreamer/gst/gstelementfactory.h b/subprojects/gstreamer/gst/gstelementfactory.h
index 518bb9b..07f3f81 100644 (file)
--- a/subprojects/gstreamer/gst/gstelementfactory.h
+++ b/subprojects/gstreamer/gst/gstelementfactory.h
@@ -108,6 +108,12 @@ GST_API
 gboolean                gst_element_register                    (GstPlugin *plugin, const gchar *name,
                                                                  guint rank, GType type);
 
+GST_API
+void                    gst_element_type_set_skip_documentation (GType type);
+
+GST_API
+gboolean                gst_element_factory_get_skip_documentation (GstElementFactory * factory);
+
 /* Factory list functions */
 
 /**