From 0b51b6b570a0cf675d9f50e55bc390a1b5802be4 Mon Sep 17 00:00:00 2001
From: George Kiagiadakis <george.kiagiadakis@collabora.com>
Date: Fri, 31 May 2024 21:00:07 +0300
Subject: [PATCH] gi: hide WP_PRIVATE_API functions from gir

Document them and annotate them with (skip) so that they are
marked as introspectable=0 in the gir file.

Fixes: #599
---
 docs/gen-api-gtkdoc.py  |  2 ++
 lib/wp/event-hook.c     | 10 ++++++++++
 lib/wp/log.c            |  6 +++++-
 lib/wp/object-manager.c | 33 ++++++++++++++++++++++++++++++---
 4 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/docs/gen-api-gtkdoc.py b/docs/gen-api-gtkdoc.py
index a9a80644..c816ba3a 100644
--- a/docs/gen-api-gtkdoc.py
+++ b/docs/gen-api-gtkdoc.py
@@ -319,6 +319,8 @@ class DoxyFunction(DoxyElement):
             d = normalize_text(d)
 
         e = DoxyFunction(name, d)
+        if (xml.get("prot") == "private"):
+            e.extra = "(skip)"
         e.add_brief(xml.find("briefdescription"))
         e.add_detail(xml.find("detaileddescription"))
         for p in xml.xpath(".//detaileddescription/*/parameterlist[@kind='param']/parameteritem"):
diff --git a/lib/wp/event-hook.c b/lib/wp/event-hook.c
index a35030f8..7d3a9302 100644
--- a/lib/wp/event-hook.c
+++ b/lib/wp/event-hook.c
@@ -184,6 +184,7 @@ wp_event_hook_get_runs_after_hooks (WpEventHook * self)
 /*!
  * \brief Returns the associated event dispatcher
  *
+ * \private
  * \ingroup wpeventhook
  * \param self the event hook
  * \return (transfer full)(nullable): the event dispatcher on which this hook
@@ -197,6 +198,15 @@ wp_event_hook_get_dispatcher (WpEventHook * self)
   return g_weak_ref_get (&priv->dispatcher);
 }
 
+/*!
+ * \brief Sets the associated event dispatcher
+ *
+ * \private
+ * \ingroup wpeventhook
+ * \param self the event hook
+ * \param dispatcher (transfer none): the event dispatcher on which
+ *  this hook is registered
+ */
 void
 wp_event_hook_set_dispatcher (WpEventHook * self, WpEventDispatcher * dispatcher)
 {
diff --git a/lib/wp/log.c b/lib/wp/log.c
index 9f418024..e733aefb 100644
--- a/lib/wp/log.c
+++ b/lib/wp/log.c
@@ -550,7 +550,11 @@ wp_log_set_level (const gchar *level_str)
   return TRUE;
 }
 
-/* private, called from wp_init() */
+/*!
+ * \brief private, called from wp_init()
+ * \ingroup wplog
+ * \private
+ */
 void
 wp_log_init (gint flags)
 {
diff --git a/lib/wp/object-manager.c b/lib/wp/object-manager.c
index aa87694d..9f96480e 100644
--- a/lib/wp/object-manager.c
+++ b/lib/wp/object-manager.c
@@ -672,6 +672,12 @@ idle_emit_objects_changed (WpObjectManager * self)
   return G_SOURCE_REMOVE;
 }
 
+/*!
+ * \brief Checks if the object manager should emit the 'objects-changed' signal
+ * \private
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ */
 void
 wp_object_manager_maybe_objects_changed (WpObjectManager * self)
 {
@@ -724,7 +730,14 @@ wp_object_manager_maybe_objects_changed (WpObjectManager * self)
   }
 }
 
-/* caller must also call wp_object_manager_maybe_objects_changed() after */
+/*!
+ * \brief Adds an object to the object manager.
+ * \private
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param object (transfer none): the object to add
+ * \note caller must also call wp_object_manager_maybe_objects_changed() after
+ */
 void
 wp_object_manager_add_object (WpObjectManager * self, gpointer object)
 {
@@ -736,7 +749,14 @@ wp_object_manager_add_object (WpObjectManager * self, gpointer object)
   }
 }
 
-/* caller must also call wp_object_manager_maybe_objects_changed() after */
+/*!
+ * \brief Removes an object from the object manager.
+ * \private
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param object the object to remove
+ * \note caller must also call wp_object_manager_maybe_objects_changed() after
+ */
 void
 wp_object_manager_rm_object (WpObjectManager * self, gpointer object)
 {
@@ -765,7 +785,14 @@ on_proxy_ready (GObject * proxy, GAsyncResult * res, gpointer data)
   wp_object_manager_maybe_objects_changed (self);
 }
 
-/* caller must also call wp_object_manager_maybe_objects_changed() after */
+/*!
+ * \brief Adds a global object to the object manager.
+ * \private
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param global the global object to add
+ * \note caller must also call wp_object_manager_maybe_objects_changed() after
+ */
 void
 wp_object_manager_add_global (WpObjectManager * self, WpGlobal * global)
 {