From 97c7fec8be265f9c18e33290cb4b1270b288e51a Mon Sep 17 00:00:00 2001
From: Seungha Yang <seungha@centricular.com>
Date: Thu, 21 Oct 2021 19:04:43 +0900
Subject: [PATCH] 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>
---
 .../docs/gst-hotdoc-plugins-scanner.c         |  4 ++
 subprojects/gstreamer/gst/gstelement.c        |  6 ++
 subprojects/gstreamer/gst/gstelementfactory.c | 55 +++++++++++++++++++
 subprojects/gstreamer/gst/gstelementfactory.h |  6 ++
 4 files changed, 71 insertions(+)

diff --git a/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c b/subprojects/gstreamer/docs/gst-hotdoc-plugins-scanner.c
index f530f860c6..653086a62b 100644
--- 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 7dab1dc9dd..112ee477f0 100644
--- 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 a36a54f3e8..7ce1fca8e7 100644
--- 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 518bb9bec5..07f3f81b22 100644
--- 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 */
 
 /**