docs: fix C API documentation to work nicely with doxygen & sphinx

docs/Doxyfile.in

@@ -269,10 +269,12 @@ TAB_SIZE               = 8
 # commands \{ and \} for these it is advised to use the version @{ and @} or use
 # a double escape (\\{ and \\})
 
-ALIASES                = "rst=\verbatim embed:rst:leading-asterisk" \
+ALIASES                = \
-                         endrst=\endverbatim \
+  "rst=\verbatim embed:rst:leading-asterisk" \
-                         "signal=\xrefitem signal \"Signal\" \"Signals\"" \
+  "endrst=\endverbatim" \
-                         "props=\xrefitem props \"Property\" \"Properties\""
+  "gsignals=\b GObject \b Signals" \
+  "gproperties=\b GObject \b Properties" \
+  "gproperty{4}=<dl><dt>\1</dt><dd><p>\4</p><table><tr><td>`\2`</td><td>`\3`</td></tr></table></dd></dl>"
 
 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
 # only. Doxygen will then generate output that is more tailored for C. For
@@ -280,7 +282,7 @@ ALIASES                = "rst=\verbatim embed:rst:leading-asterisk" \
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_FOR_C  = NO
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -938,15 +940,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        = G_DEFINE_TYPE_WITH_CODE \
+EXCLUDE_SYMBOLS        =
-                         G_DEFINE_QUARK \
-                         G_DEFINE_TYPE_WITH_PRIVATE \
-                         G_DEFINE_ABSTRACT_TYPE \
-                         G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE \
-                         G_DECLARE_DERIVABLE_TYPE \
-                         G_DECLARE_FINAL_TYPE \
-                         G_DECLARE_INTERFACE \
-                         G_LOG_*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2230,6 +2224,18 @@ PREDEFINED             = DOXYGEN_DOCUMENTATION_BUILD \
                          WP_PLUGIN_EXPORT= \
                          G_GNUC_CONST= \
                          G_GNUC_PRINTF(...)= \
+                         G_GNUC_NULL_TERMINATED= \
+                         G_DEFINE_TYPE_WITH_CODE(...)= \
+                         G_DEFINE_ABSTRACT_TYPE(...)= \
+                         G_DEFINE_TYPE(...)= \
+                         G_DEFINE_BOXED_TYPE(...)= \
+                         G_DEFINE_INTERFACE(...)= \
+                         G_DEFINE_QUARK(...)= \
+                         G_DEFINE_TYPE_WITH_PRIVATE(...)= \
+                         G_DEFINE_AUTOPTR_CLEANUP_FUNC(...)= \
+                         G_DECLARE_FINAL_TYPE(...)= \
+                         G_DECLARE_DERIVABLE_TYPE(...)= \
+                         G_DECLARE_INTERFACE(...)= \
                          GQuark=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
@@ -2239,15 +2245,7 @@ PREDEFINED             = DOXYGEN_DOCUMENTATION_BUILD \
 # definition found in the source code.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_AS_DEFINED      = WP_PRIVATE_API \
+EXPAND_AS_DEFINED      =
-                         WP_API \
-                         WP_PLUGIN_EXPORT \
-                         G_BEGIN_DECLS \
-                         G_END_DECLS \
-                         G_IMPLEMENT_INTERFACE \
-                         G_GNUC_CONST \
-                         G_GNUC_PRINTF \
-                         GQuark
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES then doxygen's preprocessor will
 # remove all references to function-like macros that are alone on a line, have

docs/rst/c_api.rst

@@ -1,35 +1,38 @@
  .. _library_root:
 
 C API Documentation
-=================
+===================
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
 
-   c_api/client_api.rst
+   c_api/wp_api.rst
-   c_api/components_api.rst
    c_api/core_api.rst
-   c_api/device_api.rst
-   c_api/endpoint_api.rst
-   c_api/global_proxy_api.rst
-   c_api/iterator_api.rst
-   c_api/link_api.rst
-   c_api/metadata_api.rst
-   c_api/node_api.rst
-   c_api/obj_interest_api.rst
-   c_api/obj_manager_api.rst
    c_api/object_api.rst
-   c_api/plugin_api.rst
+   c_api/obj_manager_api.rst
-   c_api/port_api.rst
+   c_api/obj_interest_api.rst
-   c_api/properties_api.rst
+   c_api/iterator_api.rst
-   c_api/proxy_interfaces_api.rst
-   c_api/proxy_api.rst
-   c_api/session_item_api.rst
-   c_api/si_factory_api.rst
-   c_api/si_interfaces_api.rst
-   c_api/state_api.rst
    c_api/transitions_api.rst
+   c_api/wperror_api.rst
+   c_api/log_api.rst
+   c_api/proxy_api.rst
+   c_api/pipewire_object_api.rst
+   c_api/global_proxy_api.rst
+   c_api/node_api.rst
+   c_api/port_api.rst
+   c_api/link_api.rst
+   c_api/device_api.rst
+   c_api/client_api.rst
+   c_api/metadata_api.rst
+   c_api/endpoint_api.rst
+   c_api/spa_device_api.rst
+   c_api/impl_node_api.rst
+   c_api/properties_api.rst
    c_api/spa_type_api.rst
    c_api/spa_pod_api.rst
-   c_api/wp_api.rst
+   c_api/plugin_api.rst
+   c_api/component_loader_api.rst
+   c_api/session_item_api.rst
+   c_api/si_interfaces_api.rst
+   c_api/si_factory_api.rst
+   c_api/state_api.rst

docs/rst/c_api/client_api.rst

@@ -1,7 +1,23 @@
 .. _client_api:
 
-Pipewire Client
+PipeWire Client
 ===============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpClient;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpClient;
+   }
+
 .. doxygenstruct:: WpClient
    :project: WirePlumber
-   :members:
+
+.. doxygengroup:: wpclient
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/component_loader_api.rst

@@ -0,0 +1,23 @@
+.. _component_loader_api:
+
+Component Loader
+================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpPlugin;
+      WpPlugin -> WpComponentLoader;
+   }
+
+.. doxygenstruct:: WpComponentLoader
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpComponentLoaderClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpcomponentloader
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/components_api.rst

@@ -1,7 +0,0 @@
-.. _components_api:
-
-Pipewire Components
-===================
-.. doxygenstruct:: WpComponentLoader
-   :project: WirePlumber
-   :members:

docs/rst/c_api/core_api.rst

@@ -1,7 +1,18 @@
 .. _core_api:
 
-Pipewire Core
+Core
-=============
+====
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpCore;
+   }
+
 .. doxygenstruct:: WpCore
    :project: WirePlumber
-   :members:
+
+.. doxygengroup:: wpcore
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/device_api.rst

@@ -1,7 +1,23 @@
 .. _device_api:
 
-Pipewire Device
+PipeWire Device
 ===============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpDevice;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpDevice;
+   }
+
 .. doxygenstruct:: WpDevice
    :project: WirePlumber
-   :members:
+
+.. doxygengroup:: wpdevice
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/endpoint_api.rst

@@ -1,6 +1,27 @@
 .. _endpoint_api:
 
-Pipewire Endpoint
+PipeWire Endpoint
 =================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpEndpoint;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpEndpoint;
+      WpEndpoint -> WpImplEndpoint;
+   }
+
 .. doxygenstruct:: WpEndpoint
    :project: WirePlumber
+
+.. doxygenstruct:: WpImplEndpoint
+   :project: WirePlumber
+
+.. doxygengroup:: wpendpoint
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/global_proxy_api.rst

@@ -1,6 +1,23 @@
 .. _global_proxy_api:
 
-Pipewire Global Object Proxy
+PipeWire Global Object Proxy
 ============================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+   }
+
 .. doxygenstruct:: WpGlobalProxy
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpGlobalProxyClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpglobalproxy
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/impl_node_api.rst

@@ -0,0 +1,23 @@
+.. _impl_node_api:
+
+Local Nodes
+===========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpImplNode;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpImplNode;
+   }
+
+.. doxygenstruct:: WpImplNode
+   :project: WirePlumber
+   :members:
+
+.. doxygengroup:: wpimplnode
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/iterator_api.rst

@@ -2,5 +2,20 @@
 
 Iterator
 ========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GBoxed -> WpIterator;
+   }
+
 .. doxygenstruct:: WpIterator
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpIteratorMethods
+   :project: WirePlumber
+
+.. doxygengroup:: wpiterator
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/link_api.rst

@@ -1,6 +1,23 @@
 .. _link_api:
 
-Pipewire Link
+PipeWire Link
 =============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpLink;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpLink;
+   }
+
 .. doxygenstruct:: WpLink
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wplink
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/log_api.rst

@@ -0,0 +1,7 @@
+.. _log_api:
+
+Debug Logging
+=============
+.. doxygengroup:: wplog
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/meson.build

@@ -1,29 +1,33 @@
 # you need to add here any files you add to the api directory as well
 sphinx_files += files(
   'client_api.rst',
-  'components_api.rst',
+  'component_loader_api.rst',
   'core_api.rst',
   'device_api.rst',
   'endpoint_api.rst',
   'global_proxy_api.rst',
+  'impl_node_api.rst',
   'iterator_api.rst',
   'link_api.rst',
+  'log_api.rst',
   'metadata_api.rst',
   'node_api.rst',
   'obj_interest_api.rst',
   'obj_manager_api.rst',
   'object_api.rst',
+  'pipewire_object_api.rst',
   'plugin_api.rst',
   'port_api.rst',
   'properties_api.rst',
-  'proxy_interfaces_api.rst',
   'proxy_api.rst',
   'session_item_api.rst',
   'si_factory_api.rst',
   'si_interfaces_api.rst',
+  'spa_device_api.rst',
+  'spa_pod_api.rst',
+  'spa_type_api.rst',
   'state_api.rst',
   'transitions_api.rst',
-  'spa_type_api.rst',
+  'wp_api.rst',
-  'spa_pod_api.rst',
+  'wperror_api.rst',
-  'wp_api.rst'
 )

docs/rst/c_api/metadata_api.rst

@@ -2,10 +2,24 @@
 
 PipeWire Metadata
 =================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpMetadata;
+      WpMetadata-> WpImplMetadata;
+   }
+
 .. doxygenstruct:: WpMetadata
    :project: WirePlumber
-   :members:
 
 .. doxygenstruct:: WpImplMetadata
    :project: WirePlumber
-   :members:
+
+.. doxygengroup:: wpmetadata
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/node_api.rst

@@ -2,10 +2,22 @@
 
 PipeWire Node
 =============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpNode;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpNode;
+   }
+
 .. doxygenstruct:: WpNode
    :project: WirePlumber
-   :members:
 
-.. doxygenstruct:: WpImplNode
+.. doxygengroup:: wpnode
    :project: WirePlumber
-   :members:
+   :content-only:

docs/rst/c_api/obj_interest_api.rst

@@ -2,5 +2,17 @@
 
 Object Interest
 ===============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GBoxed -> WpObjectInterest;
+   }
+
 .. doxygenstruct:: WpObjectInterest
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wpobjectinterest
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/obj_manager_api.rst

@@ -2,5 +2,17 @@
 
 Object Manager
 ==============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObjectManager;
+   }
+
 .. doxygenstruct:: WpObjectManager
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wpobjectmanager
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/object_api.rst

@@ -1,6 +1,21 @@
 .. _object_api:
 
-Base Object Type
+WpObject
-================
+========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+   }
+
 .. doxygenstruct:: WpObject
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpObjectClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpobject
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/pipewire_object_api.rst

@@ -0,0 +1,21 @@
+.. _pipewire_object_api:
+
+PipeWire Object
+===============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GInterface -> WpPipewireObject;
+   }
+
+.. doxygenstruct:: WpPipewireObject
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpPipewireObjectInterface
+   :project: WirePlumber
+
+.. doxygengroup:: wppipewireobject
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/plugin_api.rst

@@ -1,6 +1,22 @@
 .. _plugin_api:
 
-Wireplumber Daemon Plugins
+Plugins
-==========================
+=======
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpPlugin;
+   }
+
 .. doxygenstruct:: WpPlugin
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpPluginClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpplugin
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/port_api.rst

@@ -2,5 +2,22 @@
 
 PipeWire Port
 =============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpGlobalProxy;
+      WpGlobalProxy -> WpPort;
+      GInterface -> WpPipewireObject;
+      WpPipewireObject -> WpPort;
+   }
+
 .. doxygenstruct:: WpPort
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wpport
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/properties_api.rst

@@ -1,6 +1,18 @@
 .. _properties_api:
 
-PipeWire Properties Dictionary
+Properties Dictionary
-==============================
+=====================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GBoxed -> WpProperties;
+   }
+
 .. doxygenstruct:: WpProperties
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wpproperties
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/proxy_api.rst

@@ -1,6 +1,22 @@
 .. _proxy_api:
 
-PipeWire Object Proxy
+PipeWire Proxy
-=====================
+==============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+   }
+
 .. doxygenstruct:: WpProxy
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpProxyClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpproxy
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/proxy_interfaces_api.rst

@@ -1,6 +0,0 @@
-.. _proxy_interfaces_api:
-
-PipeWire Object Proxy Interfaces
-================================
-.. doxygenstruct:: WpPipewireObject
-   :project: WirePlumber

docs/rst/c_api/session_item_api.rst

@@ -2,5 +2,21 @@
 
 Session Items
 =============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpSessionItem;
+   }
+
 .. doxygenstruct:: WpSessionItem
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSessionItemClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpsessionitem
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/si_factory_api.rst

@@ -2,5 +2,20 @@
 
 Session Items Factory
 =====================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpSiFactory;
+   }
+
 .. doxygenstruct:: WpSiFactory
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiFactoryClass
+   :project: WirePlumber
+
+.. doxygengroup:: wpsifactory
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/si_interfaces_api.rst

@@ -2,8 +2,48 @@
 
 Session Items Interfaces
 ========================
-.. doxygenstruct:: WpSiAcquisition
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GInterface -> WpSiEndpoint;
+      GInterface -> WpSiAdapter;
+      GInterface -> WpSiLinkable;
+      GInterface -> WpSiLink;
+      GInterface -> WpSiAcquisition;
+   }
+
 .. doxygenstruct:: WpSiEndpoint
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiEndpointInterface
+   :project: WirePlumber
+
+.. doxygenstruct:: WpSiAdapter
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiAdapterInterface
+   :project: WirePlumber
+
+.. doxygenstruct:: WpSiLinkable
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiLinkableInterface
+   :project: WirePlumber
+
 .. doxygenstruct:: WpSiLink
-.. doxygenstruct:: WpSiPortInfo
+   :project: WirePlumber
-   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiLinkInterface
+   :project: WirePlumber
+
+.. doxygenstruct:: WpSiAcquisition
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpSiAcquisitionInterface
+   :project: WirePlumber
+
+.. doxygengroup:: wpsiinterfaces
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/spa_device_api.rst

@@ -0,0 +1,20 @@
+.. _spa_device_api:
+
+Spa Device
+==========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpObject;
+      WpObject -> WpProxy;
+      WpProxy -> WpSpaDevice;
+   }
+
+.. doxygenstruct:: WpSpaDevice
+   :project: WirePlumber
+
+.. doxygengroup:: wpspadevice
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/spa_pod_api.rst

@@ -2,5 +2,25 @@
 
 Spa Pod (Plain Old Data)
 ========================
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GBoxed -> WpSpaPod;
+      GBoxed -> WpSpaPodBuilder;
+      GBoxed -> WpSpaPodParser;
+   }
+
 .. doxygenstruct:: WpSpaPod
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: WpSpaPodBuilder
+   :project: WirePlumber
+
+.. doxygenstruct:: WpSpaPodParser
+   :project: WirePlumber
+
+.. doxygengroup:: wpspapod
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/spa_type_api.rst

@@ -2,5 +2,5 @@
 
 Spa Type Information
 ====================
-.. doxygenstruct:: WpSpaType
+.. doxygengroup:: wpspatype
-   :project: WirePlumber
+   :project: WirePlumber

docs/rst/c_api/state_api.rst

@@ -2,5 +2,17 @@
 
 State Storage
 =============
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpState;
+   }
+
 .. doxygenstruct:: WpState
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygengroup:: wpstate
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/transitions_api.rst

@@ -2,5 +2,30 @@
 
 Transitions
 ===========
+.. graphviz::
+  :align: center
+
+   digraph inheritance {
+      rankdir=LR;
+      GObject -> WpTransition;
+      GInterface -> GAsyncResult;
+      GAsyncResult -> WpTransition;
+      WpTransition -> WpFeatureActivationTransition;
+   }
+
 .. doxygenstruct:: WpTransition
-   :project: WirePlumber
+   :project: WirePlumber
+
+.. doxygenstruct:: _WpTransitionClass
+   :project: WirePlumber
+
+.. doxygengroup:: wptransition
+   :project: WirePlumber
+   :content-only:
+
+.. doxygenstruct:: WpFeatureActivationTransition
+   :project: WirePlumber
+
+.. doxygengroup:: wpfeatureactivationtransition
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/wp_api.rst

@@ -2,5 +2,6 @@
 
 Library Initialization
 ======================
-.. doxygenstruct:: Wp
+.. doxygengroup:: wp
-   :project: WirePlumber
+   :project: WirePlumber
+   :content-only:

docs/rst/c_api/wperror_api.rst

@@ -0,0 +1,7 @@
+.. _wperror_api:
+
+Error Codes
+===========
+.. doxygengroup:: wperror
+   :project: WirePlumber
+   :content-only:

docs/rst/index.rst

@@ -1,56 +1,47 @@
 Wireplumber
 ===========
 
-WirePlumber is a modular session / policy manager for `PipeWire <https://pipewire.org>`_ and a GObject-based high-level library that wraps PipeWire's API, providing convenience for writing the daemon's modules as well as external tools for managing PipeWire.
+WirePlumber is a modular session / policy manager for
+`PipeWire <https://pipewire.org>`_ and a GObject-based high-level library
+that wraps PipeWire's API, providing convenience for writing the daemon's
+modules as well as external tools for managing PipeWire.
+
+
+The WirePlumber Daemon
+----------------------
+
+The WirePlumber daemon implements the session & policy management service.
+It follows a modular design, having plugins that implement the actual
+management functionality.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    installing-wireplumber.rst
    running-wireplumber-daemon.rst
    daemon-configuration.rst
    daemon-logging.rst
-   contributing.rst
-   community.rst
-   testing.rst
-   c_api.rst
-   lua_api.rst
-
-The WirePlumber Daemon
-----------------------
-
-The WirePlumber daemon implements the session & policy management service. It follows a modular design, having plugins that implement the actual management functionality.
-
-* :ref:`running-wireplumber-daemon`
-* :ref:`daemon-configuration`
-* :ref:`logging`
 
 The WirePlumber library
 -----------------------
 
-The WirePlumber Library provides API that allows you to extend the WirePlumber daemon, to write management or status tools for PipeWire (apps that don't do actual media streaming) and to write custom session managers for embedded devices.
+The WirePlumber Library provides API that allows you to extend the WirePlumber
+daemon, to write management or status tools for PipeWire
+(apps that don't do actual media streaming) and to write custom session managers
+for embedded devices.
+
+.. toctree::
+   :maxdepth: 2
+
+   c_api.rst
+   lua_api.rst
 
 Resources
 ---------
 
-* :ref:`contributing`
+.. toctree::
-* :ref:`testing`
+   :maxdepth: 2
-* :ref:`community`
 
-Subpages
+   contributing.rst
---------
+   community.rst
-
+   testing.rst
-* :ref:`installing-wireplumber`
-* :ref:`running-wireplumber-daemon`
-* :ref:`daemon-configuration`
-* :ref:`lua_api`
-* :ref:`contributing`
-* :ref:`testing`
-* :ref:`community`
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`

lib/wp/client.c

@@ -11,28 +11,16 @@
 #include "client.h"
 #include "private/pipewire-object-mixin.h"
 
+/*! \defgroup wpclient WpClient */
 /*!
- * @file client.c
+ * \struct WpClient
- */
-
-/*!
- * @section client_section Pipewire Client
  *
- * @struct WpClient
+ * The WpClient class allows accessing the properties and methods of a PipeWire
- *
+ * client object (`struct pw_client`). A WpClient is constructed internally
- * @brief
- *
- * The [WpClient](@ref client_section) class allows accessing the properties and methods of a PipeWire
- * client object (`struct pw_client`). A [WpClient](@ref client_section) is constructed internally
  * when a new client connects to PipeWire and it is made available through the
- * [WpObjectManager](@ref object_manager_section) API.
+ * WpObjectManager API.
- *
  */
 
-/*!
- * @brief
- * @em parent
- */
 struct _WpClient
 {
   WpGlobalProxy parent;
@@ -123,18 +111,17 @@ wp_client_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpClient
+ * \brief Update client's permissions on a list of objects.
  *
- * @param self: the client
+ * An object id of `-1` can be used to set the default object permissions
- * @param n_perm: the number of permissions specified in the variable arguments
+ * for this client
- * @...: @em n_perm pairs of
+ *
- * <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint32">
+ * \ingroup wpclient
- * guint32</a> numbers; the first number is the object id
+ * \param self the client
- *   and the second is the permissions that this client should have
+ * \param n_perm the number of permissions specified in the variable arguments
+ * \param ... \a n_perm pairs of guint32 numbers; the first number is the
+ *   object id and the second is the permissions that this client should have
  *   on this object
- *
- * @brief Update client's permissions on a list of objects. An object id of `-1`
- * can be used to set the default object permissions for this client
  */
 void
 wp_client_update_permissions (WpClient * self, guint n_perm, ...)
@@ -154,16 +141,16 @@ wp_client_update_permissions (WpClient * self, guint n_perm, ...)
 }
 
 /*!
- * @memberof WpClient
+ * \brief Update client's permissions on a list of objects.
  *
- * @param self: the client
+ * An object id of `-1` can be used to set the default object permissions
- * @param n_perm: the number of permissions specified in the @em permissions array
+ * for this client
- * @param permissions: (array length=n_perm) (element-type pw_permission): an array
+ *
+ * \ingroup wpclient
+ * \param self the client
+ * \param n_perm the number of permissions specified in the \a permissions array
+ * \param permissions (array length=n_perm) (element-type pw_permission): an array
  *    of permissions per object id
- *
- * @brief Update client's permissions on a list of objects. An object id of `-1`
- * can be used to set the default object permissions for this client
- *
  */
 void
 wp_client_update_permissions_array (WpClient * self,
@@ -180,4 +167,4 @@ wp_client_update_permissions_array (WpClient * self,
   client_update_permissions_result = pw_client_update_permissions (
       pwp, n_perm, permissions);
   g_warn_if_fail (client_update_permissions_result >= 0);
-}
+}

lib/wp/client.h

@@ -16,15 +16,8 @@ G_BEGIN_DECLS
 struct pw_permission;
 
 /*!
- * @memberof WpClient
+ * \brief The WpClient GType
- *
+ * \ingroup wpclient
- * @brief The [WpClient](@ref client_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_CLIENT (wp_client_get_type ())
- * @endcode
  */
 #define WP_TYPE_CLIENT (wp_client_get_type ())
 WP_API

lib/wp/component-loader.c

@@ -6,16 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file component-loader.c
- */
-
-/*!
- * @struct WpComponentLoader
- * @section component_loader_section Components
- */
-
-
 #define G_LOG_DOMAIN "wp-comp-loader"
 
 #include "component-loader.h"
@@ -23,6 +13,24 @@
 #include "private/registry.h"
 #include <pipewire/impl.h>
 
+/*! \defgroup wpcomponentloader WpComponentLoader */
+/*!
+ * \struct WpComponentLoader
+ *
+ * The component loader is a plugin that provides the ability to load components.
+ *
+ * Components can be:
+ *  - WirePlumber modules (libraries that provide WpPlugin and WpSiFactory objects)
+ *  - PipeWire modules (libraries that extend libpipewire)
+ *  - Scripts (ex. lua scripts)
+ *  - Configuration files
+ *
+ * The WirePlumber library provides built-in support for loading WirePlumber
+ * and PipeWire modules, without a component loader. For other kinds of
+ * components, like the lua scripts and config files, a component loader is
+ * provided in by external WirePlumber module.
+ */
+
 #define WP_MODULE_INIT_SYMBOL "wireplumber__module_init"
 typedef gboolean (*WpModuleInitFunc) (WpCore *, GVariant *, GError **);
 
@@ -119,17 +127,22 @@ wp_component_loader_load (WpComponentLoader * self, const gchar * component,
 }
 
 /*!
- * @memberof WpCore
+ * \brief Loads the specified \a component on \a self
- * @param self: the core
- * @param component: the module name or file name
- * @param type: the type of the component
- * @param args (transfer floating)(nullable): additional arguments for the component,
- *   usually a dict or a string
- * @param error: (out) (optional): return location for errors, or NULL to ignore
  *
- * @returns %TRUE if loaded, %FALSE if there was an error
+ * The \a type will determine which component loader to use. The following types
+ * are built-in and will always work without a component loader:
+ *  - "module" - Loads a WirePlumber module
+ *  - "pw_module" - Loads a PipeWire module
+ *
+ * \ingroup wpcomponentloader
+ * \param self the core
+ * \param component the module name or file name
+ * \param type the type of the component
+ * \param args (transfer floating)(nullable): additional arguments for the component,
+ *   usually a dict or a string
+ * \param error (out) (optional): return location for errors, or NULL to ignore
+ * \returns TRUE if loaded, FALSE if there was an error
  */
-
 gboolean
 wp_core_load_component (WpCore * self, const gchar * component,
     const gchar * type, GVariant * args, GError ** error)

lib/wp/component-loader.h

@@ -14,25 +14,14 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpComponentLoader
+ * \brief The WpComponentLoader GType
- *
+ * \ingroup wpcomponentloader
- * @brief The [WpComponentLoader](@ref component_loader_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_COMPONENT_LOADER (wp_component_loader_get_type ())
- * @endcode
  */
 #define WP_TYPE_COMPONENT_LOADER (wp_component_loader_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpComponentLoader, wp_component_loader,
                           WP, COMPONENT_LOADER, WpPlugin)
 
-/*!
- * @brief
- * @em parent_class
- */
 struct _WpComponentLoaderClass
 {
   WpPluginClass parent_class;

lib/wp/core.c

@@ -6,9 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file core.c
- */
 #define G_LOG_DOMAIN "wp-core"
 
 #include "core.h"
@@ -79,13 +76,12 @@ wp_loop_source_new (void)
   return (GSource *) s;
 }
 
+/*! \defgroup wpcore WpCore */
 /*!
- * @struct WpCore
+ * \struct WpCore
  *
- * @section core_section Core
+ * The core is the central object around which everything operates. It is
- *
+ * essential to create a WpCore before using any other WirePlumber API.
- * @brief The core is the central object around which everything operates. It is
- * essential to create a [WpCore](@ref core_section) before using any other WirePlumber API.
  *
  * The core object has the following responsibilities:
  *  * it initializes the PipeWire library
@@ -96,8 +92,43 @@ wp_loop_source_new (void)
  *    to keep objects loaded permanently into memory
  *  * it watches the PipeWire registry and keeps track of remote and local
  *    objects that appear in the registry, making them accessible through
- *    the [WpObjectManager](@ref object_manager_section) API.
+ *    the WpObjectManager API.
  *
+ * \gproperties
+ *
+ * \gproperty{g-main-context, GMainContext *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   A GMainContext to attach to}
+ *
+ * \gproperty{properties, WpProperties *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The pipewire properties of the pw_core}
+ *
+ * \gproperty{pw-context, gpointer (struct pw_context *), G_PARAM_READABLE,
+ *   The pipewire context}
+ *
+ * \gproperty{pw-core, gpointer (struct pw_core *), G_PARAM_READABLE,
+ *   The pipewire core}
+ *
+ * \gsignals
+ *
+ * \par connected
+ * \parblock
+ * \code
+ * void
+ * connected_callback (WpCore * self,
+ *                     gpointer user_data)
+ * \endcode
+ * Emitted when the core is successfully connected to the PipeWire server
+ * \endparblock
+ *
+ * \par disconnected
+ * \parblock
+ * \code
+ * void
+ * disconnected_callback (WpCore * self,
+ *                        gpointer user_data)
+ * \endcode
+ * Emitted when the core is disconnected from the PipeWire server
+ * \endparblock
  */
 struct _WpCore
 {
@@ -122,41 +153,6 @@ struct _WpCore
   GHashTable *async_tasks; // <int seq, GTask*>
 };
 
-/*!
- * @memberof WpCore
- *
- * @props @b g-main-context
- *
- * @code
- * "g-main-context" GMainContext *
- * @endcode
- *
- * Flags : Read / Write / Construct Only
- *
- * @props @b properties
- *
- * @code
- * "properties" WpProperties *
- * @endcode
- *
- * Flags : Read / Write / Construct Only
- *
- * @props @b pw-context
- *
- * @code
- * "pw-context" gpointer *
- * @endcode
- *
- * Flags : Read
- *
- * @props @b pw-core
- *
- * @code
- * "pw-core" gpointer *
- * @endcode
- *
- * Flags : Read
- */
 enum {
   PROP_0,
   PROP_G_MAIN_CONTEXT,
@@ -165,33 +161,6 @@ enum {
   PROP_PW_CORE,
 };
 
-/*!
- * @memberof WpCore
- *
- * @signal @b connected
- *
- * Params:
- * @arg @c self: the core
- *
- * Emitted when the core is successfully connected to the PipeWire server
- * @code
- * connected_callback (WpCore * self,
- *                     gpointer user_data)
- * @endcode
- *
- *
- * @signal @b disconnected
- *
- * Params:
- * @arg @c self: the core
- *
- * Emitted when the core is disconnected from the PipeWire server
- * @code
- * disconnected_callback (WpCore * self,
- *                        gpointer user_data)
- * @endcode
- *
- */
 enum {
   SIGNAL_CONNECTED,
   SIGNAL_DISCONNECTED,
@@ -200,7 +169,6 @@ enum {
 
 static guint32 signals[NUM_SIGNALS];
 
-
 G_DEFINE_TYPE (WpCore, wp_core, G_TYPE_OBJECT)
 
 static void
@@ -446,39 +414,21 @@ wp_core_class_init (WpCoreClass * klass)
       g_param_spec_pointer ("pw-core", "pw-core", "The pipewire core",
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpCore::connected:
-   *
-   * @self: the core
-   *
-   * Emitted when the core is successfully connected to the PipeWire server
-   */
   signals[SIGNAL_CONNECTED] = g_signal_new ("connected",
       G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL,
       G_TYPE_NONE, 0);
 
-  /*
-   * WpCore::disconnected:
-   *
-   * @self: the core
-   *
-   * Emitted when the core is disconnected from the PipeWire server
-   */
   signals[SIGNAL_DISCONNECTED] = g_signal_new ("disconnected",
       G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL,
       G_TYPE_NONE, 0);
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- *
+ * \param context (transfer none) (nullable): the GMainContext to use for events
- * @param context: (transfer none) (nullable): the
+ * \param properties (transfer full) (nullable): additional properties, which are
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
+ *   passed to pw_context_new() and pw_context_connect()
- * GMainContext</a> to use for events
+ * \returns (transfer full): a new WpCore
- * @param properties: (transfer full) (nullable): additional properties, which are
- *   passed to `pw_context_new` and `pw_context_connect`
- *
- * @returns (transfer full): a new [WpCore](@ref core_section)
  */
 WpCore *
 wp_core_new (GMainContext *context, WpProperties * properties)
@@ -492,12 +442,11 @@ wp_core_new (GMainContext *context, WpProperties * properties)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Clones a core with the same context as \a self
- * @param self: the core
  *
- * @brief Clones a core with the same context as @em self
+ * \ingroup wpcore
- *
+ * \param self the core
- * @returns (transfer full): the clone [WpCore](@ref core_section)
+ * \returns (transfer full): the clone WpCore
  */
 WpCore *
 wp_core_clone (WpCore * self)
@@ -510,12 +459,10 @@ wp_core_clone (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns (transfer none) (nullable): the GMainContext that is in
- * @returns (transfer none) (nullable): the
+ *   use by this core for events
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
- * GMainContext</a> that is in use by this core for events
  */
 GMainContext *
 wp_core_get_g_main_context (WpCore * self)
@@ -525,10 +472,9 @@ wp_core_get_g_main_context (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns (transfer none): the internal pw_context object
- * @returns (transfer none): the internal `pw_context` object
  */
 struct pw_context *
 wp_core_get_pw_context (WpCore * self)
@@ -538,11 +484,10 @@ wp_core_get_pw_context (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns (transfer none) (nullable): the internal pw_core object,
- * @returns (transfer none) (nullable): the internal `pw_core` object,
+ *   or NULL if the core is not connected to PipeWire
- *   or %NULL if the core is not connected to PipeWire
  */
 struct pw_core *
 wp_core_get_pw_core (WpCore * self)
@@ -552,13 +497,13 @@ wp_core_get_pw_core (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Connects this core to the PipeWire server.
- * @param self: the core
  *
- * @brief Connects this core to the PipeWire server. When connection succeeds,
+ * When connection succeeds, the WpCore \c "connected" signal is emitted.
- * the [WpCore](@ref core_section) [connected](@ref signal_connected_section) signal is emitted
  *
- * @returns %TRUE if the core is effectively connected or %FALSE if
+ * \ingroup wpcore
+ * \param self the core
+ * \returns TRUE if the core is effectively connected or FALSE if
  *   connection failed
  */
 gboolean
@@ -590,13 +535,14 @@ wp_core_connect (WpCore *self)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Disconnects this core from the PipeWire server.
- * @param self: the core
  *
- * @brief Disconnects this core from the PipeWire server. This also effectively
+ * This also effectively destroys all WpCore objects that were created through
- * destroys all [WpCore](@ref core_section) objects that were created through the registry,
+ * the registry, destroys the pw_core and finally emits the WpCore
- * destroys the `pw_core` and finally emits the [WpCore](@ref core_section)
+ * \c "disconnected" signal.
- * [disconnected](@ref signal_disconnected_section) signal.
+ *
+ * \ingroup wpcore
+ * \param self the core
  */
 void
 wp_core_disconnect (WpCore *self)
@@ -610,10 +556,9 @@ wp_core_disconnect (WpCore *self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns TRUE if the core is connected to PipeWire, FALSE otherwise
- * @returns %TRUE if the core is connected to PipeWire, %FALSE otherwise
  */
 gboolean
 wp_core_is_connected (WpCore * self)
@@ -623,10 +568,9 @@ wp_core_is_connected (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns The cookie of the PipeWire instance that \a self is connected to.
- * @returns The cookie of the PipeWire instance that @em self is connected to.
  *     The cookie is a unique random number for identifying an instance of
  *     PipeWire
  */
@@ -640,10 +584,9 @@ wp_core_get_remote_cookie (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns The name of the PipeWire instance that \a self is connected to
- * @returns The name of the PipeWire instance that @em self is connected to
  */
 const gchar *
 wp_core_get_remote_name (WpCore * self)
@@ -655,11 +598,10 @@ wp_core_get_remote_name (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns The name of the user that started the PipeWire instance that
- * @returns The name of the user that started the PipeWire instance that
+ *     \a self is connected to
- *     @em self is connected to
  */
 const gchar *
 wp_core_get_remote_user_name (WpCore * self)
@@ -671,11 +613,10 @@ wp_core_get_remote_user_name (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns The name of the host where the PipeWire instance that
- * @returns The name of the host where the PipeWire instance that
+ *     \a self is connected to is running on
- *     @em self is connected to is running on
  */
 const gchar *
 wp_core_get_remote_host_name (WpCore * self)
@@ -687,10 +628,9 @@ wp_core_get_remote_host_name (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns The version of the PipeWire instance that \a self is connected to
- * @returns The version of the PipeWire instance that @em self is connected to
  */
 const gchar *
 wp_core_get_remote_version (WpCore * self)
@@ -702,11 +642,10 @@ wp_core_get_remote_version (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns (transfer full): the properties of the PipeWire instance that
- * @returns (transfer full): the properties of the PipeWire instance that
+ *     \a self is connected to
- *     @em self is connected to
  */
 WpProperties *
 wp_core_get_remote_properties (WpCore * self)
@@ -718,10 +657,9 @@ wp_core_get_remote_properties (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \ingroup wpcore
- * @param self: the core
+ * \param self the core
- *
+ * \returns (transfer full): the properties of \a self
- * @returns (transfer full): the properties of @em self
  */
 WpProperties *
 wp_core_get_properties (WpCore * self)
@@ -748,16 +686,16 @@ wp_core_get_properties (WpCore * self)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Updates the properties of \a self on the connection, making them
- * @param self: the core
+ * appear on the client object that represents this connection.
- * @param updates: (transfer full): updates to apply to the properties of @em self;
- *    this does not need to include properties that have not changed
  *
- * @brief Updates the properties of @em self on the connection, making them appear on
+ * If \a self is not connected yet, these properties are stored and passed to
- * the client object that represents this connection.
+ * pw_context_connect() when connecting.
  *
- * If @em self is not connected yet, these properties are stored and passed to
+ * \ingroup wpcore
- * `pw_context_connect` when connecting.
+ * \param self the core
+ * \param updates (transfer full): updates to apply to the properties of
+ *    \a self; this does not need to include properties that have not changed
  */
 void
 wp_core_update_properties (WpCore * self, WpProperties * updates)
@@ -779,21 +717,18 @@ wp_core_update_properties (WpCore * self, WpProperties * updates)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Adds an idle callback to be called in the same GMainContext as the
- * @param self: the core
+ * one used by this core.
- * @param source: (out) (optional): the source
- * @param function: (scope notified): the function to call
- * @param data: (closure): data to pass to @em function
- * @param destroy: (nullable): a function to destroy @em data
  *
- * @brief Adds an idle callback to be called in the same
+ * This is essentially the same as g_idle_add_full(), but it adds the created
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
+ * GSource on the GMainContext used by this core instead of the default context.
- * GMainContext</a> as the one used by this core. This is essentially the same as g_idle_add_full(),
+ *
- * but it adds the created
+ * \ingroup wpcore
- * <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
+ * \param self the core
- * GSource</a> on the 
+ * \param source (out) (optional): the source
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
+ * \param function (scope notified): the function to call
- * GMainContext</a> used by this core instead of the default context.
+ * \param data (closure): data to pass to \a function
+ * \param destroy (nullable): a function to destroy \a data
  */
 void
 wp_core_idle_add (WpCore * self, GSource **source, GSourceFunc function,
@@ -812,18 +747,16 @@ wp_core_idle_add (WpCore * self, GSource **source, GSourceFunc function,
 }
 
 /*!
- * @memberof WpCore
+ * \brief Adds an idle callback to be called in the same GMainContext as
- * @param self: the core
+ * the one used by this core.
- * @param source: (out) (optional): the source
- * @param closure: the closure to invoke
- *
- * @brief Adds an idle callback to be called in the same
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
- * GMainContext </a> as the one used by this core.
  *
  * This is the same as wp_core_idle_add(), but it allows you to specify a
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Closures.html#GClosure-struct">
+ * GClosure instead of a C callback.
- * GClosure</a> instead of a C callback.
+ *
+ * \ingroup wpcore
+ * \param self the core
+ * \param source (out) (optional): the source
+ * \param closure the closure to invoke
  */
 void
 wp_core_idle_add_closure (WpCore * self, GSource **source, GClosure * closure)
@@ -842,25 +775,25 @@ wp_core_idle_add_closure (WpCore * self, GSource **source, GClosure * closure)
 }
 
 /*!
- * @memberof WpCore
+ * \brief Adds a timeout callback to be called at regular intervals in the same
- * @param self: the core
+ * GMainContext as the one used by this core.
- * @param source: (out) (optional): the source
- * @param timeout_ms: the timeout in milliseconds
- * @param function: (scope notified): the function to call
- * @param data: (closure): data to pass to @em function
- * @param destroy: (nullable): a function to destroy @em data
  *
- * @brief Adds a timeout callback to be called at regular intervals in the same
+ * The function is called repeatedly until it returns FALSE, at which point
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
+ * the timeout is automatically destroyed and the function will not be called
- * GMainContext</a> as the one used by this core. The function is called repeatedly
+ * again. The first call to the function will be at the end of the first
- * until it returns FALSE, at which point the timeout is automatically destroyed
+ * interval.
- * and the function will not be called again. The first call to the function
+
- * will be at the end of the first interval. This is essentially the same as
+ * This is essentially the same as g_timeout_add_full(), but it adds
- * g_timeout_add_full(), but it adds the created
+ * the created GSource on the GMainContext used by this core instead of the
- * <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
+ * default context.
- * GSource</a> on the 
+ *
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
+ * \ingroup wpcore
- * GMainContext</a> used by this core instead of the default context.
+ * \param self the core
+ * \param source (out) (optional): the source
+ * \param timeout_ms the timeout in milliseconds
+ * \param function (scope notified): the function to call
+ * \param data (closure): data to pass to \a function
+ * \param destroy (nullable): a function to destroy \a data
  */
 void
 wp_core_timeout_add (WpCore * self, GSource **source, guint timeout_ms,
@@ -879,19 +812,17 @@ wp_core_timeout_add (WpCore * self, GSource **source, guint timeout_ms,
 }
 
 /*!
- * @memberof WpCore
+ * \brief Adds a timeout callback to be called at regular intervals in the same
- * @param self: the core
+ * GMainContext as the one used by this core.
- * @param source: (out) (optional): the source
- * @param timeout_ms: the timeout in milliseconds
- * @param closure: the closure to invoke
- *
- * @brief Adds a timeout callback to be called at regular intervals in the same
- * <a href="https://developer.gnome.org/glib/unstable/glib-The-Main-Event-Loop.html#GMainContext">
- * GMainContext</a> as the one used by this core.
  *
  * This is the same as wp_core_timeout_add(), but it allows you to specify a
- * <a href="https://developer.gnome.org/glib/stable/glib-The-Main-Event-Loop.html#GSource">
+ * GClosure instead of a C callback.
- * GClosure</a> instead of a C callback.
+ *
+ * \ingroup wpcore
+ * \param self the core
+ * \param source (out) (optional): the source
+ * \param timeout_ms the timeout in milliseconds
+ * \param closure the closure to invoke
  */
 void
 wp_core_timeout_add_closure (WpCore * self, GSource **source, guint timeout_ms,
@@ -911,25 +842,22 @@ wp_core_timeout_add_closure (WpCore * self, GSource **source, guint timeout_ms,
 }
 
 /*!
- * @memberof WpCore
+ * \brief Asks the PipeWire server to call the \a callback via an event.
- * @param self: the core
- * @param cancellable: (nullable):
- * a <a href="https://developer.gnome.org/gio/stable/GCancellable.html#GCancellable-struct">
- * GCancellable</a> to cancel the operation
- * @param callback: (scope async): a function to call when the operation is done
- * @param user_data: (closure): data to pass to @em callback
- *
- * @brief Asks the PipeWire server to call the @em callback via an event.
  *
  * Since methods are handled in-order and events are delivered
  * in-order, this can be used as a barrier to ensure all previous
  * methods and the resulting events have been handled.
  *
- * In both success and error cases, @em callback is always called. Use
+ * In both success and error cases, \a callback is always called.
- * wp_core_sync_finish() from within the @em callback to determine whether
+ * Use wp_core_sync_finish() from within the \a callback to determine whether
  * the operation completed successfully or if an error occurred.
  *
- * @returns %TRUE if the sync operation was started, %FALSE if an error
+ * \ingroup wpcore
+ * \param self the core
+ * \param cancellable (nullable): a GCancellable to cancel the operation
+ * \param callback (scope async): a function to call when the operation is done
+ * \param user_data (closure): data to pass to \a callback
+ * \returns TRUE if the sync operation was started, FALSE if an error
  *   occurred before returning from this function
  */
 gboolean
@@ -967,17 +895,14 @@ wp_core_sync (WpCore * self, GCancellable * cancellable,
 }
 
 /*!
- * @memberof WpCore
+ * \brief This function is meant to be called from within the callback of
- * @param self: the core
- * @param res: a
- * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncResult-struct">
- * GAsyncResult</a>
- * @param error: (out) (optional): the error that occurred, if any
- *
- * @brief This function is meant to be called from within the callback of
  * wp_core_sync() in order to determine the success or failure of the operation.
  *
- * @returns %TRUE if the operation succeeded, %FALSE otherwise
+ * \ingroup wpcore
+ * \param self the core
+ * \param res a GAsyncResult
+ * \param error (out) (optional): the error that occurred, if any
+ * \returns TRUE if the operation succeeded, FALSE otherwise
  */
 gboolean
 wp_core_sync_finish (WpCore * self, GAsyncResult * res, GError ** error)
@@ -998,4 +923,4 @@ WpCore *
 wp_registry_get_core (WpRegistry * self)
 {
   return SPA_CONTAINER_OF (self, WpCore, registry);
-}
+}

lib/wp/core.h

@@ -20,17 +20,9 @@ struct pw_core;
 typedef struct _WpObjectManager WpObjectManager;
 
 /*!
- * @memberof WpCore
+ * \brief The WpCore GType
- *
+ * \ingroup wpcore
- * @brief The [WpCore](@ref core_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_CORE (wp_core_get_type ())
- * @endcode
  */
-
 #define WP_TYPE_CORE (wp_core_get_type ())
 WP_API
 G_DECLARE_FINAL_TYPE (WpCore, wp_core, WP, CORE, GObject)

lib/wp/device.c

@@ -20,10 +20,21 @@
 #include <spa/monitor/device.h>
 #include <spa/utils/result.h>
 
+/*! \defgroup wpdevice WpDevice */
 /*!
- * @brief
+ * \struct WpDevice
- * @em parent
+ *
+ * The WpDevice class allows accessing the properties and methods of a
+ * PipeWire device object (`struct pw_device`).
+ *
+ * A WpDevice is constructed internally when a new device appears on the
+ * PipeWire registry and it is made available through the WpObjectManager API.
+ * Alternatively, a WpDevice can also be constructed using
+ * wp_device_new_from_factory(), which creates a new device object
+ * on the remote PipeWire server by calling into a factory.
+ *
  */
+
 struct _WpDevice
 {
   WpGlobalProxy parent;
@@ -32,41 +43,6 @@ struct _WpDevice
 static void wp_device_pw_object_mixin_priv_interface_init (
     WpPwObjectMixinPrivInterface * iface);
 
-/*!
- * @file device.c
- */
-
-/*!
- * @struct WpDevice
- * @section device_section Pipewire Device
- *
- * @brief The [WpDevice](@ref device_section) class allows accessing the properties and methods of a
- * PipeWire device object (`struct pw_device`).
- *
- * A [WpDevice](@ref device_section) is constructed internally when a new device appears on the
- * PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
- * Alternatively, a [WpDevice](@ref device_section) can also be constructed using
- * wp_device_new_from_factory(), which creates a new device object
- * on the remote PipeWire server by calling into a factory.
- *
- * @section spa_device_section WpSpaDevice
- *
- * @brief A [WpSpaDevice](@ref spa_device_section) allows running a `spa_device` object locally,
- * loading the implementation from a SPA factory. This is useful to run device
- * monitors inside the session manager and have control over creating the
- * actual nodes that the `spa_device` requests to create.
- *
- * To enable the spa device, call wp_object_activate() requesting
- * %WP_SPA_DEVICE_FEATURE_ENABLED.
- *
- * For actual devices (not device monitors) it also possible and desirable
- * to export the device to PipeWire, which can be done by requesting
- * %WP_PROXY_FEATURE_BOUND from wp_object_activate(). When exporting, the
- * export should be done before enabling the device, by requesting both
- * features at the same time.
- *
- */
-
 G_DEFINE_TYPE_WITH_CODE (WpDevice, wp_device, WP_TYPE_GLOBAL_PROXY,
     G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
         wp_pw_object_mixin_object_interface_init)
@@ -181,13 +157,8 @@ wp_device_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpDevice
+ * \brief Constructs a device on the PipeWire server by asking the remote
- * @param core: the wireplumber core
+ * factory \a factory_name to create it.
- * @param factory_name: the pipewire factory name to construct the device
- * @param properties: (nullable) (transfer full): the properties to pass to the factory
- *
- * @brief Constructs a device on the PipeWire server by asking the remote factory
- * @em factory_name to create it.
  *
  * Because of the nature of the PipeWire protocol, this operation completes
  * asynchronously at some point in the future. In order to find out when
@@ -196,7 +167,12 @@ wp_device_pw_object_mixin_priv_interface_init (
  * use on the server. If the device cannot be created, this activation operation
  * will fail.
  *
- * @returns (nullable) (transfer full): the new device or %NULL if the core
+ * \ingroup wpdevice
+ * \param core the wireplumber core
+ * \param factory_name the pipewire factory name to construct the device
+ * \param properties (nullable) (transfer full): the properties to pass to the
+ *   factory
+ * \returns (nullable) (transfer full): the new device or %NULL if the core
  *   is not connected and therefore the device cannot be created
  */
 
@@ -212,29 +188,7 @@ wp_device_new_from_factory (WpCore * core,
       NULL);
 }
 
-/*!
+/*! \defgroup wpspadevice WpSpaDevice */
- * @memberof WpDevice
- * @props @b properties
- *
- * @code
- * "properties" WpProperties *
- * @endcode
- *
- * @brief Flags : Read / Write / Construct Only
- *
- * @props @b spa-device-handle
- *
- * @code
- * "spa-device-handle" gpointer *
- * @endcode
- *
- * @brief Flags : Read / Write / Construct Only
- */
-enum {
-  PROP_0,
-  PROP_SPA_DEVICE_HANDLE,
-  PROP_PROPERTIES,
-};
 
 struct _WpSpaDevice
 {
@@ -246,57 +200,12 @@ struct _WpSpaDevice
   GPtrArray *managed_objs;
 };
 
-/*!
+enum {
- * @memberof WpDevice
+  PROP_0,
- * @signal @b create-object
+  PROP_SPA_DEVICE_HANDLE,
- *
+  PROP_PROPERTIES,
- * @code
+};
- * create_object_callback (WpSpaDevice * self,
+
- *                         guint id,
- *                         gchar * type,
- *                         gchar * factory,
- *                         WpProperties * properties,
- *                         gpointer user_data)
- * @endcode
- *
- * @brief This signal is emitted when the device is creating a managed object 
- * The handler is expected to actually construct the object using the requested SPA factory and 
- * with the given properties. The handler should then store the object with
- * wp_spa_device_store_managed_object. The WpSpaDevice will later unref the reference stored by
- * this function when the managed object is to be destroyed.
- *
- * Params:
- * @arg self - the [WpSpaDevice](@ref spa_device_section)
- * @arg id - the id of the managed object
- * @arg type - the SPA type that the managed object should have
- * @arg factory - the name of the SPA factory to use to construct the managed object
- * @arg properties - additional properties that the managed object should have
- * @arg user_data
- *
- * Flags: Run First
- *
- * @signal @b remove-object
- *
- * @code
- * object_removed_callback (WpSpaDevice * self,
- *                          guint id,
- *                          gpointer user_data)
- * @endcode
- *
- * @brief This signal is emitted when the device has deleted a managed object.
- * The handler may optionally release additional resources associated with this object.
- *
- * It is not necessary to call wp_spa_device_store_managed_object() to remove the managed object,
- * as this is done internally after this signal is fired.
- *
- * Params:
- * @arg self - the [WpSpaDevice](@ref spa_device_section)
- * @arg id - the id of the managed object
- * @arg user_data
- *
- * Flags: Run First
- *
- */
 enum
 {
   SIGNAL_CREATE_OBJECT,
@@ -541,6 +450,83 @@ wp_spa_device_deactivate (WpObject * object, WpObjectFeatures features)
   }
 }
 
+/*!
+ * \struct WpSpaDevice
+ *
+ * A WpSpaDevice allows running a `spa_device` object locally,
+ * loading the implementation from a SPA factory. This is useful to run device
+ * monitors inside the session manager and have control over creating the
+ * actual nodes that the `spa_device` requests to create.
+ *
+ * To enable the spa device, call wp_object_activate() requesting
+ * WP_SPA_DEVICE_FEATURE_ENABLED.
+ *
+ * For actual devices (not device monitors) it also possible and desirable
+ * to export the device to PipeWire, which can be done by requesting
+ * WP_PROXY_FEATURE_BOUND from wp_object_activate(). When exporting, the
+ * export should be done before enabling the device, by requesting both
+ * features at the same time.
+ *
+ * \gproperties
+ *
+ * \gproperty{properties, WpProperties *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   Properties of the spa device}
+ *
+ * \gproperty{spa-device-handle, gpointer, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The spa device handle}
+ *
+ * \gsignals
+ *
+ * \par create-object
+ * \parblock
+ * \code
+ * void
+ * create_object_callback (WpSpaDevice * self,
+ *                         guint id,
+ *                         gchar * type,
+ *                         gchar * factory,
+ *                         WpProperties * properties,
+ *                         gpointer user_data)
+ * \endcode
+ *
+ * This signal is emitted when the device is creating a managed object
+ * The handler is expected to actually construct the object using the requested
+ * SPA factory and with the given properties. The handler should then store the
+ * object with wp_spa_device_store_managed_object. The WpSpaDevice will later
+ * unref the reference stored by this function when the managed object is to be
+ * destroyed.
+ *
+ * Parameters:
+ * - `id` - the id of the managed object
+ * - `type` - the SPA type that the managed object should have
+ * - `factory` - the name of the SPA factory to use to construct the managed object
+ * - `properties` - additional properties that the managed object should have
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par remove-object
+ * \parblock
+ * \code
+ * void
+ * object_removed_callback (WpSpaDevice * self,
+ *                          guint id,
+ *                          gpointer user_data)
+ * \endcode
+ *
+ * This signal is emitted when the device has deleted a managed object.
+ * The handler may optionally release additional resources associated with this
+ * object.
+ *
+ * It is not necessary to call wp_spa_device_store_managed_object() to remove
+ * the managed object, as this is done internally after this signal is fired.
+ *
+ * Parameters:
+ * - `id` - the id of the managed object
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ */
 static void
 wp_spa_device_class_init (WpSpaDeviceClass * klass)
 {
@@ -567,54 +553,23 @@ wp_spa_device_class_init (WpSpaDeviceClass * klass)
           "Properties of the device", WP_TYPE_PROPERTIES,
           G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpSpaDevice::create-object:
-   * @self: the [WpSpaDevice](@ref spa_device_section)
-   * @id: the id of the managed object
-   * @type: the SPA type that the managed object should have
-   * @factory: the name of the SPA factory to use to construct the managed object
-   * @properties: additional properties that the managed object should have
-   *
-   * @brief This signal is emitted when the device is creating a managed object
-   * The handler is expected to actually construct the object using the
-   * requested SPA @em factory and with the given @em properties.
-   * The handler should then store the object with
-   * wp_spa_device_store_managed_object(). The [WpSpaDevice](@ref spa_device_section) will later unref
-   * the reference stored by this function when the managed object is to be
-   * destroyed.
-   */
   spa_device_signals[SIGNAL_CREATE_OBJECT] = g_signal_new (
       "create-object", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 4, G_TYPE_UINT, G_TYPE_STRING,
       G_TYPE_STRING, WP_TYPE_PROPERTIES);
 
-  /*
-   * WpSpaDevice::object-removed:
-   * @self: the [WpSpaDevice](@ref spa_device_section)
-   * @id: the id of the managed object that was removed
-   *
-   * @brief This signal is emitted when the device has deleted a managed object.
-   * The handler may optionally release additional resources associated
-   * with this object.
-   *
-   * It is not necessary to call wp_spa_device_store_managed_object()
-   * to remove the managed object, as this is done internally after this
-   * signal is fired.
-   */
   spa_device_signals[SIGNAL_OBJECT_REMOVED] = g_signal_new (
       "object-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_UINT);
 }
 
 /*!
- * @memberof WpDevice
+ * \ingroup wpspadevice
- * @param core: the wireplumber core
+ * \param core the wireplumber core
- * @param spa_device_handle: the spa device handle
+ * \param spa_device_handle the spa device handle
- * @param properties: (nullable) (transfer full): additional properties of the device
+ * \param properties (nullable) (transfer full): additional properties of the device
- *
+ * \returns (transfer full): A new WpSpaDevice
- * @returns (transfer full): A new [WpSpaDevice](@ref spa_device_section)
  */
-
 WpSpaDevice *
 wp_spa_device_new_wrap (WpCore * core, gpointer spa_device_handle,
     WpProperties * properties)
@@ -628,24 +583,22 @@ wp_spa_device_new_wrap (WpCore * core, gpointer spa_device_handle,
 }
 
 /*!
- * @memberof WpDevice
+ * \brief Constructs a `SPA_TYPE_INTERFACE_Device` by loading the given SPA
- * @param core: the wireplumber core
+ * \a factory_name.
- * @param factory_name: the name of the SPA factory
- * @param properties: (nullable) (transfer full): properties to be passed to device
- *    constructor
- *
- * @brief Constructs a `SPA_TYPE_INTERFACE_Device` by loading the given SPA
- * @em factory_name.
  *
  * To export this device to the PipeWire server, you need to call
- * wp_object_activate() requesting %WP_PROXY_FEATURE_BOUND and
+ * wp_object_activate() requesting WP_PROXY_FEATURE_BOUND and
  * wait for the operation to complete.
  *
- * @returns (nullable) (transfer full): A new [WpSpaDevice](@ref spa_device_section) wrapping the
+ * \ingroup wpspadevice
- *   device that was constructed by the factory, or %NULL if the factory
+ * \param core the wireplumber core
+ * \param factory_name the name of the SPA factory
+ * \param properties (nullable) (transfer full): properties to be passed to device
+ *    constructor
+ * \returns (nullable) (transfer full): A new WpSpaDevice wrapping the
+ *   device that was constructed by the factory, or NULL if the factory
  *   does not exist or was unable to construct the device
  */
-
 WpSpaDevice *
 wp_spa_device_new_from_spa_factory (WpCore * core,
     const gchar * factory_name, WpProperties * properties)
@@ -669,12 +622,10 @@ wp_spa_device_new_from_spa_factory (WpCore * core,
 }
 
 /*!
- * @memberof WpDevice
+ * \ingroup wpspadevice
- * @param self: the spa device
+ * \param self the spa device
- *
+ * \returns (transfer full): the device properties
- * @returns (transfer full): the device properties
  */
-
 WpProperties *
 wp_spa_device_get_properties (WpSpaDevice * self)
 {
@@ -683,13 +634,11 @@ wp_spa_device_get_properties (WpSpaDevice * self)
 }
 
 /*!
- * @memberof WpDevice
+ * \ingroup wpspadevice
- * @param self: the spa device
+ * \param self the spa device
- * @param id: the (device-internal) id of the object to get
+ * \param id the (device-internal) id of the object to get
- *
+ * \returns (transfer full): the managed object associated with \a id
- * @returns (transfer full): the managed object associated with @em id
  */
-
 GObject *
 wp_spa_device_get_managed_object (WpSpaDevice * self, guint id)
 {
@@ -701,13 +650,12 @@ wp_spa_device_get_managed_object (WpSpaDevice * self, guint id)
 }
 
 /*!
- * @memberof WpDevice
+ * \ingroup wpspadevice
- * @param self: the spa device
+ * \param self the spa device
- * @param id: the (device-internal) id of the object
+ * \param id the (device-internal) id of the object
- * @param object: (transfer full) (nullable): the object to store or %NULL to remove
+ * \param object (transfer full) (nullable): the object to store or NULL to remove
- *   the managed object associated with @em id
+ *   the managed object associated with \a id
  */
-
 void
 wp_spa_device_store_managed_object (WpSpaDevice * self, guint id,
     GObject * object)

lib/wp/device.h

@@ -16,16 +16,8 @@ G_BEGIN_DECLS
 /* WpDevice */
 
 /*!
- * @memberof WpDevice
+ * \brief The WpDevice GType
- *
+ * \ingroup wpdevice
- * @brief The [WpDevice](@ref device_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_DEVICE (wp_device_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_DEVICE (wp_device_get_type ())
 WP_API
@@ -38,29 +30,17 @@ WpDevice * wp_device_new_from_factory (WpCore * core,
 /* WpSpaDevice */
 
 /*!
- * @memberof WpDevice
+ * \brief Flags to be used as WpObjectFeatures for WpSpaDevice
- *
+ * \ingroup wpspadevice
- * @brief
- * @arg WP_SPA_DEVICE_FEATURE_ENABLED: enables a device
- *
- * Flags to be used as [WpObjectFeatures](@ref object_features_section) for
- * [WpSpaDevice](@ref spa_device_section)
  */
 typedef enum { /*< flags >*/
+  /*! enables a spa device */
   WP_SPA_DEVICE_FEATURE_ENABLED = (WP_PROXY_FEATURE_CUSTOM_START << 0),
 } WpSpaDeviceFeatures;
 
 /*!
- * @memberof WpDevice
+ * \brief The WpSpaDevice GType
- *
+ * \ingroup wpspadevice
- * @brief The [WpSpaDevice](@ref spa_device_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SPA_DEVICE (wp_spa_device_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SPA_DEVICE (wp_spa_device_get_type ())
 WP_API

lib/wp/endpoint.c

@@ -22,40 +22,27 @@
 #include <pipewire/extensions/session-manager/introspect-funcs.h>
 #include <spa/utils/result.h>
 
+/*! \defgroup wpendpoint WpEndpoint */
 /*!
- * @memberof WpEndpoint
+ * \struct WpEndpoint
  *
- * @props @b direction
+ * The WpEndpoint class allows accessing the properties and methods of a
+ * PipeWire endpoint object (`struct pw_endpoint` from the session-manager extension).
  *
- * @code
+ * A WpEndpoint is constructed internally when a new endpoint appears on the
- * "direction" WpDirection *
+ * PipeWire registry and it is made available through the WpObjectManager API.
- * @endcode
  *
- * @brief The direction of the endpoint
+ * \gproperties
  *
- * Flags : Read
+ * \gproperty{name, gchar *, G_PARAM_READABLE, The name of the endpoint}
  *
- * @props @b media-class
+ * \gproperty{media-class, gchar *, G_PARAM_READABLE,
- *
+ *   The media class of the endpoint (ex. "Audio/Sink")}
- * @code
- * "media-class" gchar *
- * @endcode
- *
- * @brief The media class of the endpoint (ex. "Audio/Sink")
- *
- * Flags : Read
- *
- * @props @b name
- *
- * @code
- * "name" gchar *
- * @endcode
- *
- * @brief The name of the endpoint
- *
- * Flags : Read
  *
+ * \gproperty{direction, WpDirection, G_PARAM_READABLE,
+ *   The direction of the endpoint}
  */
+
 enum {
   PROP_NAME = WP_PW_OBJECT_MIXIN_PROP_CUSTOM_START,
   PROP_MEDIA_CLASS,
@@ -71,23 +58,6 @@ struct _WpEndpointPrivate
 static void wp_endpoint_pw_object_mixin_priv_interface_init (
     WpPwObjectMixinPrivInterface * iface);
 
-/*!
- * @file endpoint.c
- */
-
-/*!
- * @struct WpEndpoint
- *
- * @section endpoint_section Pipewire Endpoint
- *
- * @brief The [WpEndpoint](@ref endpoint_section) class allows accessing the properties and methods of a
- * PipeWire endpoint object (`struct pw_endpoint` from the session-manager extension).
- *
- * A [WpEndpoint](@ref endpoint_section) is constructed internally when a new endpoint appears on the
- * PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
- *
- */
-
 G_DEFINE_TYPE_WITH_CODE (WpEndpoint, wp_endpoint, WP_TYPE_GLOBAL_PROXY,
     G_ADD_PRIVATE (WpEndpoint)
     G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
@@ -204,29 +174,14 @@ wp_endpoint_class_init (WpEndpointClass * klass)
 
   wp_pw_object_mixin_class_override_properties (object_class);
 
-  /*
-   * WpEndpoint:name:
-   *
-   * @brief The name of the endpoint
-   */
   g_object_class_install_property (object_class, PROP_NAME,
       g_param_spec_string ("name", "name", "name", NULL,
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpEndpoint:media-class:
-   *
-   * @brief The media class of the endpoint (ex. "Audio/Sink")
-   */
   g_object_class_install_property (object_class, PROP_MEDIA_CLASS,
       g_param_spec_string ("media-class", "media-class", "media-class", NULL,
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpEndpoint:direction:
-   *
-   * @brief The direction of the endpoint
-   */
   g_object_class_install_property (object_class, PROP_DIRECTION,
       g_param_spec_enum ("direction", "direction", "direction",
           WP_TYPE_DIRECTION, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
@@ -260,14 +215,12 @@ wp_endpoint_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpEndpoint
+ * \brief Gets the name of the endpoint
- * @param self: the endpoint
+ * \remarks Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
- *
+ * \ingroup wpendpoint
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \param self the endpoint
- *
+ * \returns the name of the endpoint
- * @returns the name of the endpoint
  */
-
 const gchar *
 wp_endpoint_get_name (WpEndpoint * self)
 {
@@ -280,14 +233,12 @@ wp_endpoint_get_name (WpEndpoint * self)
 }
 
 /*!
- * @memberof WpEndpoint
+ * \brief Gets the media class of the endpoint (ex. "Audio/Sink")
- * @param self: the endpoint
+ * \remarks Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
- *
+ * \ingroup wpendpoint
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \param self the endpoint
- *
+ * \returns the media class of the endpoint
- * @returns the media class of the endpoint (ex. "Audio/Sink")
  */
-
 const gchar *
 wp_endpoint_get_media_class (WpEndpoint * self)
 {
@@ -300,14 +251,12 @@ wp_endpoint_get_media_class (WpEndpoint * self)
 }
 
 /*!
- * @memberof WpEndpoint
+ * \brief Gets the direction of the endpoint
- * @param self: the endpoint
+ * \remarks Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
- *
+ * \ingroup wpendpoint
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \param self the endpoint
- *
+ * \returns the direction of this endpoint
- * @returns the direction of this endpoint
  */
-
 WpDirection
 wp_endpoint_get_direction (WpEndpoint * self)
 {
@@ -326,22 +275,6 @@ enum {
   IMPL_PROP_ITEM,
 };
 
-/*!
- * @struct WpImplEndpoint
- * @memberof WpEndpoint
- *
- * @section impl_endpoint_section WpImplEndpoint
- *
- * @section impl_endpoint_class_props_section Properties
- *
- * @b item
- *
- * @code
- * “item” WpSiEndpoint *
- * @endcode
- *
- * @brief Flags : Read / Write / Construct Only
- */
 struct _WpImplEndpoint
 {
   WpEndpoint parent;
@@ -634,6 +567,14 @@ wp_impl_endpoint_activate_execute_step (WpObject * object,
   }
 }
 
+/*!
+ * \struct WpImplEndpoint
+ *
+ * \gproperties
+ *
+ * \gproperty{item, WpSiEndpoint *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The session item that implements this endpoint}
+ */
 static void
 wp_impl_endpoint_class_init (WpImplEndpointClass * klass)
 {
@@ -733,13 +674,11 @@ wp_endpoint_impl_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpEndpoint
+ * \ingroup wpendpoint
- * @param core: the core
+ * \param core the core
- * @param item: the endpoint
+ * \param item the session item that implements the endpoint
- *
+ * \returns (transfer full): a new WpImplEndpoint
- * Returns: (transfer full): a new [WpImplEndpoint](@ref impl_endpoint_section)
  */
-
 WpImplEndpoint *
 wp_impl_endpoint_new (WpCore * core, WpSiEndpoint * item)
 {

lib/wp/endpoint.h

@@ -18,27 +18,13 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpEndpoint
+ * \brief The WpEndpoint GType
- *
+ * \ingroup wpendpoint
- * @brief The [WpEndpoint](@ref endpoint_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_ENDPOINT (wp_endpoint_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_ENDPOINT (wp_endpoint_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpEndpoint, wp_endpoint, WP, ENDPOINT, WpGlobalProxy)
 
-/*!
- * @memberof WpEndpoint
- *
- * @brief
- * @em parent_class
- */
 struct _WpEndpointClass
 {
   WpGlobalProxyClass parent_class;
@@ -54,15 +40,8 @@ WP_API
 WpDirection wp_endpoint_get_direction (WpEndpoint * self);
 
 /*!
- * @memberof WpEndpoint
+ * \brief The WpImplEndpoint GType
- *
+ * \ingroup wpendpoint
- * @brief The [WpImplEndpoint](@ref impl_endpoint_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- * @code
- * #define WP_TYPE_IMPL_ENDPOINT (wp_impl_endpoint_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_IMPL_ENDPOINT (wp_impl_endpoint_get_type ())
 WP_API

lib/wp/error.c

@@ -8,15 +8,6 @@
 
 #include "error.h"
 
-/**
+/*! \defgroup wperror Errors */
- * wp_domain_library_quark:
+
- *
- * @file error.c
- *
- * @section error_section Error codes
- *
- * Error domain and codes for
- * <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
- * GError</a>
- */
 G_DEFINE_QUARK (wireplumber-library, wp_domain_library);

lib/wp/error.h

@@ -14,66 +14,27 @@
 
 G_BEGIN_DECLS
 
-/**
+/*!
- * WP_DOMAIN_LIBRARY:
+ * \brief A GError domain for errors that occurred within the context of the
- *
- * @file error.c
- * @struct ErrorCodes
- * @section error_section Error codes
- *
- * @brief Error domain and codes for <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
- * GError</a>
- *
- * @b wp_domain_library_quark
- *
- * @code
- * GQuark wp_domain_library_quark ()
- * @endcode
- *
- * @subsection error_enum_subsection Enumerations
- *
- * @subsubsection error_enum_subsubsection WpLibraryErrorEnum:
- *
- * @brief Error codes that can appear in a 
- * <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">GError</a>
- * when the error domain is [WP_DOMAIN_LIBRARY](@ref error_constants_subsection)
- *
- * @b Members:
- *
- * @arg `WP_LIBRARY_ERROR_INVARIANT (0) – an invariant check failed; this most likely indicates a programming error`
- * @arg `WP_LIBRARY_ERROR_INVALID_ARGUMENT (1) – an unexpected/invalid argument was given`
- * @arg `WP_LIBRARY_ERROR_OPERATION_FAILED (2) – an operation failed`
- *
- * @subsection error_constants_subsection Constants
- *
- * @b WP_DOMAIN_LIBRARY:
- *
- * A <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
- * GError</a> domain for errors that occurred within the context of the
  * WirePlumber library.
- *
+ * \ingroup wperror
- * @code
- * #define WP_DOMAIN_LIBRARY (wp_domain_library_quark ())
- * @endcode 
  */
 #define WP_DOMAIN_LIBRARY (wp_domain_library_quark ())
 WP_API
 GQuark wp_domain_library_quark (void);
 
 /*!
- * @em WP_LIBRARY_ERROR_INVARIANT: an invariant check failed; this most likely
+ * \brief Error codes that can appear in a GError when the error domain
- *    indicates a programming error
+ * is WP_DOMAIN_LIBRARY
- * @em WP_LIBRARY_ERROR_INVALID_ARGUMENT: an unexpected/invalid argument was given
+ * \ingroup wperror
- * @em WP_LIBRARY_ERROR_OPERATION_FAILED: an operation failed
- *
- * Error codes that can appear in a 
- * <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
- * GError</a> when the error domain
- * is %WP_DOMAIN_LIBRARY
  */
 typedef enum {
+  /*! an invariant check failed; this most likely
+   *  indicates a programming error */
   WP_LIBRARY_ERROR_INVARIANT,
+  /*! an unexpected/invalid argument was given */
   WP_LIBRARY_ERROR_INVALID_ARGUMENT,
+  /*! an operation failed */
   WP_LIBRARY_ERROR_OPERATION_FAILED,
 } WpLibraryErrorEnum;
 

lib/wp/global-proxy.c

@@ -13,6 +13,29 @@
 #include "core.h"
 #include "error.h"
 
+/*! \defgroup wpglobalproxy WpGlobalProxy */
+/*!
+ * \struct WpGlobalProxy
+ *
+ * A proxy that represents a PipeWire global object, i.e. an
+ * object that is made available through the PipeWire registry.
+ *
+ * \gproperties
+ *
+ * \gproperty{global, WpGlobal *, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY,
+ *   Internal WpGlobal object}
+ *
+ * \gproperty{factory-name, gchar *, G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY,
+ *   The factory name}
+ *
+ * \gproperty{global-properties, WpProperties *,
+ *   G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The pipewire global properties}
+ *
+ * \gproperty{permissions, guint, G_PARAM_READABLE,
+ *   The pipewire global permissions}
+ */
+
 typedef struct _WpGlobalProxyPrivate WpGlobalProxyPrivate;
 struct _WpGlobalProxyPrivate
 {
@@ -21,34 +44,6 @@ struct _WpGlobalProxyPrivate
   WpProperties *properties;
 };
 
-/*!
- * @memberof WpGlobalProxy
- *
- * @props @b global
- *
- * @code
- * “global” object *
- * @endcode
- *
- * @brief Flags : Read / Write / Construct Only
- *
- * @props @b global-properties
- *
- * @code
- * “global-properties” [WpProperties](@ref properties_section) *
- * @endcode
- *
- * @brief Flags : Read
- *
- * @props @b permissions
- *
- * @code
- * “permissions” <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint">guint</a>
- * @endcode
- *
- * @brief Flags : Read
- *
- */
 enum {
   PROP_0,
   PROP_GLOBAL,
@@ -57,19 +52,6 @@ enum {
   PROP_PERMISSIONS,
 };
 
-/*!
- * @file global-proxy.c
- */
-
-/*!
- * @struct WpGlobalProxy
- * @section global_proxy_section Global Proxy
- *
- * @brief A proxy that represents a PipeWire global object, i.e. an object that is
- * made available through the PipeWire registry.
- *
- */
-
 G_DEFINE_TYPE_WITH_PRIVATE (WpGlobalProxy, wp_global_proxy, WP_TYPE_PROXY)
 
 static void
@@ -316,18 +298,18 @@ wp_global_proxy_class_init (WpGlobalProxyClass * klass)
 }
 
 /*!
- * @memberof WpGlobalProxy
+ * \brief Requests the PipeWire server to destroy the object represented by
- * @param self: the pipewire global
+ * this proxy.
  *
- * @brief Requests the PipeWire server to destroy the object represented by this proxy.
  * If the server allows it, the object will be destroyed and the
- * WpProxy::pw-proxy-destroyed signal will be emitted. If the server does
+ * WpProxy's `pw-proxy-destroyed` signal will be emitted. If the server does
  * not allow it, nothing will happen.
  *
- * This is mostly useful for destroying [WpLink](@ref link_section) and
+ * This is mostly useful for destroying WpLink objects.
- * [WpEndpointLink](@ref endpoint_link_section) objects.
+ *
+ * \ingroup wpglobalproxy
+ * \param self the pipewire global
  */
-
 void
 wp_global_proxy_request_destroy (WpGlobalProxy * self)
 {
@@ -344,12 +326,10 @@ wp_global_proxy_request_destroy (WpGlobalProxy * self)
 }
 
 /*!
- * @memberof WpGlobalProxy
+ * \ingroup wpglobalproxy
- * @param self: the pipewire global
+ * \param self the pipewire global
- *
+ * \returns the permissions that wireplumber has on this object
- * @returns the permissions that wireplumber has on this object
  */
-
 guint32
 wp_global_proxy_get_permissions (WpGlobalProxy * self)
 {
@@ -362,13 +342,11 @@ wp_global_proxy_get_permissions (WpGlobalProxy * self)
 }
 
 /*!
- * @memberof WpGlobalProxy
+ * \ingroup wpglobalproxy
- * @param self: the pipewire global
+ * \param self the pipewire global
- *
+ * \returns (transfer full): the global (immutable) properties of this
- * @returns (transfer full): the global (immutable) properties of this
  *   pipewire object
  */
-
 WpProperties *
 wp_global_proxy_get_global_properties (WpGlobalProxy * self)
 {
@@ -383,18 +361,18 @@ wp_global_proxy_get_global_properties (WpGlobalProxy * self)
 }
 
 /*!
- * @memberof WpGlobalProxy
+ * \brief Binds to the global and creates the underlying `pw_proxy`.
- * @param self: the pipewire global
- *
- * @brief Binds to the global and creates the underlying `pw_proxy`. This may only
- * be called if there is no `pw_proxy` associated with this object yet.
  *
  * This is mostly meant to be called internally. It will create the `pw_proxy`
- * and will activate the %WP_PROXY_FEATURE_BOUND feature.
+ * and will activate the WP_PROXY_FEATURE_BOUND feature.
  *
- * @returns %TRUE on success, %FALSE if there is no global to bind to
+ * This may only be called if there is no `pw_proxy` associated with this
+ * object yet.
+ *
+ * \ingroup wpglobalproxy
+ * \param self the pipewire global
+ * \returns TRUE on success, FALSE if there is no global to bind to
  */
-
 gboolean
 wp_global_proxy_bind (WpGlobalProxy * self)
 {
@@ -407,4 +385,4 @@ wp_global_proxy_bind (WpGlobalProxy * self)
   if (priv->global)
     wp_proxy_set_pw_proxy (WP_PROXY (self), wp_global_bind (priv->global));
   return !!priv->global;
-}
+}

lib/wp/global-proxy.h

@@ -15,28 +15,14 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpGlobalProxy
+ * \brief The WpGlobalProxy GType
- *
+ * \ingroup wpglobalproxy
- * @brief The [WpGlobalProxy](@ref global_proxy_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_GLOBAL_PROXY (wp_global_proxy_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_GLOBAL_PROXY (wp_global_proxy_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpGlobalProxy, wp_global_proxy,
                           WP, GLOBAL_PROXY, WpProxy)
 
-/*!
- * @memberof WpGlobalProxy
- *
- * @brief
- * @em parent_class
- */
 struct _WpGlobalProxyClass
 {
   WpProxyClass parent_class;

lib/wp/iterator.c

@@ -5,19 +5,16 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
- * @file iterator.c
- */
 
 #define G_LOG_DOMAIN "wp-iterator"
 
 #include "iterator.h"
 #include <spa/utils/defs.h>
 
+/*! \defgroup wpiterator WpIterator */
 /*!
- * @struct WpIterator
+ * \struct WpIterator
- * @section iterator_section Iterator
+ * A generic iterator API
- *
  */
 struct _WpIterator
 {
@@ -67,19 +64,19 @@ wp_iterator_default_foreach (WpIterator *self, WpIteratorForeachFunc func,
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Constructs an iterator that uses the provided \a methods to implement
- * @param methods: method implementations for the new iterator
+ * its API.
- * @param user_size: size of the user_data structure to be allocated
  *
- * @brief Constructs an iterator that uses the provided @em methods to implement its API.
+ * The WpIterator structure is internally allocated with \a user_size additional
- * The WpIterator structure is internally allocated with @em user_size additional
  * space at the end. A pointer to this space can be retrieved with
  * wp_iterator_get_user_data() and is available for implementation-specific
  * storage.
  *
- * @returns (transfer full): a new custom iterator
+ * \ingroup wpiterator
+ * \param methods method implementations for the new iterator
+ * \param user_size size of the user_data structure to be allocated
+ * \returns (transfer full): a new custom iterator
  */
-
 WpIterator *
 wp_iterator_new (const WpIteratorMethods *methods, size_t user_size)
 {
@@ -96,14 +93,13 @@ wp_iterator_new (const WpIteratorMethods *methods, size_t user_size)
 }
 
 /*!
- * @memberof WpIterator
+ * \note this only for use by implementations of WpIterator
- * @param self: an iterator object
  *
- * Note: this only for use by implementations of WpIterator
+ * \protected
- *
+ * \ingroup wpiterator
- * @returns a pointer to the implementation-specific storage area
+ * \param self an iterator object
+ * \returns a pointer to the implementation-specific storage area
  */
-
 gpointer
 wp_iterator_get_user_data (WpIterator *self)
 {
@@ -111,12 +107,10 @@ wp_iterator_get_user_data (WpIterator *self)
 }
 
 /*!
- * @memberof WpIterator
+ * \ingroup wpiterator
- * @param self: an iterator object
+ * \param self an iterator object
- *
+ * \returns (transfer full): \a self with an additional reference count on it
- * @returns (transfer full): @em self with an additional reference count on it
  */
-
 WpIterator *
 wp_iterator_ref (WpIterator *self)
 {
@@ -131,13 +125,12 @@ wp_iterator_free (WpIterator *self)
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Decreases the reference count on \a self and frees it when the ref
- * @param self: (transfer full): an iterator object
+ * count reaches zero.
  *
- * @brief Decreases the reference count on @em self and frees it when the ref count
+ * \ingroup wpiterator
- * reaches zero.
+ * \param self (transfer full): an iterator object
  */
-
 void
 wp_iterator_unref (WpIterator *self)
 {
@@ -145,12 +138,11 @@ wp_iterator_unref (WpIterator *self)
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Resets the iterator so we can iterate again from the beginning.
- * @param self: the iterator
  *
- * @brief Resets the iterator so we can iterate again from the beginning.
+ * \ingroup wpiterator
+ * \param self the iterator
  */
-
 void
 wp_iterator_reset (WpIterator *self)
 {
@@ -161,13 +153,12 @@ wp_iterator_reset (WpIterator *self)
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Gets the next item of the iterator.
- * @param self: the iterator
- * @param item: (out): the next item of the iterator
  *
- * @brief Gets the next item of the iterator.
+ * \ingroup wpiterator
- *
+ * \param self the iterator
- * @returns TRUE if next iterator was obtained, FALSE when the iterator has no
+ * \param item (out): the next item of the iterator
+ * \returns TRUE if next iterator was obtained, FALSE when the iterator has no
  * more items to iterate through.
  */
 
@@ -181,18 +172,15 @@ wp_iterator_next (WpIterator *self, GValue *item)
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Iterates over all items of the iterator calling a function.
- * @param self: the iterator
- * @param func: (scope call): the fold function
- * @param ret: (inout): the accumulator data
- * @param data: (closure): the user data
- *
- * @brief Iterates over all items of the iterator calling a function.
- *
- * @returns TRUE if all the items were processed, FALSE otherwise.
  *
+ * \ingroup wpiterator
+ * \param self the iterator
+ * \param func (scope call): the fold function
+ * \param ret (inout): the accumulator data
+ * \param data (closure): the user data
+ * \returns TRUE if all the items were processed, FALSE otherwise.
  */
-
 gboolean
 wp_iterator_fold (WpIterator *self, WpIteratorFoldFunc func, GValue *ret,
     gpointer data)
@@ -206,17 +194,14 @@ wp_iterator_fold (WpIterator *self, WpIteratorFoldFunc func, GValue *ret,
 }
 
 /*!
- * @memberof WpIterator
+ * \brief Fold a function over the items of the iterator.
- * @param self: the iterator
- * @param func: (scope call): the foreach function
- * @param data: (closure): the user data
- *
- * @brief Fold a function over the items of the iterator.
- *
- * @returns TRUE if all the items were processed, FALSE otherwise.
  *
+ * \ingroup wpiterator
+ * \param self the iterator
+ * \param func (scope call): the foreach function
+ * \param data (closure): the user data
+ * \returns TRUE if all the items were processed, FALSE otherwise.
  */
-
 gboolean
 wp_iterator_foreach (WpIterator *self, WpIteratorForeachFunc func,
    gpointer data)
@@ -296,13 +281,11 @@ static const WpIteratorMethods ptr_array_iterator_methods = {
 };
 
 /*!
- * @memberof WpIterator
+ * \ingroup wpiterator
- * @items: (element-type utf8) (transfer full): the items to iterate over
+ * \param items (element-type utf8) (transfer full): the items to iterate over
- * @item_type: the type of each item
+ * \param item_type the type of each item
- *
+ * \returns (transfer full): a new iterator that iterates over \a items
- * @returns (transfer full): a new iterator that iterates over @em items
  */
-
 WpIterator *
 wp_iterator_new_ptr_array (GPtrArray * items, GType item_type)
 {
@@ -334,4 +317,4 @@ wp_iterator_new_ptr_array (GPtrArray * items, GType item_type)
     g_return_val_if_reached (NULL);
 
   return g_steal_pointer (&it);
-}
+}

lib/wp/iterator.h

@@ -15,42 +15,27 @@
 G_BEGIN_DECLS
 
 /*!
- * @fn WpIteratorFoldFunc:
+ * \brief A function to be passed to wp_iterator_fold()
- * @memberof WpIterator
+ * \param item the item to fold
- *
+ * \param ret the value collecting the result
- * @param item: the item to fold
+ * \param data data passed to wp_iterator_fold()
- * @param ret: the value collecting the result
+ * \returns TRUE if the fold should continue, FALSE if it should stop.
- * @param data: data passed to @b wp_iterator_fold
+ * \ingroup wpiterator
- *
- * A function to be passed to `wp_iterator_fold()`.
- *
- * @returns TRUE if the fold should continue, FALSE if it should stop.
  */
 typedef gboolean (*WpIteratorFoldFunc) (const GValue *item, GValue *ret,
     gpointer data);
 
 /*!
- * @fn WpIteratorForeachFunc:
+ * \brief A function that is called by wp_iterator_foreach().
- * @memberof WpIterator
+ * \param item the item
- *
+ * \param data the data passed to wp_iterator_foreach()
- * @param item: the item
+ * \ingroup wpiterator
- * @param data: the data passed to @b wp_iterator_foreach
- *
- * A function that is called by `wp_iterator_foreach()`.
  */
 typedef void (*WpIteratorForeachFunc) (const GValue *item, gpointer data);
 
 /*!
- * memberof WpIterator
+ * \brief The WpIterator GType
- *
+ * \ingroup wpiterator
- * @brief The [WpIterator](@ref iterator_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_ITERATOR (wp_iterator_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_ITERATOR (wp_iterator_get_type ())
 WP_API
@@ -59,6 +44,11 @@ GType wp_iterator_get_type (void);
 typedef struct _WpIterator WpIterator;
 typedef struct _WpIteratorMethods WpIteratorMethods;
 
+/*!
+ * \brief The version to set to _WpIteratorMethods::version.
+ * This allows future expansion of the struct
+ * \ingroup wpiterator
+ */
 static const guint32 WP_ITERATOR_METHODS_VERSION = 0;
 
 struct _WpIteratorMethods

lib/wp/link.c

@@ -6,18 +6,25 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file link.c
- */
 #define G_LOG_DOMAIN "wp-link"
 
 #include "link.h"
 #include "private/pipewire-object-mixin.h"
 
+/*! \defgroup wplink WpLink */
 /*!
- * @brief
+ * \struct WpLink
- * @em parent
+ *
+ * The WpLink class allows accessing the properties and methods of a
+ * PipeWire link object (`struct pw_link`).
+ *
+ * A WpLink is constructed internally when a new link appears on the
+ * PipeWire registry and it is made available through the WpObjectManager API.
+ * Alternatively, a WpLink can also be constructed using
+ * wp_link_new_from_factory(), which creates a new link object
+ * on the remote PipeWire server by calling into a factory.
  */
+
 struct _WpLink
 {
   WpGlobalProxy parent;
@@ -26,21 +33,6 @@ struct _WpLink
 static void wp_link_pw_object_mixin_priv_interface_init (
     WpPwObjectMixinPrivInterface * iface);
 
-/*!
- * @struct WpLink
- *
- * @section link_section Pipewire Link
- *
- * @brief The [WpLink](@ref link_section) class allows accessing the properties and methods of a
- * PipeWire link object (`struct pw_link`).
- *
- * A [WpLink](@ref link_section) is constructed internally when a new link appears on the
- * PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
- * Alternatively, a [WpLink](@ref link_section) can also be constructed using
- * wp_link_new_from_factory(), which creates a new link object
- * on the remote PipeWire server by calling into a factory.
- */
-
 G_DEFINE_TYPE_WITH_CODE (WpLink, wp_link, WP_TYPE_GLOBAL_PROXY,
     G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
         wp_pw_object_mixin_object_interface_init)
@@ -123,25 +115,24 @@ wp_link_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpLink
+ * \brief Constructs a link on the PipeWire server by asking the remote factory
- * @param core: the wireplumber core
+ * \a factory_name to create it.
- * @param factory_name: the pipewire factory name to construct the link
- * @param properties: (nullable) (transfer full): the properties to pass to the factory
- *
- * @brief Constructs a link on the PipeWire server by asking the remote factory
- * @em factory_name to create it.
  *
  * Because of the nature of the PipeWire protocol, this operation completes
  * asynchronously at some point in the future. In order to find out when
  * this is done, you should call wp_object_activate(), requesting at least
- * %WP_PROXY_FEATURE_BOUND. When this feature is ready, the link is ready for
+ * WP_PROXY_FEATURE_BOUND. When this feature is ready, the link is ready for
  * use on the server. If the link cannot be created, this activation operation
  * will fail.
  *
- * @returns (nullable) (transfer full): the new link or %NULL if the core
+ * \ingroup wplink
+ * \param core the wireplumber core
+ * \param factory_name the pipewire factory name to construct the link
+ * \param properties (nullable) (transfer full): the properties to pass to the
+ *   factory
+ * \returns (nullable) (transfer full): the new link or NULL if the core
  *   is not connected and therefore the link cannot be created
  */
-
 WpLink *
 wp_link_new_from_factory (WpCore * core,
     const gchar * factory_name, WpProperties * properties)
@@ -155,18 +146,17 @@ wp_link_new_from_factory (WpCore * core,
 }
 
 /*!
- * @memberof WpLink
+ * \brief Retrieves the ids of the objects that are linked by this link
- * @param self: the link
- * @param output_node: (out) (optional): the bound id of the output (source) node
- * @param output_port: (out) (optional): the bound id of the output (source) port
- * @param input_node: (out) (optional): the bound id of the input (sink) node
- * @param input_port: (out) (optional): the bound id of the input (sink) port
  *
- * @brief Retrieves the ids of the objects that are linked by this link
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @note Using this method requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \ingroup wplink
+ * \param self the link
+ * \param output_node (out) (optional): the bound id of the output (source) node
+ * \param output_port (out) (optional): the bound id of the output (source) port
+ * \param input_node (out) (optional): the bound id of the input (sink) node
+ * \param input_port (out) (optional): the bound id of the input (sink) port
  */
-
 void
 wp_link_get_linked_object_ids (WpLink * self,
     guint32 * output_node, guint32 * output_port,
@@ -186,4 +176,4 @@ wp_link_get_linked_object_ids (WpLink * self,
     *input_node = info->input_node_id;
   if (input_port)
     *input_port = info->input_port_id;
-}
+}

lib/wp/link.h

@@ -14,16 +14,8 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WPLink
+ * \brief The WpLink GType
- *
+ * \ingroup wplink
- * @brief The [WpLink](@ref link_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_LINK (wp_link_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_LINK (wp_link_get_type ())
 WP_API

lib/wp/log.c

@@ -6,20 +6,166 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file debug.c
- */
-
-/*!
- * WpDebug:
- */
-
 #include "log.h"
 #include "spa-pod.h"
 #include "proxy.h"
 #include <pipewire/pipewire.h>
 #include <spa/support/log.h>
 
+/*!
+ * \defgroup wplog Debug Logging
+ * \{
+ */
+/*!
+ * \def WP_LOG_LEVEL_TRACE
+ * \brief A custom GLib log level for trace messages (see GLogLevelFlags)
+ */
+/*!
+ * \def WP_OBJECT_FORMAT
+ * \brief A format string to print GObjects with WP_OBJECT_ARGS()
+ * For example:
+ * \code
+ * GObject *myobj = ...;
+ * wp_debug ("This: " WP_OBJECT_FORMAT " is an object", WP_OBJECT_ARGS (myobj));
+ * \endcode
+ */
+/*!
+ * \def WP_OBJECT_ARGS(object)
+ * \brief A macro to format an object for printing with WP_OBJECT_FORMAT
+ */
+/*!
+ * \def wp_critical(...)
+ * \brief Logs a critical message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_critical_object(object, ...)
+ * \brief Logs a critical message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_critical_boxed(type, object, ...)
+ * \brief Logs a critical message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_warning(...)
+ * \brief Logs a warning message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_warning_object(object, ...)
+ * \brief Logs a warning message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_warning_boxed(type, object, ...)
+ * \brief Logs a warning message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_message(...)
+ * \brief Logs a standard message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_message_object(object, ...)
+ * \brief Logs a standard message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_message_boxed(type, object, ...)
+ * \brief Logs a standard message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_info(...)
+ * \brief Logs a info message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_info_object(object, ...)
+ * \brief Logs a info message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_info_boxed(type, object, ...)
+ * \brief Logs a info message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_debug(...)
+ * \brief Logs a debug message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_debug_object(object, ...)
+ * \brief Logs a debug message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_debug_boxed(type, object, ...)
+ * \brief Logs a debug message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_trace(...)
+ * \brief Logs a trace message to the standard log via GLib's logging system.
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_trace_object(object, ...)
+ * \brief Logs a trace message to the standard log via GLib's logging system.
+ * \param object A GObject associated with the log; this is printed in a special
+ *   way to make it easier to track messages from a specific object
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_trace_boxed(type, object, ...)
+ * \brief Logs a trace message to the standard log via GLib's logging system.
+ * \param type The type of \a object
+ * \param object A boxed object associated with the log; this is printed in a
+ *   special way to make it easier to track messages from a specific object.
+ *   For some object types, contents from the object are also printed (ex WpSpaPod)
+ * \param ... A format string, followed by format arguments in printf() style
+ */
+/*!
+ * \def wp_log(level, type, object, ...)
+ * \brief The generic form of all the logging macros
+ * \remark Don't use this directly, use one of the other logging macros
+ */
+/*! \} */
+
 static GString *spa_dbg_str = NULL;
 #define spa_debug(...) \
 ({ \
@@ -220,14 +366,12 @@ extract_common_fields (struct common_fields *cf, const GLogField *fields,
   }
 }
 
-/**
+/*!
- * wp_log_level_is_enabled:
+ * \brief Use this to figure out if a debug message is going to be printed or not,
- * @log_level: a log level
- *
- * Use this to figure out if a debug message is going to be printed or not,
  * so that you can avoid allocating resources just for debug logging purposes
- *
+ * \ingroup wplog
- * Returns: whether the log level is currently enabled
+ * \param log_level a log level
+ * \returns whether the log level is currently enabled
  */
 gboolean
 wp_log_level_is_enabled (GLogLevelFlags log_level)
@@ -235,12 +379,11 @@ wp_log_level_is_enabled (GLogLevelFlags log_level)
   return log_level_index (log_level) <= enabled_level;
 }
 
-/**
+/*!
- * wp_log_set_level:
+ * \brief Configures the log level and enabled categories
- * @level_str: a log level description string as it would appear in the
+ * \ingroup wplog
+ * \param level_str a log level description string as it would appear in the
  *   WIREPLUMBER_DEBUG environment variable "level:category1,category2"
- *
- * Configures the log level and enabled categories
  */
 void
 wp_log_set_level (const gchar * level_str)
@@ -289,15 +432,12 @@ wp_log_set_level (const gchar * level_str)
     pw_free_strv (tokens);
 }
 
-/**
+/*!
- * wp_log_writer_default:
+ * \brief WirePlumber's GLogWriterFunc
- *
- * WirePlumber's
- * <a href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#GLogWriterFunc">
- * GLogWriterFunc</a>
  *
  * This is installed automatically when you call wp_init() with
- * %WP_INIT_SET_GLIB_LOG set in the flags
+ * WP_INIT_SET_GLIB_LOG set in the flags
+ * \ingroup wplog
  */
 GLogWriterOutput
 wp_log_writer_default (GLogLevelFlags log_level,
@@ -365,10 +505,9 @@ wp_log_writer_default (GLogLevelFlags log_level,
   return G_LOG_WRITER_HANDLED;
 }
 
-/**
+/*!
- * wp_log_structured_standard:
+ * \brief Used internally by the debug logging macros. Avoid using it directly.
- *
+ * \ingroup wplog
- * Used internally by the debug logging macros. Avoid using it directly.
  */
 void
 wp_log_structured_standard (
@@ -476,15 +615,12 @@ static struct spa_log wp_spa_log = {
   .level = SPA_LOG_LEVEL_WARN,
 };
 
-/**
+/*!
- * wp_spa_log_get_instance:
+ * \ingroup wplog
- *
+ * \returns WirePlumber's instance of `spa_log`, which can be used to redirect
- * Returns: WirePlumber's instance of `spa_log`, which can be used to redirect
+ *   PipeWire's log messages to the currently installed GLogWriterFunc.
- *   PipeWire's log messages to the currently installed
- * <a href="https://developer.gnome.org/glib/stable/glib-Message-Logging.html#GLogWriterFunc">
- * GLogWriterFunc</a>.
  *   This is installed automatically when you call wp_init() with
- *   %WP_INIT_SET_PW_LOG set in the flags
+ *   WP_INIT_SET_PW_LOG set in the flags
  */
 struct spa_log *
 wp_spa_log_get_instance (void)

lib/wp/metadata.c

@@ -6,9 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file metadata.c
- */
 #define G_LOG_DOMAIN "wp-metadata"
 
 #include "metadata.h"
@@ -20,31 +17,39 @@
 #include <pipewire/pipewire.h>
 #include <pipewire/extensions/metadata.h>
 
+/*! \defgroup wpmetadata WpMetadata */
 /*!
- * @memberof WpMetadata
+ * \struct WpMetadata
  *
- * @signal @b changed
+ * The WpMetadata class allows accessing the properties and methods of
+ * PipeWire metadata object (`struct pw_metadata`).
  *
- * @code
+ * A WpMetadata is constructed internally when a new metadata object appears on the
+ * PipeWire registry and it is made available through the WpObjectManager API.
+ *
+ * \gsignals
+ *
+ * \par changed
+ * \parblock
+ * \code
+ * void
  * changed_callback (WpMetadata * self,
  *                   guint object,
- *                   gchar * p0,
+ *                   gchar * key,
- *                   gchar * p1,
+ *                   gchar * type,
- *                   gchar * p2,
+ *                   gchar * value,
  *                   gpointer user_data)
- * @endcode
+ * \endcode
+ * Emited when metadata change
  *
  * Parameters:
+ * - `subject` - the metadata subject id
+ * - `key` - the metadata key
+ * - `type` - the value type
+ * - `value` - the metadata value
  *
- * @arg `self`
+ * Flags: G_SIGNAL_RUN_LAST
- * @arg `object`
+ * \endparblock
- * @arg `p0`
- * @arg `p1`
- * @arg `p2`
- * @arg `user_data`
- *
- * Flags: Run Last
- *
  */
 enum {
   SIGNAL_CHANGED,
@@ -125,15 +130,6 @@ clear_items (struct pw_array * metadata)
   pw_array_reset (metadata);
 }
 
-/*!
- * @struct WpMetadata
- * @section metadata_section Metadata
- *
- * @brief The [WpMetadata](@ref metadata_section) class allows accessing the properties and methods of
- * PipeWire metadata object (`struct pw_metadata`).
- *
- */
-
 typedef struct _WpMetadataPrivate WpMetadataPrivate;
 struct _WpMetadataPrivate
 {
@@ -390,23 +386,22 @@ static const WpIteratorMethods metadata_iterator_methods = {
 };
 
 /*!
- * @memberof WpMetadata
+ * \brief Iterates over metadata items that matches the given \a subject.
- * @param self: a metadata object
- * @param subject: the metadata subject id, or -1 (PW_ID_ANY)
  *
- * @brief Iterates over metadata items that matches the given @em subject. If no
+ * If no constraints are specified, the returned iterator iterates over all the
- * constraints are specified, the returned iterator iterates over all the
  * stored metadata.
  *
  * Note that this method works on cached metadata. When you change metadata
  * with wp_metadata_set(), this cache will be updated on the next round-trip
  * with the pipewire server.
  *
- * @returns (transfer full): an iterator that iterates over the found metadata.
+ * \ingroup wpmetadata
+ * \param self a metadata object
+ * \param subject the metadata subject id, or -1 (PW_ID_ANY)
+ * \returns (transfer full): an iterator that iterates over the found metadata.
  *   Use wp_metadata_iterator_item_extract() to parse the items returned by
  *   this iterator.
  */
-
 WpIterator *
 wp_metadata_new_iterator (WpMetadata * self, guint32 subject)
 {
@@ -427,22 +422,16 @@ wp_metadata_new_iterator (WpMetadata * self, guint32 subject)
 }
 
 /*!
- * @memberof WpMetadata
+ * \brief Extracts the metadata subject, key, type and value out of a
- * @param item: a
+ * GValue that was returned from the WpIterator of wp_metadata_find()
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue-struct">
- * GValue</a> that was returned from the [WpIterator](@ref iterator_section) of wp_metadata_find()
  *
- * @brief
+ * \ingroup wpmetadata
- * @param subject: (out)(optional): the subject id of the current item
+ * \param item a GValue that was returned from the WpIterator of wp_metadata_find()
- * @param key: (out)(optional)(transfer none): the key of the current item
+ * \param subject (out)(optional): the subject id of the current item
- * @param type: (out)(optional)(transfer none): the type of the current item
+ * \param key (out)(optional)(transfer none): the key of the current item
- * @param value: (out)(optional)(transfer none): the value of the current item
+ * \param type (out)(optional)(transfer none): the type of the current item
- *
+ * \param value (out)(optional)(transfer none): the value of the current item
- * Extracts the metadata subject, key, type and value out of a 
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue-struct">
- * GValue</a> that was returned from the [WpIterator](@ref iterator_section) of wp_metadata_find()
  */
-
 void
 wp_metadata_iterator_item_extract (const GValue * item, guint32 * subject,
     const gchar ** key, const gchar ** type, const gchar ** value)
@@ -460,17 +449,15 @@ wp_metadata_iterator_item_extract (const GValue * item, guint32 * subject,
 }
 
 /*!
- * @memberof WpMetadata
+ * \brief Finds the metadata value given its \a subject and \a key.
- * @param self: a metadata object
- * @param subject: the metadata subject id
- * @param key: the metadata key name
- * @param type: (out)(optional): the metadata type name
  *
- * @brief Finds the metadata value given its @em subject and &key.
+ * \ingroup wpmetadata
- *
+ * \param self a metadata object
- * @returns the metadata string value, or NULL if not found.
+ * \param subject the metadata subject id
+ * \param key the metadata key name
+ * \param type (out)(optional): the metadata type name
+ * \returns the metadata string value, or NULL if not found.
  */
-
 const gchar *
 wp_metadata_find (WpMetadata * self, guint32 subject, const gchar * key,
   const gchar ** type)
@@ -491,19 +478,18 @@ wp_metadata_find (WpMetadata * self, guint32 subject, const gchar * key,
 }
 
 /*!
- * @memberof WpMetadata
+ * \brief Sets the metadata associated with the given \a subject and \a key.
- * @param self: the metadata object
+ * Use NULL as a value to unset the given \a key and use NULL in both \a key
- * @param subject: the subject id for which this metadata property is being set
+ * and \a value to remove all metadata associated with the given \a subject.
- * @param key: (nullable): the key to set, or %NULL to remove all metadata for
- *   @em subject
- * @param type: (nullable): the type of the value; %NULL is synonymous to "string"
- * @param value: (nullable): the value to set, or %NULL to unset the given @em key
  *
- * @brief Sets the metadata associated with the given @em subject and @em key. Use %NULL as
+ * \ingroup wpmetadata
- * a value to unset the given @em key and use %NULL in both @em key and @em value to
+ * \param self the metadata object
- * remove all metadata associated with the given @em subject.
+ * \param subject the subject id for which this metadata property is being set
+ * \param key (nullable): the key to set, or NULL to remove all metadata for
+ *   \a subject
+ * \param type (nullable): the type of the value; NULL is synonymous to "string"
+ * \param value (nullable): the value to set, or NULL to unset the given \a key
  */
-
 void
 wp_metadata_set (WpMetadata * self, guint32 subject,
     const gchar * key, const gchar * type, const gchar * value)
@@ -513,12 +499,10 @@ wp_metadata_set (WpMetadata * self, guint32 subject,
 }
 
 /*!
- * @memberof WpMetadata
+ * \brief Clears permanently all stored metadata.
- * @param self: the metadata object
+ * \ingroup wpmetadata
- *
+ * \param self the metadata object
- * @brief Clears permanently all stored metadata.
  */
-
 void
 wp_metadata_clear (WpMetadata * self)
 {
@@ -527,9 +511,11 @@ wp_metadata_clear (WpMetadata * self)
 }
 
 /*!
- * @struct WpImplMetadata
+ * \struct WpImplMetadata
- * @memberof WpMetadata
+ * Implementation of the metadata object.
- * @section impl_metadata_section WpImplMetadata
+ *
+ * Activate this object with at least WP_PROXY_FEATURE_BOUND to export it to
+ * PipeWire.
  */
 struct _WpImplMetadata
 {
@@ -709,14 +695,10 @@ wp_impl_metadata_class_init (WpImplMetadataClass * klass)
 }
 
 /*!
- * @memberof WpMetadata
+ * \ingroup wpmetadata
- *
+ * \param core the core
- * @param core: the core
+ * \returns (transfer full): a new WpImplMetadata
- *
- * @returns (transfer full): a new [WpImplMetadata](@ref impl_metadata_section)
- *
  */
-
 WpImplMetadata *
 wp_impl_metadata_new (WpCore * core)
 {
@@ -725,4 +707,4 @@ wp_impl_metadata_new (WpCore * core)
   return g_object_new (WP_TYPE_IMPL_METADATA,
       "core", core,
       NULL);
-}
+}

lib/wp/metadata.h

@@ -14,40 +14,23 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpMetadata
+ * \brief An extension of WpProxyFeatures for WpMetadata objects
- *
+ * \ingroup wpmetadata
- * @brief
- * @em WP_METADATA_FEATURE_DATA: caches metadata locally
- *
- * An extension of [WpProxyFeatures](@ref proxy_features_section)
  */
 typedef enum { /*< flags >*/
+  /*! caches metadata locally */
   WP_METADATA_FEATURE_DATA = (WP_PROXY_FEATURE_CUSTOM_START << 0),
 } WpMetadataFeatures;
 
 /*!
- * @memberof WpMetadata
+ * \brief The WpMetadata GType
- *
+ * \ingroup wpmetadata
- * @brief The [WpMetadata](@ref metadata_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_METADATA (wp_metadata_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_METADATA (wp_metadata_get_type ())
 
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpMetadata, wp_metadata, WP, METADATA, WpGlobalProxy)
 
-/*!
- * @memberof WpMetadata
- *
- * @brief
- * @em parent_class
- */
 struct _WpMetadataClass
 {
   WpGlobalProxyClass parent_class;
@@ -72,16 +55,8 @@ WP_API
 void wp_metadata_clear (WpMetadata * self);
 
 /*!
- * @memberof WpMetadata
+ * \brief The WpImplMetadata GType
- *
+ * \ingroup wpmetadata
- * @brief The [WpImplMetadata](@ref impl_metadata_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_IMPL_METADATA (wp_impl_metadata_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_IMPL_METADATA (wp_impl_metadata_get_type ())
 

lib/wp/node.c

@@ -6,9 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file node.c
- */
 #define G_LOG_DOMAIN "wp-node"
 
 #include "node.h"
@@ -20,47 +17,56 @@
 
 #include <pipewire/impl.h>
 
+/*! \defgroup wpnode WpNode */
 /*!
- * @memberof WpNode
+ * \struct WpNode
  *
- * @signal @b ports-changed
+ * The WpNode class allows accessing the properties and methods of a
+ * PipeWire node object (`struct pw_node`).
  *
- * @code
+ * A WpNode is constructed internally when a new node appears on the
+ * PipeWire registry and it is made available through the WpObjectManager API.
+ * Alternatively, a WpNode can also be constructed using
+ * wp_node_new_from_factory(), which creates a new node object
+ * on the remote PipeWire server by calling into a factory.
+ *
+ * \gsignals
+ *
+ * \par ports-changed
+ * \parblock
+ * \code
+ * void
  * ports_changed_callback (WpNode * self,
  *                         gpointer user_data)
- * @endcode
+ * \endcode
  *
- * Emitted when the node's ports change. This is only emitted when %WP_NODE_FEATURE_PORTS is enabled.
+ * Emitted when the node's ports change. This is only emitted when
+ * WP_NODE_FEATURE_PORTS is enabled.
  *
- * @b Parameters:
+ * Flags: G_SIGNAL_RUN_LAST
+ * \endparblock
  *
- * @arg `self` - the node
+ * \par state-changed
- * @arg `user_data`
+ * \parblock
- *
+ * \code
- * Flags: Run Last
+ * void
- *
- * @signal @b state-changed
- *
- * @code
  * state_changed_callback (WpNode * self,
  *                         WpNodeState * old_state,
  *                         WpNodeState * new_state,
  *                         gpointer user_data)
- * @endcode
+ * \endcode
  *
  * Emitted when the node changes state. This is only emitted when
- * %WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
+ * WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
  *
- * @b Parameters:
+ * Parameters:
- *
+ * - `old_state` - the old state
- * @arg `self` - the node
+ * - `new_state` - the new state
- * @arg `old_state` - the old state
- * @arg `new_state` - the new state
- * @arg `user_data`
- *
- * Flags: Run Last
  *
+ * Flags: G_SIGNAL_RUN_LAST
+ * \endparblock
  */
+
 enum {
   SIGNAL_STATE_CHANGED,
   SIGNAL_PORTS_CHANGED,
@@ -69,26 +75,6 @@ enum {
 
 static guint32 signals[N_SIGNALS] = {0};
 
-/*!
- * 
- * @struct WpNode
- * @section node_section Node
- *
- * @brief The [WpNode](@ref node_section) class allows accessing the properties and methods of a
- * PipeWire node object (`struct pw_node`).
- *
- * A [WpNode](@ref node_section) is constructed internally when a new node appears on the
- * PipeWire registry and it is made available through the [WpObjectManager](@ref object_manager_section) API.
- * Alternatively, a [WpNode](@ref node_section) can also be constructed using
- * wp_node_new_from_factory(), which creates a new node object
- * on the remote PipeWire server by calling into a factory.
- *
- */
-/*!
- * @brief
- * @em parent
- * @em ports_om
- */
 struct _WpNode
 {
   WpGlobalProxy parent;
@@ -245,26 +231,11 @@ wp_node_class_init (WpNodeClass * klass)
 
   wp_pw_object_mixin_class_override_properties (object_class);
 
-  /*
-   * WpNode::state-changed:
-   * @self: the node
-   * @old_state: the old state
-   * @new_state: the new state
-   *
-   * @brief Emitted when the node changes state. This is only emitted
-   * when %WP_PIPEWIRE_OBJECT_FEATURE_INFO is enabled.
-   */
   signals[SIGNAL_STATE_CHANGED] = g_signal_new (
       "state-changed", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 2,
       WP_TYPE_NODE_STATE, WP_TYPE_NODE_STATE);
 
-  /*
-   * WpNode::ports-changed:
-   *
-   * @brief Emitted when the node's ports change. This is only emitted
-   * when %WP_NODE_FEATURE_PORTS is enabled.
-   */
   signals[SIGNAL_PORTS_CHANGED] = g_signal_new (
       "ports-changed", G_TYPE_FROM_CLASS (klass),
       G_SIGNAL_RUN_LAST, 0, NULL, NULL, NULL, G_TYPE_NONE, 0);
@@ -312,25 +283,24 @@ wp_node_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpNode
+ * \brief Constructs a node on the PipeWire server by asking the remote factory
- * @param core: the wireplumber core
+ * \a factory_name to create it.
- * @param factory_name: the pipewire factory name to construct the node
- * @param properties: (nullable) (transfer full): the properties to pass to the factory
- *
- * @brief Constructs a node on the PipeWire server by asking the remote factory
- * @em param factory_name to create it.
  *
  * Because of the nature of the PipeWire protocol, this operation completes
  * asynchronously at some point in the future. In order to find out when
  * this is done, you should call wp_object_activate(), requesting at least
- * %WP_PROXY_FEATURE_BOUND. When this feature is ready, the node is ready for
+ * WP_PROXY_FEATURE_BOUND. When this feature is ready, the node is ready for
  * use on the server. If the node cannot be created, this activation operation
  * will fail.
  *
- * @returns (nullable) (transfer full): the new node or %NULL if the core
+ * \ingroup wpnode
+ * \param core the wireplumber core
+ * \param factory_name the pipewire factory name to construct the node
+ * \param properties (nullable) (transfer full): the properties to pass to the
+ *   factory
+ * \returns (nullable) (transfer full): the new node or NULL if the core
  *   is not connected and therefore the node cannot be created
  */
-
 WpNode *
 wp_node_new_from_factory (WpCore * core,
     const gchar * factory_name, WpProperties * properties)
@@ -344,13 +314,11 @@ wp_node_new_from_factory (WpCore * core,
 }
 
 /*!
- * @memberof WpNode
+ * \ingroup wpnode
- * @param self: the node
+ * \param self the node
- * @param error: the error
+ * \param error the error
- *
+ * \returns the current state of the node
- * @returns the current state of the node
  */
-
 WpNodeState
 wp_node_get_state (WpNode * self, const gchar ** error)
 {
@@ -367,15 +335,15 @@ wp_node_get_state (WpNode * self, const gchar ** error)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets the number of input ports of this node
- * @param self: the node
- * @param max: (out) (optional): the maximum supported number of input ports
  *
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remarks Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns the number of input ports of this node, as reported by the node info
+ * \ingroup wpnode
+ * \param self the node
+ * \param max (out) (optional): the maximum supported number of input ports
+ * \returns the number of input ports of this node, as reported by the node info
  */
-
 guint
 wp_node_get_n_input_ports (WpNode * self, guint * max)
 {
@@ -392,15 +360,15 @@ wp_node_get_n_input_ports (WpNode * self, guint * max)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets the number of output ports of this node
- * @param self: the node
- * @param max: (out) (optional): the maximum supported number of output ports
  *
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remarks Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns the number of output ports of this node, as reported by the node info
+ * \ingroup wpnode
+ * \param self the node
+ * \param max (out) (optional): the maximum supported number of output ports
+ * \returns the number of output ports of this node, as reported by the node info
  */
-
 guint
 wp_node_get_n_output_ports (WpNode * self, guint * max)
 {
@@ -417,18 +385,20 @@ wp_node_get_n_output_ports (WpNode * self, guint * max)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets the number of ports of this node
- * @param self: the node
  *
- * @brief Requires %WP_NODE_FEATURE_PORTS
+ * Note that this number may not add up to
+ * wp_node_get_n_input_ports() + wp_node_get_n_output_ports()
+ * because it is discovered by looking at the number of available ports
+ * in the registry, however ports may appear there with a delay or may
+ * not appear at all if this client does not have permission to read them
  *
- * @returns the number of ports of this node. Note that this number may not
+ * \remarks Requires WP_NODE_FEATURE_PORTS
- *   add up to wp_node_get_n_input_ports() + wp_node_get_n_output_ports()
+ *
- *   because it is discovered by looking at the number of available ports
+ * \ingroup wpnode
- *   in the registry, however ports may appear there with a delay or may
+ * \param self the node
- *   not appear at all if this client does not have permission to read them
+ * \returns the number of ports of this node.
  */
-
 guint
 wp_node_get_n_ports (WpNode * self)
 {
@@ -440,15 +410,15 @@ wp_node_get_n_ports (WpNode * self)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets a new iterator that iterates over all the ports that belong
- * @param self: the node
+ * to this node
  *
- * @brief Requires %WP_NODE_FEATURE_PORTS
+ * \remarks Requires WP_NODE_FEATURE_PORTS
  *
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
+ * \ingroup wpnode
- *   the ports that belong to this node
+ * \param self the node
+ * \returns (transfer full): a WpIterator that iterates over WpPort objects
  */
-
 WpIterator *
 wp_node_new_ports_iterator (WpNode * self)
 {
@@ -460,19 +430,19 @@ wp_node_new_ports_iterator (WpNode * self)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets a new iterator that iterates over all
- * @param self: the node
+ * the ports that belong to this node and match the constraints
- * @...: a list of constraints, terminated by %NULL
- *
- * @brief Requires %WP_NODE_FEATURE_PORTS
  *
  * The constraints specified in the variable arguments must follow the rules
  * documented in wp_object_interest_new().
  *
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
+ * \remarks Requires WP_NODE_FEATURE_PORTS
- *   the ports that belong to this node and match the constraints
+ *
+ * \ingroup wpnode
+ * \param self the node
+ * \param ... a list of constraints, terminated by NULL
+ * \returns (transfer full): a WpIterator that iterates over WpPort objects
  */
-
 WpIterator *
 wp_node_new_ports_filtered_iterator (WpNode * self, ...)
 {
@@ -485,16 +455,16 @@ wp_node_new_ports_filtered_iterator (WpNode * self, ...)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Gets a new iterator that iterates over all
- * @param self: the node
+ * the ports that belong to this node and match the \a interest
- * @param interest: (transfer full): the interest
  *
- * @brief Requires %WP_NODE_FEATURE_PORTS
+ * \remarks Requires WP_NODE_FEATURE_PORTS
  *
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all
+ * \ingroup wpnode
- *   the ports that belong to this node and match the @em interest
+ * \param self the node
+ * \param interest (transfer full): the interest
+ * \returns (transfer full): a WpIterator that iterates over WpPort objects
  */
-
 WpIterator *
 wp_node_new_ports_filtered_iterator_full (WpNode * self,
     WpObjectInterest * interest)
@@ -508,19 +478,19 @@ wp_node_new_ports_filtered_iterator_full (WpNode * self,
 }
 
 /*!
- * @memberof WpNode
+ * \brief Retrieves the first port that matches the constraints
- * @param self: the node
- * @...: a list of constraints, terminated by %NULL
- *
- * @brief Requires %WP_NODE_FEATURE_PORTS
  *
  * The constraints specified in the variable arguments must follow the rules
  * documented in wp_object_interest_new().
  *
- * @returns (transfer full) (nullable): the first port that matches the
+ * \remarks Requires WP_NODE_FEATURE_PORTS
- *    constraints, or %NULL if there is no such port
+ *
+ * \ingroup wpnode
+ * \param self the node
+ * \param ... a list of constraints, terminated by NULL
+ * \returns (transfer full) (nullable): the first port that matches the
+ *    constraints, or NULL if there is no such port
  */
-
 WpPort *
 wp_node_lookup_port (WpNode * self, ...)
 {
@@ -533,16 +503,16 @@ wp_node_lookup_port (WpNode * self, ...)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Retrieves the first port that matches the \a interest
- * @param self: the node
- * @param interest: (transfer full): the interest
  *
- * @brief Requires %WP_NODE_FEATURE_PORTS
+ * \remarks Requires WP_NODE_FEATURE_PORTS
  *
- * @returns (transfer full) (nullable): the first port that matches the
+ * \ingroup wpnode
- *    @em interest, or %NULL if there is no such port
+ * \param self the node
+ * \param interest (transfer full): the interest
+ * \returns (transfer full) (nullable): the first port that matches the
+ *    \a interest, or NULL if there is no such port
  */
-
 WpPort *
 wp_node_lookup_port_full (WpNode * self, WpObjectInterest * interest)
 {
@@ -555,16 +525,17 @@ wp_node_lookup_port_full (WpNode * self, WpObjectInterest * interest)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Sends a command to a node
- * @param self: the node
- * @param command: the command
  *
- * returns Void
+ * Valid commands are the short string reprepsentations of
+ * `enum spa_node_command`. For example, "Suspend" or "Flush" are valid commands
  *
- * @brief Sends a command to a node
+ * \ingroup wpnode
+ * \param self the node
+ * \param command the command
  */
-
+void
-void wp_node_send_command (WpNode * self, const gchar * command)
+wp_node_send_command (WpNode * self, const gchar * command)
 {
   WpSpaIdValue command_value = wp_spa_id_value_from_short_name (
       "Spa:Pod:Object:Command:Node", command);
@@ -577,32 +548,12 @@ void wp_node_send_command (WpNode * self, const gchar * command)
   pw_node_send_command (wp_proxy_get_pw_proxy (WP_PROXY (self)), &cmd);
 }
 
-/*!
+/*! \defgroup wpimplnode WpImplNode */
- * @memberof WpImplNode
+
- *
- * @props @b pw-impl-node
- *
- * @code
- * "pw-impl-node" gpointer
- * @endcode
- *
- * Flags : Read / Write / Construct Only
- */
 enum {
   PROP_PW_IMPL_NODE = WP_PW_OBJECT_MIXIN_PROP_CUSTOM_START,
 };
 
-/*!
- * @struct WpImplNode:
- * @memberof WpNode
- * @section impl_node_section WpImplNode
- *
- * @brief A [WpImplNode](@ref impl_node_section) allows running a node
- * implementation (`struct pw_impl_node`) locally,
- * loading the implementation from factory or wrapping a manually
- * constructed `pw_impl_node`. This object can then be exported to PipeWire
- * by requesting %WP_PROXY_FEATURE_BOUND.
- */
 struct _WpImplNode
 {
   WpProxy parent;
@@ -739,6 +690,19 @@ wp_impl_node_activate_execute_step (WpObject * object,
   }
 }
 
+/*!
+ * \struct WpImplNode
+ *
+ * A WpImplNode allows running a node implementation (`struct pw_impl_node`)
+ * locally, loading the implementation from factory or wrapping a manually
+ * constructed `pw_impl_node`. This object can then be exported to PipeWire
+ * by requesting WP_PROXY_FEATURE_BOUND.
+ *
+ * \gproperties
+ *
+ * \gproperty{pw-impl-node, gpointer, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The actual node implementation\, `struct pw_impl_node *`}
+ */
 static void
 wp_impl_node_class_init (WpImplNodeClass * klass)
 {
@@ -807,13 +771,11 @@ wp_impl_node_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpNode
+ * \ingroup wpimplnode
- * @param core: the wireplumber core
+ * \param core the wireplumber core
- * @param node: an existing pw_impl_node to wrap
+ * \param node an existing pw_impl_node to wrap
- *
+ * \returns (transfer full): A new WpImplNode wrapping \a node
- * @returns (transfer full): A new [WpImplNode](@ref impl_node_section) wrapping @em node
  */
-
 WpImplNode *
 wp_impl_node_new_wrap (WpCore * core, struct pw_impl_node * node)
 {
@@ -824,24 +786,22 @@ wp_impl_node_new_wrap (WpCore * core, struct pw_impl_node * node)
 }
 
 /*!
- * @memberof WpNode
+ * \brief Constructs a new node, locally on this process, using the specified
- * @param core: the wireplumber core
+ * \a factory_name.
- * @param factory_name: the name of the pipewire factory
- * @param properties: (nullable) (transfer full): properties to be passed to node
- *    constructor
- *
- * @brief Constructs a new node, locally on this process, using the specified
- * @em factory_name.
  *
  * To export this node to the PipeWire server, you need to call
- * wp_object_activate() requesting %WP_PROXY_FEATURE_BOUND and
+ * wp_object_activate() requesting WP_PROXY_FEATURE_BOUND and
  * wait for the operation to complete.
  *
- * @returns (nullable) (transfer full): A new [WpImplNode](@ref impl_node_section) wrapping the
+ * \ingroup wpimplnode
+ * \param core the wireplumber core
+ * \param factory_name the name of the pipewire factory
+ * \param properties (nullable) (transfer full): properties to be passed to node
+ *    constructor
+ * \returns (nullable) (transfer full): A new WpImplNode wrapping the
  *   node that was constructed by the factory, or %NULL if the factory
  *   does not exist or was unable to construct the node
  */
-
 WpImplNode *
 wp_impl_node_new_from_pw_factory (WpCore * core,
     const gchar * factory_name, WpProperties * properties)
@@ -868,4 +828,4 @@ wp_impl_node_new_from_pw_factory (WpCore * core,
   }
 
   return wp_impl_node_new_wrap (core, node);
-}
+}

lib/wp/node.h

@@ -19,48 +19,36 @@ G_BEGIN_DECLS
 struct pw_impl_node;
 
 /*!
- * @memberof WpNode
+ * \brief The state of the node
- *
+ * \ingroup wpnode
- * @brief
- * @arg WP_NODE_STATE_ERROR: error state
- * @arg WP_NODE_STATE_CREATING: the node is being created
- * @arg WP_NODE_STATE_SUSPENDED: the node is suspended, the device might be closed
- * @arg WP_NODE_STATE_IDLE: the node is running but there is no active port
- * @arg WP_NODE_STATE_RUNNING: the node is running
  */
 typedef enum {
+  /*! error state */
   WP_NODE_STATE_ERROR = -1,
+  /*! the node is being created */
   WP_NODE_STATE_CREATING = 0,
+  /*! the node is suspended, the device might be closed */
   WP_NODE_STATE_SUSPENDED = 1,
+  /*! the node is running but there is no active port */
   WP_NODE_STATE_IDLE = 2,
+  /*! the node is running */
   WP_NODE_STATE_RUNNING = 3,
 } WpNodeState;
 
 /*!
- * @memberof WpNode
+ * \brief An extension of WpProxyFeatures
- *
+ * \ingroup wpnode
- * @brief
- * @arg WP_NODE_FEATURE_PORTS: caches information about ports, enabling
- *   the use of wp_node_get_n_ports(), wp_node_lookup_port(),
- *   wp_node_new_ports_iterator() and related methods
- *
- * An extension of [WpProxyFeatures](@ref proxy_features_section)
  */
 typedef enum { /*< flags >*/
+  /*! caches information about ports, enabling
+   * the use of wp_node_get_n_ports(), wp_node_lookup_port(),
+   * wp_node_new_ports_iterator() and related methods */
   WP_NODE_FEATURE_PORTS = (WP_PROXY_FEATURE_CUSTOM_START << 0),
 } WpNodeFeatures;
 
 /*!
- * @memberof WpNode
+ * \brief The WpNode GType
- *
+ * \ingroup wpnode
- * @brief The [WpNode](@ref node_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_NODE (wp_node_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_NODE (wp_node_get_type ())
 WP_API
@@ -103,16 +91,8 @@ WP_API
 void wp_node_send_command (WpNode * self, const gchar *command);
 
 /*!
- * @memberof WpNode
+ * \brief The WpImplNode GType
- *
+ * \ingroup wpimplnode
- * @brief The [WpImplNode](@ref impl_node_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_IMPL_NODE (wp_impl_node_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_IMPL_NODE (wp_impl_node_get_type ())
 WP_API

lib/wp/object-interest.c

@@ -6,9 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file object-interest.c
- */
 #define G_LOG_DOMAIN "wp-object-interest"
 
 #include "object-interest.h"
@@ -20,6 +17,19 @@
 
 #include <pipewire/pipewire.h>
 
+/*! \defgroup wpobjectinterest WpObjectInterest */
+/*!
+ * \struct WpObjectInterest
+ *
+ * An object interest is a helper that is used in WpObjectManager to
+ * declare interest in certain kinds of objects.
+ *
+ * An interest is defined by a GType and a set of constraints on the object's
+ * properties. An object "matches" the interest if it is of the specified
+ * GType (either the same type or a descendant of it) and all the constraints
+ * are satisfied.
+ */
+
 struct constraint
 {
   WpConstraintType type;
@@ -29,30 +39,6 @@ struct constraint
   GVariant *value;
 };
 
-/*!
- * @struct WpObjectInterest
- *
- * @section object_interest_section Object Interest
- *
- * @brief An object interest is a helper that is used in
- * [WpObjectManager](@ref object_manager_section) to
- * declare interest in certain kinds of objects.
- *
- * An interest is defined by a
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a> and a set of constraints on the object's
- * properties. An object "matches" the interest if it is of the specified
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a> (either the same type or a descendant of it) and all the constraints
- * are satisfied.
- */
-/*!
- * @brief
- * @em ref
- * @em valid
- * @em gtype
- * @em constraints
- */
 struct _WpObjectInterest
 {
   grefcount ref;
@@ -65,59 +51,52 @@ G_DEFINE_BOXED_TYPE (WpObjectInterest, wp_object_interest,
                      wp_object_interest_copy, wp_object_interest_unref)
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Creates a new interest that declares interest in objects of the specified
- * @param gtype: the type of the object to declare interest in, ... a set of constraints, terminated with %NULL
+ * \a gtype, with the constraints specified in the variable arguments.
  *
- * @brief Creates a new interest that declares interest in objects of the specified
+ * The variable arguments should be a list of constraints terminated with NULL,
- * @em gtype, with the constraints specified in the variable arguments.
- *
- * The variable arguments should be a list of constraints terminated with %NULL,
  * where each constraint consists of the following arguments:
- *  - a [WpConstraintType](@ref constraint_type_section): the constraint type
+ *  - a `WpConstraintType`: the constraint type
  *  - a `const gchar *`: the subject name
  *  - a `const gchar *`: the format string
  *  - 0 or more arguments according to the format string
  *
  * The format string is interpreted as follows:
  *  - the first character is the constraint verb:
- *     - `=`: %WP_CONSTRAINT_VERB_EQUALS
+ *     - `=`: WP_CONSTRAINT_VERB_EQUALS
- *     - `!`: %WP_CONSTRAINT_VERB_NOT_EQUALS
+ *     - `!`: WP_CONSTRAINT_VERB_NOT_EQUALS
- *     - `c`: %WP_CONSTRAINT_VERB_IN_LIST
+ *     - `c`: WP_CONSTRAINT_VERB_IN_LIST
- *     - `~`: %WP_CONSTRAINT_VERB_IN_RANGE
+ *     - `~`: WP_CONSTRAINT_VERB_IN_RANGE
- *     - `#`: %WP_CONSTRAINT_VERB_MATCHES
+ *     - `#`: WP_CONSTRAINT_VERB_MATCHES
- *     - `+`: %WP_CONSTRAINT_VERB_IS_PRESENT
+ *     - `+`: WP_CONSTRAINT_VERB_IS_PRESENT
- *     - `-`: %WP_CONSTRAINT_VERB_IS_ABSENT
+ *     - `-`: WP_CONSTRAINT_VERB_IS_ABSENT
- *  - the rest of the characters are interpreted as a
+ *  - the rest of the characters are interpreted as a GVariant format string,
- * <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
- * GVariant</a> format string,
  *    as it would be used in g_variant_new()
  *
  * The rest of this function's arguments up to the start of the next constraint
- * depend on the
+ * depend on the GVariant format part of the format string and are used to
- * <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
+ * construct a GVariant for the constraint's value argument.
- * GVariant</a> format part of the format string and are used to
- * construct a
- * <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
- * GVariant</a> for the constraint's value argument.
  *
  * For further reading on the constraint's arguments, see
  * wp_object_interest_add_constraint()
  *
- * For example, this interest matches objects that are descendands of [WpProxy](@ref proxy_section)
+ * For example, this interest matches objects that are descendands of WpProxy
  * with a "bound-id" between 0 and 100 (inclusive), with a pipewire property
  * called "format.dsp" that contains the string "audio" somewhere in the value
  * and with a pipewire property "port.name" being present (with any value):
- * |[
+ * \code
  * interest = wp_object_interest_new (WP_TYPE_PROXY,
  *     WP_CONSTRAINT_TYPE_G_PROPERTY, "bound-id", "~(uu)", 0, 100,
  *     WP_CONSTRAINT_TYPE_PW_PROPERTY, "format.dsp", "#s", "*audio*",
  *     WP_CONSTRAINT_TYPE_PW_PROPERTY, "port.name", "+",
  *     NULL);
- * ]|
+ * \endcode
  *
- * @returns (transfer full): the new object interest
+ * \ingroup wpobjectinterest
+ * \param gtype the type of the object to declare interest in
+ * \param ... a set of constraints, terminated with NULL
+ * \returns (transfer full): the new object interest
  */
-
 WpObjectInterest *
 wp_object_interest_new (GType gtype, ...)
 {
@@ -130,15 +109,13 @@ wp_object_interest_new (GType gtype, ...)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief va_list version of wp_object_interest_new()
- * @param gtype: the type of the object to declare interest in
- * @param args: pointer to va_list containing the constraints
  *
- * @brief va_list version of wp_object_interest_new()
+ * \ingroup wpobjectinterest
- *
+ * \param gtype the type of the object to declare interest in
- * @returns (transfer full): the new object interest
+ * \param args pointer to va_list containing the constraints
+ * \returns (transfer full): the new object interest
  */
-
 WpObjectInterest *
 wp_object_interest_new_valist (GType gtype, va_list *args)
 {
@@ -171,16 +148,16 @@ wp_object_interest_new_valist (GType gtype, va_list *args)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Creates a new interest that declares interest in objects of the
- * @param gtype: the type of the object to declare interest in
+ * specified \a gtype, without any property constraints.
  *
- * @brief Creates a new interest that declares interest in objects of the specified
+ * To add property constraints, you can call wp_object_interest_add_constraint()
- * @em gtype, without any property constraints. To add property constraints,
+ * afterwards.
- * you can call wp_object_interest_add_constraint() afterwards.
  *
- * @returns (transfer full): the new object interest
+ * \ingroup wpobjectinterest
+ * \param gtype the type of the object to declare interest in
+ * \returns (transfer full): the new object interest
  */
-
 WpObjectInterest *
 wp_object_interest_new_type (GType gtype)
 {
@@ -193,54 +170,43 @@ wp_object_interest_new_type (GType gtype)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Adds a constraint to this interest. Constraints consist of a \a type,
- * @param self: the object interest
+ * a \a subject, a \a verb and, depending on the \a verb, a \a value.
- * @param type: the constraint type
- * @param subject: the subject that the constraint applies to
- * @param verb: the operation that is performed to check the constraint
- * @param value: (transfer floating)(nullable): the value to check for
- *
- * @brief Adds a constraint to this interest. Constraints consist of a @em type,
- * a @em subject, a @em verb and, depending on the @em verb, a @em value.
  *
  * Constraints are almost like a spoken language sentence that declare a
  * condition that must be true in order to consider that an object can match
  * this interest. For instance, a constraint can be "pipewire property
  * 'object.id' equals 10". This would be translated to:
- * |[
+ * \code
  * wp_object_interest_add_constraint (i,
  *    WP_CONSTRAINT_TYPE_PW_PROPERTY, "object.id",
  *    WP_CONSTRAINT_VERB_EQUALS, g_variant_new_int (10));
- * ]|
+ * \endcode
  *
- * Some verbs require a @em value and some others do not. For those that do,
+ * Some verbs require a \a value and some others do not. For those that do,
- * the @em value must be of a specific type:
+ * the \a value must be of a specific type:
- *  - %WP_CONSTRAINT_VERB_EQUALS: @em value can be a string, a (u)int32,
+ *  - WP_CONSTRAINT_VERB_EQUALS: \a value can be a string, a (u)int32,
- *    a (u)int64, a double or a boolean. The @em subject value must equal this
+ *    a (u)int64, a double or a boolean. The \a subject value must equal this
  *    value for the constraint to be satisfied
- *  - %WP_CONSTRAINT_VERB_IN_LIST: @em value must be a tuple that contains any
+ *  - WP_CONSTRAINT_VERB_IN_LIST: \a value must be a tuple that contains any
  *    number of items of the same type; the items can be string, (u)int32,
- *    (u)int64 or double. These items make a list that the @em subject's value
+ *    (u)int64 or double. These items make a list that the \a subject's value
- *    will be checked against. If any of the items equals the @em subject value,
+ *    will be checked against. If any of the items equals the \a subject value,
  *    the constraint is satisfied
- *  - %WP_CONSTRAINT_VERB_IN_RANGE: @em value must be a tuple that contains exactly
+ *  - WP_CONSTRAINT_VERB_IN_RANGE: \a value must be a tuple that contains exactly
  *    2 numbers of the same type ((u)int32, (u)int64 or double), meaning the
- *    minimum and maximum (inclusive) of the range. If the @em subject value is a
+ *    minimum and maximum (inclusive) of the range. If the \a subject value is a
  *    number within this range, the constraint is satisfied
- *  - %WP_CONSTRAINT_VERB_MATCHES: @em value must be a string that defines a
+ *  - WP_CONSTRAINT_VERB_MATCHES: \a value must be a string that defines a
- *    pattern usable with
+ *    pattern usable with GPatternSpec If the \a subject value matches this
- * <a href="https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html#GPatternSpec">
- * GPatternSpec.</a> If the @em subject value matches this
  *    pattern, the constraint is satisfied
  *
- * In case the type of the @em subject value is not the same type as the one
+ * In case the type of the \a subject value is not the same type as the one
- * requested by the type of the @em value, the @em subject value is converted.
+ * requested by the type of the \a value, the \a subject value is converted.
- * For
+ * For GObject properties, this conversion is done using g_value_transform(),
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
- * GObject</a> properties, this conversion is done using g_value_transform(),
  * so limitations of this function apply. In the case of PipeWire properties,
  * which are *always* strings, conversion is done as follows:
- *  - to boolean: `"true"` or `"1"` means %TRUE, `"false"` or `"0"` means %FALSE
+ *  - to boolean: `"true"` or `"1"` means TRUE, `"false"` or `"0"` means FALSE
  *  - to int / uint / int64 / uint64: One of the `strtol()` family of functions
  *    is used to convert, using base 10
  *  - to double: `strtod()` is used
@@ -248,8 +214,14 @@ wp_object_interest_new_type (GType gtype)
  * This method does not fail if invalid arguments are given. However,
  * wp_object_interest_validate() should be called after adding all the
  * constraints on an interest in order to catch errors.
+ *
+ * \ingroup wpobjectinterest
+ * \param self the object interest
+ * \param type the constraint type
+ * \param subject the subject that the constraint applies to
+ * \param verb the operation that is performed to check the constraint
+ * \param value (transfer floating)(nullable): the value to check for
  */
-
 void
 wp_object_interest_add_constraint (WpObjectInterest * self,
     WpConstraintType type, const gchar * subject,
@@ -273,12 +245,10 @@ wp_object_interest_add_constraint (WpObjectInterest * self,
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \ingroup wpobjectinterest
- * @param self: the object interest to copy
+ * \param self the object interest to copy
- *
+ * \returns (transfer full): a deep copy of \a self
- * @returns (transfer full): a deep copy of @em self
  */
-
 WpObjectInterest *
 wp_object_interest_copy (WpObjectInterest * self)
 {
@@ -306,12 +276,10 @@ wp_object_interest_copy (WpObjectInterest * self)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \ingroup wpobjectinterest
- * @param self: the object interest to ref
+ * \param self the object interest to ref
- *
+ * \returns (transfer full): \a self with an additional reference count on it
- * @returns (transfer full): @em self with an additional reference count on it
  */
-
 WpObjectInterest *
 wp_object_interest_ref (WpObjectInterest *self)
 {
@@ -335,13 +303,12 @@ wp_object_interest_free (WpObjectInterest * self)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Decreases the reference count on \a self and frees it when the ref
- * @param self: (transfer full): the object interest to unref
+ * count reaches zero.
  *
- * @brief Decreases the reference count on @em self and frees it when the ref count
+ * \ingroup wpobjectinterest
- * reaches zero.
+ * \param self (transfer full): the object interest to unref
  */
-
 void
 wp_object_interest_unref (WpObjectInterest * self)
 {
@@ -350,18 +317,18 @@ wp_object_interest_unref (WpObjectInterest * self)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Validates the interest, ensuring that the interest GType
- * @param self: the object interest to validate
+ * is a valid object and that all the constraints have been expressed properly.
- * @param error: (out) (optional): the error, in case validation failed
  *
- * @brief Validates the interest, ensuring that the interest
+ * \remark This is called internally when \a self is first used to find a match,
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
+ * so it is not necessary to call it explicitly
- * GType</a> is a valid object and that all the constraints have been expressed properly.
  *
- * @returns %TRUE if the interest is valid and can be used in a match,
+ * \ingroup wpobjectinterest
- *   %FALSE otherwise
+ * \param self the object interest to validate
+ * \param error (out) (optional): the error, in case validation failed
+ * \returns TRUE if the interest is valid and can be used in a match,
+ *   FALSE otherwise
  */
-
 gboolean
 wp_object_interest_validate (WpObjectInterest * self, GError ** error)
 {
@@ -716,24 +683,20 @@ constraint_verb_in_range (gchar subj_type, const GValue * subj_val,
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Checks if the specified \a object matches the type and all the
- * @param self: the object interest
+ * constraints that are described in \a self
- * @param object: the target object to check for a match
  *
- * @brief Checks if the specified @em object matches the type and all the constraints
+ * If \a self is configured to match GObject subclasses, this is equivalent to
- * that are described in @em self
- *
- * If @em self is configured to match
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
- * GObject</a> subclasses, this is equivalent to
  * `wp_object_interest_matches_full (self, G_OBJECT_TYPE (object), object,
- * NULL, NULL)` and if it is configured to match [WpProperties](@ref properties_section), this is
+ * NULL, NULL)` and if it is configured to match WpProperties, this is
  * equivalent to `wp_object_interest_matches_full (self, self->gtype, NULL,
  * (WpProperties *) object, NULL);`
  *
- * @returns %TRUE if the object matches, %FALSE otherwise
+ * \ingroup wpobjectinterest
+ * \param self the object interest
+ * \param object the target object to check for a match
+ * \returns TRUE if the object matches, FALSE otherwise
  */
-
 gboolean
 wp_object_interest_matches (WpObjectInterest * self, gpointer object)
 {
@@ -750,36 +713,34 @@ wp_object_interest_matches (WpObjectInterest * self, gpointer object)
 }
 
 /*!
- * @memberof WpObjectInterest
+ * \brief A low-level version of wp_object_interest_matches().
- * @param self: the object interest
- * @param object_type: the type to be checked against the interest's type
- * @param object: (type GObject)(transfer none)(nullable): the object to be used for
- *   checking constraints of type %WP_CONSTRAINT_TYPE_G_PROPERTY
- * @param pw_props: (transfer none)(nullable): the properties to be used for
- *   checking constraints of type %WP_CONSTRAINT_TYPE_PW_PROPERTY
- * @param pw_global_props: (transfer none)(nullable): the properties to be used for
- *   checking constraints of type %WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY
  *
- * @brief A low-level version of wp_object_interest_matches(). In this version,
+ * In this version, the object's type is directly given in \a object_type and
- * the object's type is directly given in @em object_type and is not inferred
+ * is not inferred from the \a object. \a object is only used to check for
- * from the @em object. @em object is only used to check for constraints against
+ * constraints against GObject properties.
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
- * GObject</a> properties.
  *
- * @em pw_props and @em pw_global_props are used to check constraints against
+ * \a pw_props and \a pw_global_props are used to check constraints against
  * PipeWire object properties and global properties, respectively.
  *
- * @em object, @em pw_props and @em pw_global_props may be %NULL, but in case there
+ * \a object, \a pw_props and \a pw_global_props may be NULL, but in case there
  * are any constraints that require them, the match will fail.
- * As a special case, if @em object is not %NULL and is a subclass of [WpProxy](@ref proxy_section),
+ * As a special case, if \a object is not NULL and is a subclass of WpProxy,
- * then @em pw_props and @em pw_global_props, if required, will be internally
+ * then \a pw_props and \a pw_global_props, if required, will be internally
- * retrieved from @em object by calling wp_pipewire_object_get_properties() and
+ * retrieved from \a object by calling wp_pipewire_object_get_properties() and
  * wp_global_proxy_get_global_properties() respectively.
  *
- * @returns %TRUE if the the type matches this interest and the properties
+ * \ingroup wpobjectinterest
- *   match the constraints, %FALSE otherwise
+ * \param self the object interest
+ * \param object_type the type to be checked against the interest's type
+ * \param object (type GObject)(transfer none)(nullable): the object to be used for
+ *   checking constraints of type WP_CONSTRAINT_TYPE_G_PROPERTY
+ * \param pw_props (transfer none)(nullable): the properties to be used for
+ *   checking constraints of type WP_CONSTRAINT_TYPE_PW_PROPERTY
+ * \param pw_global_props (transfer none)(nullable): the properties to be used for
+ *   checking constraints of type WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY
+ * \returns TRUE if the the type matches this interest and the properties
+ *   match the constraints, FALSE otherwise
  */
-
 gboolean
 wp_object_interest_matches_full (WpObjectInterest * self,
     GType object_type, gpointer object, WpProperties * pw_props,
@@ -922,4 +883,4 @@ wp_object_interest_matches_full (WpObjectInterest * self,
     }
   }
   return TRUE;
-}
+}

lib/wp/object-interest.h

@@ -16,66 +16,50 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Constraint types for wp_object_interest_add_constraint()
- *
+ * \ingroup wpobjectinterest
- * @brief
- * @arg WP_CONSTRAINT_TYPE_NONE: invalid constraint type
- * @arg WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY: constraint applies
- *   to a PipeWire global property of the object (the ones returned by
- *   wp_global_proxy_get_global_properties())
- * @arg WP_CONSTRAINT_TYPE_PW_PROPERTY: constraint applies
- *   to a PipeWire property of the object (the ones returned by
- *   wp_pipewire_object_get_properties())
- * @arg WP_CONSTRAINT_TYPE_G_PROPERTY: constraint applies to a
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject-struct">
- * GObject</a> property of the object
  */
 typedef enum {
+  /*! invalid constraint type */
   WP_CONSTRAINT_TYPE_NONE = 0,
+  /*! constraint applies to a PipeWire global property of the object
+   *  (the ones returned by wp_global_proxy_get_global_properties()) */
   WP_CONSTRAINT_TYPE_PW_GLOBAL_PROPERTY,
+  /*! constraint applies to a PipeWire property of the object
+   *  (the ones returned by wp_pipewire_object_get_properties()) */
   WP_CONSTRAINT_TYPE_PW_PROPERTY,
+  /*! constraint applies to a GObject property of the object */
   WP_CONSTRAINT_TYPE_G_PROPERTY,
 } WpConstraintType;
 
 /*!
- * @memberof WpObjectInterest
+ * \brief Verbs to use with wp_object_interest_add_constraint()
- *
+ * \ingroup wpobjectinterest
- * @brief
- * @arg WP_CONSTRAINT_VERB_EQUALS: `=` the subject's value must equal the
- *   constraint's value
- * @arg WP_CONSTRAINT_VERB_NOT_EQUALS: `!` the subject's value must be different
- *   from the constraint's value
- * @arg WP_CONSTRAINT_VERB_IN_LIST: `c` the subject's value must equal at least
- *   one of the values in the list given as the constraint's value
- * @arg WP_CONSTRAINT_VERB_IN_RANGE: `~` the subject's value must be a number
- *   in the range defined by the constraint's value
- * @arg WP_CONSTRAINT_VERB_MATCHES: `#` the subject's value must match the
- *   pattern specified in the constraint's value
- * @arg WP_CONSTRAINT_VERB_IS_PRESENT: `+` the subject property must exist
- * @arg WP_CONSTRAINT_VERB_IS_ABSENT: `-` the subject property must not exist
  */
 typedef enum {
+  /*! the subject's value must equal the constraint's value */
   WP_CONSTRAINT_VERB_EQUALS = '=',
+  /*! the subject's value must be different from the constraint's value */
   WP_CONSTRAINT_VERB_NOT_EQUALS = '!',
+  /*! the subject's value must equal at least
+   *  one of the values in the list given as the constraint's value */
   WP_CONSTRAINT_VERB_IN_LIST = 'c',
+  /*! the subject's value must be a number in the range defined
+   *  by the constraint's value */
   WP_CONSTRAINT_VERB_IN_RANGE = '~',
+  /*! the subject's value must match the pattern specified in the
+   *  constraint's value */
   WP_CONSTRAINT_VERB_MATCHES = '#',
+  /*! the subject property must exist */
   WP_CONSTRAINT_VERB_IS_PRESENT = '+',
+  /*! the subject property must not exist */
   WP_CONSTRAINT_VERB_IS_ABSENT = '-',
 } WpConstraintVerb;
 
 /*!
- * @memberof WpObjectInterest
+ * \brief The WpObjectInterest GType
- *
+ * \ingroup wpobjectinterest
- * @brief The [WpObjectInterest](@ref object_interest_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())
- * @endcode
  */
-
 #define WP_TYPE_OBJECT_INTEREST (wp_object_interest_get_type ())
 WP_API
 GType wp_object_interest_get_type (void) G_GNUC_CONST;

lib/wp/object-manager.c

@@ -6,69 +6,122 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file object-manager.c
- */
 #define G_LOG_DOMAIN "wp-object-manager"
 
 #include "object-manager.h"
-
-/*!
- * @struct WpObjectManager
- *
- * @section object_manager_section Object Manager
- *
- * @brief The [WpObjectManager](@ref object_manager_section) class provides a way
- * to collect a set of objects and be notified when objects that fulfill a
- * certain set of criteria are created or destroyed.
- *
- * There are 4 kinds of objects that can be managed by a
- * [WpObjectManager](@ref object_manager_section):
- *   * remote PipeWire global objects that are advertised on the registry;
- *     these are bound locally to subclasses of [WpGlobalProxy](@ref global_proxy_section)
- *   * remote PipeWire global objects that are created by calling a remote
- *     factory through the WirePlumber API; these are very similar to other
- *     global objects but it should be noted that the same
- *     [WpGlobalProxy](@ref global_proxy_section)
- *     instance that created them appears in the
- *     [WpObjectManager](@ref object_manager_section) (as soon as
- *     its %WP_PROXY_FEATURE_BOUND is enabled)
- *   * local PipeWire objects that are being exported to PipeWire
- *     ([WpImplSession](@ref impl_session_section), WpImplEndpoint [private], etc); these appear in the
- *     [WpObjectManager](@ref object_manager_section) as soon as they are exported (so, when their
- *     %WP_PROXY_FEATURE_BOUND is enabled)
- *   * WirePlumber-specific objects, such as WirePlumber factories
- *
- * To start an object manager, you first need to declare interest in a certain
- * kind of object by calling wp_object_manager_add_interest() and then install
- * it on the [WpCore](@ref core_section) with wp_core_install_object_manager().
- *
- * Upon installing a [WpObjectManager](@ref object_manager_section) on a
- * [WpCore](@ref core_section), any pre-existing objects
- * that match the interests of this [WpObjectManager](@ref object_manager_section) will immediately become
- * available to get through wp_object_manager_new_iterator() and the
- * [WpObjectManager](@ref object_manager_section)
- * [object-added](@ref signal_object_added_section) signal will be emitted for all of them.
- *
- */
 #include "log.h"
 #include "private/registry.h"
 
 #include <pipewire/pipewire.h>
 
-/* WpObjectManager */
+/*! \defgroup wpobjectmanager WpObjectManager */
 /*!
- * @brief
+ * \struct WpObjectManager
- * @em parent
+ *
- * @em core
+ * The WpObjectManager class provides a way to collect a set of objects and
- * @em interests
+ * be notified when objects that fulfill a certain set of criteria are created
- * @em features
+ * or destroyed.
- * @em objects
+ *
- * @em installed
+ * There are 4 kinds of objects that can be managed by a
- * @em changed
+ * WpObjectManager:
- * @em pending_objects
+ *   * remote PipeWire global objects that are advertised on the registry;
- * @em idle_source
+ *     these are bound locally to subclasses of WpGlobalProxy
+ *   * remote PipeWire global objects that are created by calling a remote
+ *     factory through the WirePlumber API; these are very similar to other
+ *     global objects but it should be noted that the same WpGlobalProxy
+ *     instance that created them appears in the WpObjectManager (as soon as
+ *     its WP_PROXY_FEATURE_BOUND is enabled)
+ *   * local PipeWire objects that are being exported to PipeWire
+ *     (WpImplMetadata, WpImplEndpoint, etc); these appear in the
+ *     WpObjectManager as soon as they are exported (so, when their
+ *     WP_PROXY_FEATURE_BOUND is enabled)
+ *   * WirePlumber-specific objects, such as WirePlumber factories
+ *
+ * To start an object manager, you first need to declare interest in a certain
+ * kind of object by calling wp_object_manager_add_interest() and then install
+ * it on the WpCore with wp_core_install_object_manager().
+ *
+ * Upon installing a WpObjectManager on a WpCore, any pre-existing objects
+ * that match the interests of this WpObjectManager will immediately become
+ * available to get through wp_object_manager_new_iterator() and the
+ * WpObjectManager \c object-added signal will be emitted for all of them.
+ *
+ * \gproperties
+ *
+ * \gproperty{core, WpCore *, G_PARAM_READABLE, The core}
+ *
+ * \gsignals
+ *
+ * \par installed
+ * \parblock
+ * \code
+ * void
+ * installed_callback (WpObjectManager * self,
+ *                     gpointer user_data)
+ * \endcode
+ *
+ * This is emitted once after the object manager is installed with
+ * wp_core_install_object_manager(). If there are objects that need to be
+ * prepared asynchronously internally, emission of this signal is delayed
+ * until all objects are ready.
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par object-added
+ * \parblock
+ * \code
+ * void
+ * object_added_callback (WpObjectManager * self,
+ *                        gpointer object,
+ *                        gpointer user_data)
+ * \endcode
+ *
+ * Emitted when an object that matches the interests of this object manager
+ * is made available.
+ *
+ * Parameters:
+ * - `object` - the managed object that was just added
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par object-removed
+ * \parblock
+ * \code
+ * void
+ * object_removed_callback (WpObjectManager * self,
+ *                          gpointer object,
+ *                          gpointer user_data)
+ * \endcode
+ *
+ * Emitted when an object that was previously added on this object manager is
+ * now being removed (and most likely destroyed). At the time that this signal
+ * is emitted, the object is still alive.
+ *
+ * Parameters:
+ * - `object` - the managed object that is being removed
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par object-changed
+ * \parblock
+ * \code
+ * void
+ * object_changed_callback (WpObjectManager * self,
+ *                          gpointer user_data)
+ * \endcode
+ *
+ * Emitted when one or more objects have been recently added or removed from
+ * this object manager. This signal is useful to get notified only once when
+ * multiple changes happen in a short timespan. The receiving callback may
+ * retrieve the updated list of objects by calling wp_object_manager_new_iterator()
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
  */
+
 struct _WpObjectManager
 {
   GObject parent;
@@ -87,102 +140,11 @@ struct _WpObjectManager
   GSource *idle_source;
 };
 
-/*!
- * @memberof WpObjectManager
- *
- * @props @b core
- *
- * @code
- * "core" WpCore *
- * @endcode
- *
- * Flags : Read
- *
- */
 enum {
   PROP_0,
   PROP_CORE,
 };
 
-/*!
- * @memberof WpObjectManager
- *
- * @signal @b installed
- *
- * @code
- * installed_callback (WpObjectManager * self,
- *                     gpointer user_data)
- * @endcode
- *
- * This is emitted once after the object manager is installed with 
- * wp_core_install_object_manager. If there are objects that need to be prepared
- * asynchronously internally, emission of this signal is delayed until all objects are ready.
- *
- * Parameters:
- *
- * @arg `self` - the object manager
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @signal @b object-added
- *
- * @code
- * object_added_callback (WpObjectManager * self,
- *                        gpointer object,
- *                        gpointer user_data)
- * @endcode
- *
- * Emitted when an object that matches the interests of this object manager is made available.
- *
- * @b Parameters:
- *
- * @arg `self` - the object manager
- * @arg `object` - the managed object that was just added
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @signal @b object-removed
- *
- * @code
- * object_removed_callback (WpObjectManager * self,
- *                          gpointer object,
- *                          gpointer user_data)
- * @endcode
- *
- * Emitted when an object that was previously added on this object manager is now being
- * removed (and most likely destroyed). At the time that this signal is emitted, the object
- * is still alive.
- *
- * @b Parameters:
- *
- * @arg `self` - the object manager
- * @arg `object` - the managed object that is being removed
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @signal @b object-changed
- *
- * @code
- * object_changed_callback (WpObjectManager * self,
- *                          gpointer user_data)
- * @endcode
- *
- * Emitted when one or more objects have been recently added or removed from this object manager.
- * This signal is useful to get notified only once when multiple changes happen in a short timespan.
- * The receiving callback may retrieve the updated list of objects by calling
- * %wp_object_manager_new_iterator
- *
- * Parameters:
- *
- * @arg `self` - the object manager
- * @arg `user_data`
- *
- * Flags: Run First
- *
- */
 enum {
   SIGNAL_OBJECT_ADDED,
   SIGNAL_OBJECT_REMOVED,
@@ -255,70 +217,28 @@ wp_object_manager_class_init (WpObjectManagerClass * klass)
       g_param_spec_object ("core", "core", "The WpCore", WP_TYPE_CORE,
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpObjectManager::object-added:
-   * @self: the object manager
-   * @object: (transfer none): the managed object that was just added
-   *
-   * @section signal_object_added_section object-added
-   *
-   * @brief Emitted when an object that matches the interests of this object manager
-   * is made available.
-   */
   signals[SIGNAL_OBJECT_ADDED] = g_signal_new (
       "object-added", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_OBJECT);
 
-  /*
-   * WpObjectManager::object-removed:
-   * @self: the object manager
-   * @object: (transfer none): the managed object that is being removed
-   *
-   * @section signal_object_removed_section object-removed
-   *
-   * @brief Emitted when an object that was previously added on this object manager
-   * is now being removed (and most likely destroyed). At the time that this
-   * signal is emitted, the object is still alive.
-   */
   signals[SIGNAL_OBJECT_REMOVED] = g_signal_new (
       "object-removed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_OBJECT);
 
-  /*
-   * WpObjectManager::objects-changed:
-   * @self: the object manager
-   *
-   * @brief Emitted when one or more objects have been recently added or removed
-   * from this object manager. This signal is useful to get notified only once
-   * when multiple changes happen in a short timespan. The receiving callback
-   * may retrieve the updated list of objects by calling
-   * wp_object_manager_new_iterator()
-   */
   signals[SIGNAL_OBJECTS_CHANGED] = g_signal_new (
       "objects-changed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 0);
 
-  /*
-   * WpObjectManager::installed:
-   * @self: the object manager
-   *
-   * @brief This is emitted once after the object manager is installed with
-   * wp_core_install_object_manager(). If there are objects that need
-   * to be prepared asynchronously internally, emission of this signal is
-   * delayed until all objects are ready.
-   */
   signals[SIGNAL_INSTALLED] = g_signal_new (
       "installed", G_TYPE_FROM_CLASS (klass), G_SIGNAL_RUN_FIRST,
       0, NULL, NULL, NULL, G_TYPE_NONE, 0);
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Constructs a new object manager.
- * @brief Constructs a new object manager.
+ * \ingroup wpobjectmanager
- *
+ * \returns (transfer full): the newly constructed object manager
- * @returns (transfer full): the newly constructed object manager
  */
-
 WpObjectManager *
 wp_object_manager_new (void)
 {
@@ -326,13 +246,11 @@ wp_object_manager_new (void)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \ingroup wpobjectmanager
- * @param self: the object manager
+ * \param self the object manager
- *
+ * \returns TRUE if the object manager is installed (i.e. the
- * @returns %TRUE if the object manager is installed (the
+ *   WpObjectManager \c installed signal has been emitted), FALSE otherwise
- *   WpObjectManager::installed has been emitted), %FALSE otherwise
  */
-
 gboolean
 wp_object_manager_is_installed (WpObjectManager * self)
 {
@@ -341,24 +259,20 @@ wp_object_manager_is_installed (WpObjectManager * self)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Equivalent to:
- * @param self: the object manager
+ * \code
- * @param gtype: the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- * of the objects that we are declaring interest in
- * @...: a list of constraints, terminated by %NULL
- *
- * @brief Equivalent to:
- * |[
  * WpObjectInterest *i = wp_object_interest_new (gtype, ...);
  * wp_object_manager_add_interest_full (self, i);
- * ]|
+ * \endcode
  *
  * The constraints specified in the variable arguments must follow the rules
  * documented in wp_object_interest_new().
+ *
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param gtype the GType of the objects that we are declaring interest in
+ * \param ... a list of constraints, terminated by NULL
  */
-
 void
 wp_object_manager_add_interest (WpObjectManager * self, GType gtype, ...)
 {
@@ -374,18 +288,16 @@ wp_object_manager_add_interest (WpObjectManager * self, GType gtype, ...)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Declares interest in a certain kind of object.
- * @param self: the object manager
- * @param interest: (transfer full): the interest
  *
- * @brief Declares interest in a certain kind of object. Interest consists of a
+ * Interest consists of a GType that the object must be an ancestor of
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
+ * (g_type_is_a() must match) and optionally, a set of additional constraints
- * GType</a>
+ * on certain properties of the object. Refer to WpObjectInterest for more details.
- * that the object must be an ancestor of (g_type_is_a must match) and
+ *
- * optionally, a set of additional constraints on certain properties of the
+ * \ingroup wpobjectmanager
- * object. Refer to [WpObjectInterest](@ref object_interest_section) for more details.
+ * \param self the object manager
+ * \param interest (transfer full): the interest
  */
-
 void
 wp_object_manager_add_interest_full (WpObjectManager *self,
     WpObjectInterest * interest)
@@ -422,16 +334,18 @@ store_children_object_features (GHashTable *store, GType object_type,
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Requests the object manager to automatically prepare the
- * @param self: the object manager
+ * \a wanted_features on any managed object that is of the specified
- * @param object_type: the [WpProxy](@ref proxy_section) descendant type
+ * \a object_type.
- * @param wanted_features: the features to enable on this kind of object
  *
- * @brief Requests the object manager to automatically prepare the @em wanted_features
+ * These features will always be prepared before the object appears on the
- * on any managed object that is of the specified @em object_type. These features
+ * object manager.
- * will always be prepared before the object appears on the object manager.
+ *
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param object_type the WpProxy descendant type
+ * \param wanted_features the features to enable on this kind of object
  */
-
 void
 wp_object_manager_request_object_features (WpObjectManager *self,
     GType object_type, WpObjectFeatures wanted_features)
@@ -445,12 +359,10 @@ wp_object_manager_request_object_features (WpObjectManager *self,
 }
 
 /*!
- * @memberof WpObjectManager
+ * \ingroup wpobjectmanager
- * @param self: the object manager
+ * \param self the object manager
- *
+ * \returns the number of objects managed by this WpObjectManager
- * @returns the number of objects managed by this [WpObjectManager](@ref object_manager_section)
  */
-
 guint
 wp_object_manager_get_n_objects (WpObjectManager * self)
 {
@@ -533,13 +445,11 @@ static const WpIteratorMethods om_iterator_methods = {
 };
 
 /*!
- * @memberof WpObjectManager
+ * \ingroup wpobjectmanager
- * @param self: the object manager
+ * \param self the object manager
- *
+ * \returns (transfer full): a WpIterator that iterates over all the managed
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the managed
  *   objects of this object manager
  */
-
 WpIterator *
 wp_object_manager_new_iterator (WpObjectManager * self)
 {
@@ -556,26 +466,22 @@ wp_object_manager_new_iterator (WpObjectManager * self)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Equivalent to:
- * @param self: the object manager
+ * \code
- * @param gtype: the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a> of the objects to iterate through
- * @...: a list of constraints, terminated by %NULL
- *
- * @brief Equivalent to:
- * |[
  * WpObjectInterest *i = wp_object_interest_new (gtype, ...);
  * return wp_object_manager_new_filtered_iterator_full (self, i);
- * ]|
+ * \endcode
  *
  * The constraints specified in the variable arguments must follow the rules
  * documented in wp_object_interest_new().
  *
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the matching
+ * \ingroup wpobjectmanager
+ * \param self the object manager
+ * \param gtype the GType of the objects to iterate through
+ * \param ... a list of constraints, terminated by NULL
+ * \returns (transfer full): a WpIterator that iterates over all the matching
  *   objects of this object manager
  */
-
 WpIterator *
 wp_object_manager_new_filtered_iterator (WpObjectManager * self, GType gtype,
     ...)
@@ -593,17 +499,15 @@ wp_object_manager_new_filtered_iterator (WpObjectManager * self, GType gtype,
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Iterates through all the objects managed by this object manager that
- * @param self: the object manager
+ * match the specified \a interest.
- * @param interest: (transfer full): the interest
  *
- * @brief Iterates through all the objects managed by this object manager that
+ * \ingroup wpobjectmanager
- * match the specified @em interest.
+ * \param self the object manager
- *
+ * \param interest (transfer full): the interest
- * @returns (transfer full): a [WpIterator](@ref iterator_section) that iterates over all the matching
+ * \returns (transfer full): a WpIterator that iterates over all the matching
  *   objects of this object manager
  */
-
 WpIterator *
 wp_object_manager_new_filtered_iterator_full (WpObjectManager * self,
     WpObjectInterest * interest)
@@ -630,26 +534,22 @@ wp_object_manager_new_filtered_iterator_full (WpObjectManager * self,
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Equivalent to:
- * @param self: the object manager
+ * \code
- * @param gtype: the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a> of the object to lookup
- * @...: a list of constraints, terminated by %NULL
- *
- * @brief Equivalent to:
- * |[
  * WpObjectInterest *i = wp_object_interest_new (gtype, ...);
  * return wp_object_manager_lookup_full (self, i);
- * ]|
+ * \endcode
  *
  * The constraints specified in the variable arguments must follow the rules
  * documented in wp_object_interest_new().
  *
- * @returns (type GObject)(transfer full)(nullable): the first managed object
+ * \ingroup wpobjectmanager
- *    that matches the lookup interest, or %NULL if no object matches
+ * \param self the object manager
+ * \param gtype the GType of the object to lookup
+ * \param ... a list of constraints, terminated by NULL
+ * \returns (type GObject)(transfer full)(nullable): the first managed object
+ *    that matches the lookup interest, or NULL if no object matches
  */
-
 gpointer
 wp_object_manager_lookup (WpObjectManager * self, GType gtype, ...)
 {
@@ -666,19 +566,19 @@ wp_object_manager_lookup (WpObjectManager * self, GType gtype, ...)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Searches for an object that matches the specified \a interest and
- * @param self: the object manager
+ * returns it, if found.
- * @param interest: (transfer full): the interst
  *
- * @brief Searches for an object that matches the specified @em interest and returns
+ * If more than one objects match, only the first one is returned.
- * it, if found. If more than one objects match, only the first one is returned.
  * To find multiple objects that match certain criteria,
  * wp_object_manager_new_filtered_iterator() is more suitable.
  *
- * @returns (type GObject)(transfer full)(nullable): the first managed object
+ * \ingroup wpobjectmanager
- *    that matches the lookup interest, or %NULL if no object matches
+ * \param self the object manager
+ * \param interest (transfer full): the interst
+ * \returns (type GObject)(transfer full)(nullable): the first managed object
+ *    that matches the lookup interest, or NULL if no object matches
  */
-
 gpointer
 wp_object_manager_lookup_full (WpObjectManager * self,
     WpObjectInterest * interest)
@@ -872,9 +772,7 @@ wp_object_manager_rm_object (WpObjectManager * self, gpointer object)
 /*
  * WpRegistry:
  *
- * @section registry_section WpRegistry
+ * The registry keeps track of registered objects on the wireplumber core.
- *
- * @brief The registry keeps track of registered objects on the wireplumber core.
  * There are 3 kinds of registered objects:
  *
  * 1) PipeWire global objects, which live in another process.
@@ -1181,10 +1079,9 @@ expose_tmp_globals (WpCore *core, GAsyncResult *res, WpRegistry *self)
 }
 
 /*
+ * \param new_global (out) (transfer full) (optional): the new global
  *
- * @param new_global: (out) (transfer full) (optional): the new global
+ * This is normally called up to 2 times in the same sync cycle:
- *
- * @brief This is normally called up to 2 times in the same sync cycle:
  * one from registry_global(), another from the proxy bound event
  * Unfortunately the order in which those 2 events happen is specific
  * to the implementation of the object, which is why this is implemented
@@ -1258,16 +1155,14 @@ wp_registry_prepare_new_global (WpRegistry * self, guint32 id,
 }
 
 /*
+ * Finds a registered object
  *
- * @param reg: the registry
+ * \param reg the registry
- * @param func: (scope call): a function that takes the object being searched
+ * \param func (scope call): a function that takes the object being searched
- *   as the first argument and @em data as the second. it should return TRUE if
+ *   as the first argument and \a data as the second. it should return TRUE if
  *   the object is found or FALSE otherwise
- * @param data: the second argument to @em func
+ * \param data the second argument to \a func
- *
+ * \returns (transfer full) (type GObject *) (nullable): the registered object
- * @brief Finds a registered object
- *
- * @returns (transfer full) (type GObject *) (nullable): the registered object
  *   or NULL if not found
  */
 gpointer
@@ -1290,14 +1185,12 @@ wp_registry_find_object (WpRegistry *reg, GEqualFunc func, gconstpointer data)
 }
 
 /*
- *
+ * Registers \a obj with the core, making it appear on WpObjectManager
- * @param reg: the registry
- * @param obj: (transfer full) (type GObject*): the object to register
- *
- * @brief Registers @em obj with the core, making it appear on
- * [WpObjectManager](@ref object_manager_section)
  * instances as well. The core will also maintain a ref to that object
  * until it is removed.
+ *
+ * \param reg the registry
+ * \param obj (transfer full) (type GObject*): the object to register
  */
 void
 wp_registry_register_object (WpRegistry *reg, gpointer obj)
@@ -1317,11 +1210,10 @@ wp_registry_register_object (WpRegistry *reg, gpointer obj)
 }
 
 /*
+ * Detaches and unrefs the specified object from this core
  *
- * @param reg: the registry
+ * \param reg the registry
- * @param obj: (transfer none) (type GObject*): a pointer to the object to remove
+ * \param obj (transfer none) (type GObject*): a pointer to the object to remove
- *
- * @brief Detaches and unrefs the specified object from this core
  */
 void
 wp_registry_remove_object (WpRegistry *reg, gpointer obj)
@@ -1339,15 +1231,16 @@ wp_registry_remove_object (WpRegistry *reg, gpointer obj)
 }
 
 /*!
- * @memberof WpObjectManager
+ * \brief Installs the object manager on this core, activating its internal
- * @param self: the core
+ * management engine.
- * @param om: (transfer none): a [WpObjectManager](@ref object_manager_section)
  *
- * @brief Installs the object manager on this core, activating its internal management
+ * This will immediately emit signals about objects added on \a om
- * engine. This will immediately emit signals about objects added on @em om
+ * if objects that the \a om is interested in were in existence already.
- * if objects that the @em om is interested in were in existence already.
+ *
+ * \ingroup wpobjectmanager
+ * \param self the core
+ * \param om (transfer none): a WpObjectManager
  */
-
 void
 wp_core_install_object_manager (WpCore * self, WpObjectManager * om)
 {
@@ -1447,4 +1340,4 @@ wp_global_bind (WpGlobal * global)
   WpProxyClass *klass = WP_PROXY_GET_CLASS (global->proxy);
   return pw_registry_bind (global->registry->pw_registry, global->id,
       klass->pw_iface_type, klass->pw_iface_version, 0);
-}
+}

lib/wp/object-manager.h

@@ -17,16 +17,8 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpObjectManager
+ * \brief The WpObjectManager GType
- *
+ * \ingroup wpobjectmanager
- * @brief The [WpObjectManager](@ref object_manager_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_OBJECT_MANAGER (wp_object_manager_get_type ())
 WP_API

lib/wp/object.c

@@ -5,27 +5,17 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
+
- * @file object.c
- */
 #define G_LOG_DOMAIN "wp-object"
 
 #include "object.h"
 #include "log.h"
 #include "core.h"
 
+/*! \defgroup wpfeatureactivationtransition WpFeatureActivationTransition */
 /*!
- * @struct WpFeatureActivationTransition
+ * \struct WpFeatureActivationTransition
- * @memberof WpObject
+ * A WpTransition that is used by WpObject to implement feature activation.
- * @section feature_active_transition_section Feature Activation
- *
- * @brief A [WpTransition](@ref transition_section) that is used by
- * [WpObject](@ref object_section) to implement feature activation.
- */
-/*!
- * @brief
- * @em parent
- * @em missing
  */
 struct _WpFeatureActivationTransition
 {
@@ -113,14 +103,12 @@ wp_feature_activation_transition_class_init (
 }
 
 /*!
- * @memberof WpFeatureActivationTransition
+ * \ingroup wpfeatureactivationtransition
- * @param self: the transition
+ * \param self the transition
- *
+ * \returns the features that were requested to be activated in this transition;
- * @returns the features that were requested to be activated in this transition;
  *   this contains the features as they were passed in wp_object_activate() and
  *   therefore it may contain unsupported or already active features
  */
-
 WpObjectFeatures
 wp_feature_activation_transition_get_requested_features (
     WpFeatureActivationTransition * self)
@@ -128,8 +116,22 @@ wp_feature_activation_transition_get_requested_features (
   return GPOINTER_TO_UINT (wp_transition_get_data (WP_TRANSITION (self)));
 }
 
+/*! \defgroup wpobject WpObject */
 /*!
- * @struct WpObject
+ * \struct WpObject
+ *
+ * Base class for objects that have activatable features.
+ *
+ * \gproperties
+ *
+ * \gproperty{core, WpCore *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The WpCore associated with this object}
+ *
+ * \gproperty{active-features, guint (WpObjectFeatures), G_PARAM_READABLE,
+ *   The active WpObjectFeatures on this proxy}
+ *
+ * \gproperty{supported-features, guint (WpObjectFeatures), G_PARAM_READABLE,
+ *   The supported WpObjectFeatures on this proxy}
  */
 typedef struct _WpObjectPrivate WpObjectPrivate;
 struct _WpObjectPrivate
@@ -143,33 +145,6 @@ struct _WpObjectPrivate
   GSource *idle_advnc_source;
 };
 
-/*!
- * @memberof WpObject
- *
- * @props @b active-features
- *
- * @code
- * "active-features" guint
- * @endcode
- *
- * Flags : Read
- *
- * @props @b core
- *
- * @code
- * "core" WpCore *
- * @endcode
- *
- * Flags : Read / Write / Construct Only
- *
- * @props @b supported-features
- *
- * @code
- * "supported-features" <a href="https://developer.gnome.org/glib/stable/glib-Basic-Types.html#guint">guint</a>
- * @endcode
- *
- * Flags : Read
- */
 enum {
   PROP_0,
   PROP_CORE,
@@ -288,12 +263,10 @@ wp_object_class_init (WpObjectClass * klass)
 }
 
 /*!
- * @memberof WpObject
+ * \ingroup wpobject
- * @param self: the object
+ * \param self the object
- *
+ * \returns (transfer full): the core associated with this object
- * @returns (transfer full): the core associated with this object
  */
-
 WpCore *
 wp_object_get_core (WpObject * self)
 {
@@ -304,12 +277,10 @@ wp_object_get_core (WpObject * self)
 }
 
 /*!
- * @memberof WpObject
+ * \ingroup wpobject
- * @param self: the object
+ * \param self the object
- *
+ * \returns A bitset containing the active features of this object
- * @returns a bitset containing the active features of this object
  */
-
 WpObjectFeatures
 wp_object_get_active_features (WpObject * self)
 {
@@ -320,13 +291,11 @@ wp_object_get_active_features (WpObject * self)
 }
 
 /*!
- * @memberof WpObject
+ * \ingroup wpobject
- * @param self: the object
+ * \param self the object
- *
+ * \returns A bitset containing the supported features of this object;
- * @returns a bitset containing the supported features of this object;
  *   note that supported features may change at runtime
  */
-
 WpObjectFeatures
 wp_object_get_supported_features (WpObject * self)
 {
@@ -339,8 +308,8 @@ wp_object_get_supported_features (WpObject * self)
 static gboolean
 wp_object_advance_transitions (WpObject * self)
 {
-  /* keep @em self alive; in rare cases, the last transition may be
+  /* keep \a self alive; in rare cases, the last transition may be
-     holding the last ref on @em self and g_queue_peek_head will crash
+     holding the last ref on \a self and g_queue_peek_head will crash
      right after droping that last ref */
   g_autoptr (WpObject) self_ref = g_object_ref (self);
   WpObjectPrivate *priv = wp_object_get_instance_private (self);
@@ -361,16 +330,15 @@ wp_object_advance_transitions (WpObject * self)
 }
 
 /*!
- * @memberof WpObject
+ * \brief Callback version of wp_object_activate_closure()
- * @param self: the object
- * @param features: the features to enable
- * @param cancellable: (nullable): a cancellable for the async operation
- * @param callback: (scope async): a function to call when activation is complete
- * @param user_data: (closure): data for @em callback
  *
- * @brief Callback version of wp_object_activate_closure
+ * \ingroup wpobject
+ * \param self the object
+ * \param features the features to enable
+ * \param cancellable (nullable): a cancellable for the async operation
+ * \param callback (scope async): a function to call when activation is complete
+ * \param user_data (closure): data for \a callback
  */
-
 void
 wp_object_activate (WpObject * self,
     WpObjectFeatures features, GCancellable * cancellable,
@@ -384,23 +352,23 @@ wp_object_activate (WpObject * self,
 }
 
 /*!
- * @memberof WpObject
+ * \brief Activates the requested \a features and invokes \a closure when this
- * @param self: the object
+ * is done. \a features may contain unsupported or already active features.
- * @param features: the features to enable
+ * The operation will filter them and activate only ones that are supported and
- * @param cancellable: (nullable): a cancellable for the async operation
+ * inactive.
- * @param closure: (transfer full): the closure to use when activation is completed
- *
- * @brief Activates the requested @em features and invokes @em closure when this is done.
- * @em features may contain unsupported or already active features. The operation
- * will filter them and activate only ones that are supported and inactive.
  *
  * If multiple calls to this method is done, the operations will be executed
  * one after the other to ensure features only get activated once.
  *
- * Note that @em closure may be invoked in sync while this method is being called,
+ * \note \a closure may be invoked in sync while this method is being called,
  * if there are no features to activate.
+ *
+ * \ingroup wpobject
+ * \param self the object
+ * \param features the features to enable
+ * \param cancellable (nullable): a cancellable for the async operation
+ * \param closure (transfer full): the closure to use when activation is completed
  */
-
 void
 wp_object_activate_closure (WpObject * self,
     WpObjectFeatures features, GCancellable * cancellable,
@@ -427,15 +395,15 @@ wp_object_activate_closure (WpObject * self,
 }
 
 /*!
- * @memberof WpObject
+ * \brief Finishes the async operation that was started with wp_object_activate()
- * @param self: the object
- * @param res: the async operation result
- * @param error: (out) (optional): the error of the operation, if any
  *
- * @returns %TRUE if the requested features were activated,
+ * \ingroup wpobject
- *   %FALSE if there was an error
+ * \param self the object
+ * \param res the async operation result
+ * \param error (out) (optional): the error of the operation, if any
+ * \returns TRUE if the requested features were activated,
+ *   FALSE if there was an error
  */
-
 gboolean
 wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
 {
@@ -446,15 +414,16 @@ wp_object_activate_finish (WpObject * self, GAsyncResult * res, GError ** error)
 }
 
 /*!
- * @memberof WpObject
+ * \brief Deactivates the given \a features, leaving the object in the state
- * @param self: the object
+ * it was before they were enabled.
- * @param features: the features to deactivate
  *
- * @brief Deactivates the given @em features, leaving the object in the state it was
+ * This is seldom needed to call manually, but it can be used to save
- * before they were enabled. This is seldom needed to call manually, but it
+ * resources if some features are no longer needed.
- * can be used to save resources if some features are no longer needed.
+ *
+ * \ingroup wpobject
+ * \param self the object
+ * \param features the features to deactivate
  */
-
 void
 wp_object_deactivate (WpObject * self, WpObjectFeatures features)
 {
@@ -466,14 +435,20 @@ wp_object_deactivate (WpObject * self, WpObjectFeatures features)
 }
 
 /*!
- * @memberof WpObject
+ * \brief Allows subclasses to update the currently active features.
- * @brief Private method to be called by subclasses. Allows subclasses to update
- * the currently active features. @em activated should contain new features and
- * @em deactivated should contain features that were just deactivated.
  *
+ * \a activated should contain new features and \a deactivated
+ * should contain features that were just deactivated.
  * Calling this method also advances the activation transitions.
+ *
+ * \remark Private method to be called by subclasses only.
+ *
+ * \protected
+ * \ingroup wpobject
+ * \param self the object
+ * \param activated the features that were activated, or 0
+ * \param deactivated the features that were deactivated, or 0
  */
-
 void
 wp_object_update_features (WpObject * self, WpObjectFeatures activated,
     WpObjectFeatures deactivated)
@@ -499,4 +474,4 @@ wp_object_update_features (WpObject * self, WpObjectFeatures activated,
     wp_core_idle_add (core, &priv->idle_advnc_source,
         G_SOURCE_FUNC (wp_object_advance_transitions), self, NULL);
   }
-}
+}

lib/wp/object.h

@@ -6,10 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file object.h
- */
-
 #ifndef __WIREPLUMBER_OBJECT_H__
 #define __WIREPLUMBER_OBJECT_H__
 
@@ -19,11 +15,7 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpObject
+ * \brief Flags that specify functionality that is available on this class.
- *
- * @section object_features_section WpObjectFeatures
- *
- * @brief Flags that specify functionality that is available on this class.
  *
  * Use wp_object_activate() to enable more features,
  * wp_object_get_supported_features() to see which features are supported and
@@ -31,30 +23,23 @@ G_BEGIN_DECLS
  * enabled. Features can also be deactivated later using wp_object_deactivate().
  *
  * Actual feature flags are to be specified by subclasses and their interfaces.
- * %WP_OBJECT_FEATURES_ALL is a special value that can be used to activate
+ * WP_OBJECT_FEATURES_ALL is a special value that can be used to activate
  * all the supported features in any given object.
+ *
+ * \ingroup wpobject
  */
 typedef guint WpObjectFeatures;
 
 /*!
- * @memberof WpObject
+ * \brief Special value that can be used to activate
- *
- * @brief Special value that can be used to activate
  * all the supported features in any given object.
+ * \ingroup wpobject
  */
 static const WpObjectFeatures WP_OBJECT_FEATURES_ALL = 0xffffffff;
 
 /*!
- * @memberof WpFeatureActivationTransition
+ * \brief The WpFeatureActivationTransition GType
- *
+ * \ingroup wpfeatureactivationtransition
- * @brief The [WpFeatureActivationTransition](@ref feature_activation_transition_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_FEATURE_ACTIVATION_TRANSITION (wp_feature_activation_transition_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_FEATURE_ACTIVATION_TRANSITION \
     (wp_feature_activation_transition_get_type ())
@@ -68,27 +53,13 @@ WpObjectFeatures wp_feature_activation_transition_get_requested_features (
     WpFeatureActivationTransition * self);
 
 /*!
- * @memberof WpObject
+ * \brief The WpObject GType
- *
+ * \ingroup wpobject
- * @brief The [WpObject](@ref object_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_OBJECT (wp_object_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_OBJECT (wp_object_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpObject, wp_object, WP, OBJECT, GObject)
 
-/*!
- * @memberof WpObject
- *
- * @brief
- * @em parent_class
- */
 struct _WpObjectClass
 {
   GObjectClass parent_class;

lib/wp/plugin.c

@@ -6,28 +6,39 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file plugin.c
- */
 #define G_LOG_DOMAIN "wp-plugin"
 
 #include "plugin.h"
 #include "log.h"
 #include "private/registry.h"
 
+/*! \defgroup wpplugin WpPlugin */
 /*!
- * @memberof WpPlugin
+ * \struct WpPlugin
  *
- * @props @b name
+ * WpPlugin is a base class for objects that provide functionality to the
+ * WirePlumber daemon.
  *
- * @code
+ * Typically, a plugin is created within a module and then registered to
- * "name" gchar *
+ * make it available for use by the daemon. The daemon is responsible for
- * @endcode
+ * calling wp_object_activate() on it after all modules have been loaded,
+ * the core is connected and the initial discovery of global objects is
+ * done.
  *
- * The name of this plugin. Implementations should initialize this in the constructor.
+ * Being a WpObject subclass, the plugin inherits WpObject's activation system.
+ * For most implementations, there is only need for activating one
+ * feature, WP_PLUGIN_FEATURE_ENABLED, and this can be done by implementing
+ * only WpPluginClass::enable() and WpPluginClass::disable().
+ * For more advanced plugins that need to have more features, you may
+ * implement directly the functions of WpObjectClass and ignore the ones of
+ * WpPluginClass.
  *
- * Flags : Read / Write / Construct Only
+ * \gproperties
+ *
+ * \gproperty{name, gchar *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The name of this plugin}
  */
+
 enum {
   PROP_0,
   PROP_NAME,
@@ -39,31 +50,6 @@ struct _WpPluginPrivate
   GQuark name_quark;
 };
 
-/*!
- * @struct WpPlugin
- * @section plugin_section Plugins
- * 
- * @brief [WpPlugin](@ref plugin_section) is a base class for objects that
- * provide functionality to the WirePlumber daemon.
- *
- * Typically, a plugin is created within a module and then registered to
- * make it available for use by the daemon. The daemon is responsible for
- * calling wp_object_activate() on it after all modules have been loaded,
- * the core is connected and the initial discovery of global objects is
- * done.
- *
- * Being a [WpObject](@ref object_section) subclass, the plugin inherits
- * [WpObject](@ref object_section)'s activation system.
- * For most implementations, there is only need for activating one
- * feature, %WP_PLUGIN_FEATURE_ENABLED, and this can be done by implementing
- * only [WpPluginClass](@ref plugin_class_section).[enable](@ref plugin_class_enable_section)() and
- * [WpPluginClass](@ref plugin_class_section).[disable](@ref plugin_class_disable_section)().
- * For more advanced plugins that need to have more features, you may implement directly the
- * functions of [WpObjectClass](@ref object_class_section) and ignore the ones of
- * [WpPluginClass](@ref plugin_class_section).
- *
- */
-
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpPlugin, wp_plugin, WP_TYPE_OBJECT)
 
 static void
@@ -174,11 +160,6 @@ wp_plugin_class_init (WpPluginClass * klass)
   wpobject_class->activate_execute_step = wp_plugin_activate_execute_step;
   wpobject_class->deactivate = wp_plugin_deactivate;
 
-  /*
-   * WpPlugin:name:
-   * @brief The name of this plugin.
-   * Implementations should initialize this in the constructor.
-   */
   g_object_class_install_property (object_class, PROP_NAME,
       g_param_spec_string ("name", "name",
           "The name of this plugin", NULL,
@@ -186,12 +167,11 @@ wp_plugin_class_init (WpPluginClass * klass)
 }
 
 /*!
- * @memberof WpPlugin
+ * \brief Registers the plugin to its associated core, making it available for use
- * @param plugin: (transfer full): the plugin
  *
- * @brief Registers the plugin to its associated core, making it available for use
+ * \ingroup wpplugin
+ * \param plugin (transfer full): the plugin
  */
-
 void
 wp_plugin_register (WpPlugin * plugin)
 {
@@ -212,13 +192,11 @@ find_plugin_func (gpointer plugin, gpointer name_quark)
 }
 
 /*!
- * @memberof WpPlugin
+ * \ingroup wpplugin
- * @param core: the core
+ * \param core the core
- * @param plugin_name: the lookup name
+ * \param plugin_name the lookup name
- *
+ * \returns (transfer full) (nullable): the plugin matching the lookup name
- * @returns (transfer full) (nullable): the plugin matching the lookup name
  */
-
 WpPlugin *
 wp_plugin_find (WpCore * core, const gchar * plugin_name)
 {
@@ -233,12 +211,10 @@ wp_plugin_find (WpCore * core, const gchar * plugin_name)
 }
 
 /*!
- * @memberof WpPlugin
+ * \ingroup wpplugin
- * @param self: the plugin
+ * \param self the plugin
- *
+ * \returns the name of this plugin
- * @returns the name of this plugin
  */
-
 const gchar *
 wp_plugin_get_name (WpPlugin * self)
 {
@@ -249,28 +225,24 @@ wp_plugin_get_name (WpPlugin * self)
 }
 
 /**
- * WpPluginClass::enable:
+ * \var _WpPluginClass::enable
  *
- * @section plugin_class_enable_section enable
+ * \brief Enables the plugin. The plugin is required to start any operations
- *
+ * only when this method is called and not before.
- * @param self: the plugin
- * @param transition: the activation transition
- *
- * @brief Enables the plugin. The plugin is required to start any operations only
- * when this method is called and not before.
  *
  * When enabling the plugin is done, you must call wp_object_update_features()
- * with %WP_PLUGIN_FEATURE_ENABLED marked as activated, or return an error
+ * with WP_PLUGIN_FEATURE_ENABLED marked as activated, or return an error
- * on @em transition.
+ * on \a transition.
+ *
+ * \param self the plugin
+ * \param transition the activation transition
  */
 
 /**
- * WpPluginClass::disable:
+ * \var _WpPluginClass::disable
  *
- * @section plugin_class_disable_section disable
+ * \brief Disables the plugin. The plugin is required to stop all operations
+ * and release all resources associated with it.
  *
- * @param self: the plugin
+ * \param self the plugin
- *
- * Disables the plugin. The plugin is required to stop all operations and
- * release all resources associated with it.
  */

lib/wp/plugin.h

@@ -14,42 +14,22 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpPlugin
+ * \brief Flags to be used as WpObjectFeatures on WpPlugin subclasses.
- *
+ * \ingroup wpplugin
- * @section plugin_features_section WpPluginFeatures
- *
- * @brief
- * @em WP_PLUGIN_FEATURE_ENABLED: enables the plugin
- *
- * Flags to be used as [WpObjectFeatures](@ref object_features_section)
- * for [WpPlugin](@ref plugin_section) subclasses.
  */
 typedef enum { /*< flags >*/
+  /*! enables the plugin */
   WP_PLUGIN_FEATURE_ENABLED = (1 << 0),
 } WpPluginFeatures;
 
 /*!
- * @memberof WpPlugin
+ * \brief The WpPlugin GType
- *
+ * \ingroup wpplugin
- * @brief The [WpPlugin](@ref plugin_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_PLUGIN (wp_plugin_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_PLUGIN (wp_plugin_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpPlugin, wp_plugin, WP, PLUGIN, WpObject)
 
-/*!
- * @brief
- * @em parent_class
- * @em enable: See wp_plugin_activate_execute_step()
- * @em disable: See wp_plugin_deactivate()
- */
 struct _WpPluginClass
 {
   WpObjectClass parent_class;

lib/wp/port.c

@@ -5,18 +5,24 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
+
- * @file port.c
- */
 #define G_LOG_DOMAIN "wp-port"
 
 #include "port.h"
 #include "private/pipewire-object-mixin.h"
 
+/*! \defgroup wpport WpPort */
 /*!
- * @brief
+ * \struct WpPort
- * @em parent
+ *
+ * The WpPort class allows accessing the properties
+ * and methods of a PipeWire port object (`struct pw_port`).
+ *
+ * A WpPort is constructed internally when a new port appears
+ * on the PipeWire registry and it is made available through the
+ * WpObjectManager API.
  */
+
 struct _WpPort
 {
   WpGlobalProxy parent;
@@ -25,19 +31,6 @@ struct _WpPort
 static void wp_port_pw_object_mixin_priv_interface_init (
     WpPwObjectMixinPrivInterface * iface);
 
-/*!
- * @struct WpPort
- * @section port_section Port
- *
- * @brief The [WpPort](@ref port_section) class allows accessing the properties
- * and methods of a PipeWire port object (`struct pw_port`).
- *
- * A [WpPort](@ref port_section) is constructed internally when a new port appears
- * on the PipeWire registry and it is made available through the
- * [WpObjectManager](@ref object_manager_section) API.
- *
- */
-
 G_DEFINE_TYPE_WITH_CODE (WpPort, wp_port, WP_TYPE_GLOBAL_PROXY,
     G_IMPLEMENT_INTERFACE (WP_TYPE_PIPEWIRE_OBJECT,
         wp_pw_object_mixin_object_interface_init)
@@ -142,12 +135,10 @@ wp_port_pw_object_mixin_priv_interface_init (
 }
 
 /*!
- * @memberof WpPort
+ * \ingroup wpport
- * @param self: the port
+ * \param self the port
- *
+ * \returns the current direction of the port
- * @returns the current direction of the port
  */
-
 WpDirection
 wp_port_get_direction (WpPort * self)
 {
@@ -159,4 +150,4 @@ wp_port_get_direction (WpPort * self)
   const struct pw_port_info *info = d->info;
 
   return (WpDirection) info->direction;
-}
+}

lib/wp/port.h

@@ -14,30 +14,17 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof @WpPort
+ * \brief The different directions that a port can have
- *
+ * \ingroup wpport
- * @brief
- * @em WP_DIRECTION_INPUT: a sink, consuming input
- * @em WP_DIRECTION_OUTPUT: a source, producing output
- *
- * The different directions the endpoint can have
  */
 typedef enum {
-  WP_DIRECTION_INPUT,
+  WP_DIRECTION_INPUT, /*!< a sink, consuming input */
-  WP_DIRECTION_OUTPUT,
+  WP_DIRECTION_OUTPUT, /*!< a source, producing output */
 } WpDirection;
 
 /*!
- * @memberof @WpPort
+ * \brief The WpPort GType
- *
+ * \ingroup wpport
- * @brief The [WpPort](@ref port_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_PORT (wp_port_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_PORT (wp_port_get_type ())
 WP_API

lib/wp/properties.c

@@ -5,43 +5,6 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
- * @file properties.c
- */
-
-/*!
- * @struct WpProperties
- * @section properties_section Properties
- *
- * @brief [WpProperties](@ref properties_section) is a data structure that contains
- * string key-value pairs, which are used to send/receive/attach arbitrary properties
- * to PipeWire objects.
- *
- * This could be thought of as a hash table with strings as both keys and
- * values. However, the reason that this class exists instead of using
- * <a href="https://developer.gnome.org/glib/stable/glib-Hash-Tables.html#GHashTable">
- * GHashTable</a> directly is that in reality it wraps the PipeWire native
- * `struct spa_dict` and `struct pw_properties` and therefore it can be
- * easily passed to PipeWire function calls that require a `struct spa_dict *`
- * or a `struct pw_properties *` as arguments. Or alternatively, it can easily
- * wrap a `struct spa_dict *` or a `struct pw_properties *` that was given
- * from the PipeWire API without necessarily doing an expensive copy operation.
- *
- * [WpProperties](@ref properties_section) normally wraps a `struct pw_properties`,
- * unless it was created with wp_properties_new_wrap_dict(), in which case it wraps a
- * `struct spa_dict` and it is immutable (you cannot add/remove/modify any
- * key-value pair).
- *
- * In most cases, it actually owns the `struct pw_properties`
- * internally and manages its lifetime. The exception to that rule is when
- * [WpProperties](@ref properties_section) is constructed with wp_properties_new_wrap(),
- * in which case the ownership of the `struct pw_properties` remains outside. This must
- * be used with care, as the `struct pw_properties` may be free'ed externally.
- *
- * [WpProperties](@ref properties_section) is reference-counted with wp_properties_ref() and
- * wp_properties_unref().
- *
- */
 
 #define G_LOG_DOMAIN "wp-properties"
 
@@ -50,16 +13,42 @@
 #include <errno.h>
 #include <pipewire/properties.h>
 
+/*! \defgroup wpproperties WpProperties */
+/*!
+ * \struct WpProperties
+ *
+ * WpProperties is a data structure that contains string key-value pairs,
+ * which are used to send/receive/attach arbitrary properties to PipeWire objects.
+ *
+ * This could be thought of as a hash table with strings as both keys and
+ * values. However, the reason that this class exists instead of using
+ * GHashTable directly is that in reality it wraps the PipeWire native
+ * `struct spa_dict` and `struct pw_properties` and therefore it can be
+ * easily passed to PipeWire function calls that require a `struct spa_dict *`
+ * or a `struct pw_properties *` as arguments. Or alternatively, it can easily
+ * wrap a `struct spa_dict *` or a `struct pw_properties *` that was given
+ * from the PipeWire API without necessarily doing an expensive copy operation.
+ *
+ * WpProperties normally wraps a `struct pw_properties`, unless it was created
+ * with wp_properties_new_wrap_dict(), in which case it wraps a
+ * `struct spa_dict` and it is immutable (you cannot add/remove/modify any
+ * key-value pair).
+ *
+ * In most cases, it actually owns the `struct pw_properties`
+ * internally and manages its lifetime. The exception to that rule is when
+ * WpProperties is constructed with wp_properties_new_wrap(), in which case
+ * the ownership of the `struct pw_properties` remains outside. This must
+ * be used with care, as the `struct pw_properties` may be free'ed externally.
+ *
+ * WpProperties is reference-counted with wp_properties_ref() and
+ * wp_properties_unref().
+ */
+
 enum {
   FLAG_IS_DICT = (1<<1),
   FLAG_NO_OWNERSHIP = (1<<2),
 };
 
-/*!
- * @brief
- * @em ref
- * @em flags
- */
 struct _WpProperties
 {
   grefcount ref;
@@ -73,12 +62,10 @@ struct _WpProperties
 G_DEFINE_BOXED_TYPE(WpProperties, wp_properties, wp_properties_ref, wp_properties_unref)
 
 /*!
- * @memberof WpProperties
+ * \brief Creates a new empty properties set
- * @brief Creates a new empty properties set
+ * \ingroup wpproperties
- *
+ * \returns (transfer full): the newly constructed properties set
- * @returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_empty (void)
 {
@@ -90,16 +77,14 @@ wp_properties_new_empty (void)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new properties set that contains the given properties
- * @param key: a property name
- * @...: a property value, followed by any number of further property
- *   key-value pairs, followed by %NULL
  *
- * @brief Constructs a new properties set that contains the given properties
+ * \ingroup wpproperties
- *
+ * \param key a property name
- * @returns (transfer full): the newly constructed properties set
+ * \param ... a property value, followed by any number of further property
+ *   key-value pairs, followed by NULL
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new (const gchar * key, ...)
 {
@@ -114,15 +99,13 @@ wp_properties_new (const gchar * key, ...)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief This is the `va_list` version of wp_properties_new()
- * @param key: a property name
- * @param args: the variable arguments passed to wp_properties_new()
  *
- * @brief This is the `va_list` version of wp_properties_new()
+ * \ingroup wpproperties
- *
+ * \param key a property name
- * @returns (transfer full): the newly constructed properties set
+ * \param args the variable arguments passed to wp_properties_new()
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_valist (const gchar * key, va_list args)
 {
@@ -140,16 +123,14 @@ wp_properties_new_valist (const gchar * key, va_list args)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new properties set that contains the properties that can
- * @param str: a string containing a whitespace separated list of key=value pairs
- *    (ex. "key1=value1 key2=value2")
- *
- * @brief Constructs a new properties set that contains the properties that can
  * be parsed from the given string
  *
- * @returns (transfer full): the newly constructed properties set
+ * \ingroup wpproperties
+ * \param str a string containing a whitespace separated list of key=value pairs
+ *    (ex. "key1=value1 key2=value2")
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_string (const gchar * str)
 {
@@ -165,25 +146,23 @@ wp_properties_new_string (const gchar * str)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new WpProperties that wraps the given \a props structure,
- * @param props: a native `pw_properties` structure to wrap
+ * allowing reading properties on that \a props structure through
+ * the WpProperties API.
  *
- * @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em props structure,
+ * Care must be taken when using this function, since the returned WpProperties
- * allowing reading properties on that @em props structure through
+ * object does not own the \a props structure. Therefore, if the owner decides
- * the [WpProperties](@ref properties_section) API.
+ * to free \a props, the returned WpProperties will crash when used. In addition,
+ * the returned WpProperties object will not try to free \a props when destroyed.
  *
- * Care must be taken when using this function, since the returned [WpProperties](@ref properties_section)
+ * Furthermore, note that the returned WpProperties object is immutable. That
- * object does not own the @em props structure. Therefore, if the owner decides
- * to free @em props, the returned [WpProperties](@ref properties_section) will crash when used. In addition,
- * the returned [WpProperties](@ref properties_section) object will not try to free @em props when destroyed.
- *
- * Furthermore, note that the returned [WpProperties](@ref properties_section) object is immutable. That
  * means that you cannot add or modify any properties on it, unless you make
  * a copy first.
  *
- * @returns (transfer full): the newly constructed properties set
+ * \ingroup wpproperties
+ * \param props a native `pw_properties` structure to wrap
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_wrap (const struct pw_properties * props)
 {
@@ -199,19 +178,17 @@ wp_properties_new_wrap (const struct pw_properties * props)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new WpProperties that wraps the given \a props structure,
- * @param props: a native `pw_properties` structure to wrap
+ * allowing reading & writing properties on that \a props structure through
- *
+ * the WpProperties API.
- * @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em props structure,
- * allowing reading & writing properties on that @em props structure through
- * the [WpProperties](@ref properties_section) API.
  *
  * In constrast with wp_properties_new_wrap(), this function assumes ownership
- * of the @em props structure, so it will try to free @em props when it is destroyed.
+ * of the \a props structure, so it will try to free \a props when it is destroyed.
  *
- * @returns (transfer full): the newly constructed properties set
+ * \ingroup wpproperties
+ * \param props a native `pw_properties` structure to wrap
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_take (struct pw_properties * props)
 {
@@ -227,15 +204,13 @@ wp_properties_new_take (struct pw_properties * props)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new WpProperties that contains a copy of all the properties
- * @param props: a native `pw_properties` structure to copy
+ * contained in the given \a props structure.
  *
- * @brief Constructs a new [WpProperties](@ref properties_section) that contains a copy of all the properties
+ * \ingroup wpproperties
- * contained in the given @em props structure.
+ * \param props a native `pw_properties` structure to copy
- *
+ * \returns (transfer full): the newly constructed properties set
- * @returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_copy (const struct pw_properties * props)
 {
@@ -251,23 +226,21 @@ wp_properties_new_copy (const struct pw_properties * props)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new WpProperties that wraps the given \a dict structure,
- * @param dict: a native `spa_dict` structure to wrap
+ * allowing reading properties from that \a dict through the WpProperties API.
  *
- * @brief Constructs a new [WpProperties](@ref properties_section) that wraps the given @em dict structure,
+ * Note that the returned object does not own the \a dict, so care must be taken
- * allowing reading properties from that @em dict through the [WpProperties](@ref properties_section) API.
+ * not to free it externally while this WpProperties object is alive.
  *
- * Note that the returned object does not own the @em dict, so care must be taken
+ * In addition, note that the returned WpProperties object is immutable. That
- * not to free it externally while this [WpProperties](@ref properties_section) object is alive.
- *
- * In addition, note that the returned [WpProperties](@ref properties_section) object is immutable. That
  * means that you cannot add or modify any properties on it, since there is
  * no defined method for modifying a `struct spa_dict`. If you need to change
  * this properties set later, you should make a copy with wp_properties_copy().
  *
- * @returns (transfer full): the newly constructed properties set
+ * \ingroup wpproperties
+ * \param dict a native `spa_dict` structure to wrap
+ * \returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_wrap_dict (const struct spa_dict * dict)
 {
@@ -283,15 +256,13 @@ wp_properties_new_wrap_dict (const struct spa_dict * dict)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs a new WpProperties that contains a copy of all the
- * @param dict: a native `spa_dict` structure to copy
+ * properties contained in the given \a dict structure.
  *
- * @brief Constructs a new [WpProperties](@ref properties_section) that contains a copy of all the properties
+ * \ingroup wpproperties
- * contained in the given @em dict structure.
+ * \param dict a native `spa_dict` structure to copy
- *
+ * \returns (transfer full): the newly constructed properties set
- * @returns (transfer full): the newly constructed properties set
  */
-
 WpProperties *
 wp_properties_new_copy_dict (const struct spa_dict * dict)
 {
@@ -307,13 +278,12 @@ wp_properties_new_copy_dict (const struct spa_dict * dict)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Constructs and returns a new WpProperties object that contains a copy
- * @param other: a properties object
+ * of all the properties contained in \a other.
  *
- * @brief Constructs and returns a new [WpProperties](@ref properties_section) object that contains a copy
+ * \ingroup wpproperties
- * of all the properties contained in @em other.
+ * \param other a properties object
- *
+ * \returns (transfer full): the newly constructed properties set
- * @returns (transfer full): the newly constructed properties set
  */
 
 WpProperties *
@@ -331,12 +301,10 @@ wp_properties_free (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param self: a properties object
+ * \param self a properties object
- *
+ * \returns (transfer full): \a self with an additional reference count on it
- * @returns (transfer full): @em self with an additional reference count on it
  */
-
 WpProperties *
 wp_properties_ref (WpProperties * self)
 {
@@ -345,13 +313,12 @@ wp_properties_ref (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Decreases the reference count on \a self and frees it when the ref
- * @param self: (transfer full): a properties object
+ * count reaches zero.
  *
- * @brief Decreases the reference count on @em self and frees it when the ref count
+ * \ingroup wpproperties
- * reaches zero.
+ * \param self (transfer full): a properties object
  */
-
 void
 wp_properties_unref (WpProperties * self)
 {
@@ -360,20 +327,20 @@ wp_properties_unref (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Ensures that the given properties set is uniquely owned.
- * @param self: (transfer full): a properties object
  *
- * @brief Ensures that the given properties set is uniquely owned, which means:
+ * "Uniquely owned" means that:
  *  - its reference count is 1
  *  - it is not wrapping a native `spa_dict` or `pw_properties` object
  *
- * If @em self is not uniquely owned already, then it is unrefed and a copy of
+ * If \a self is not uniquely owned already, then it is unrefed and a copy of
- * it is returned instead. You should always consider @em self as unsafe to use
+ * it is returned instead. You should always consider \a self as unsafe to use
  * after this call and you should use the returned object instead.
  *
- * @returns (transfer full): the uniquely owned properties object
+ * \ingroup wpproperties
+ * \param self (transfer full): a properties object
+ * \returns (transfer full): the uniquely owned properties object
  */
-
 WpProperties *
 wp_properties_ensure_unique_owner (WpProperties * self)
 {
@@ -388,17 +355,16 @@ wp_properties_ensure_unique_owner (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Updates (adds new or modifies existing) properties in \a self,
- * @param self: a properties object
+ * using the given \a props as a source.
- * @param props: a properties set that contains properties to update
  *
- * @brief Updates (adds new or modifies existing) properties in @em self, using the
+ * Any properties that are not contained in \a props are left untouched.
- * given @em props as a source. Any properties that are not contained in @em props
- * are left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param props a properties set that contains properties to update
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_update (WpProperties * self, WpProperties * props)
 {
@@ -410,17 +376,16 @@ wp_properties_update (WpProperties * self, WpProperties * props)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Updates (adds new or modifies existing) properties in \a self,
- * @param self: a properties object
+ * using the given \a dict as a source.
- * @param dict: a `spa_dict` that contains properties to update
  *
- * @brief Updates (adds new or modifies existing) properties in @em self, using the
+ * Any properties that are not contained in \a dict are left untouched.
- * given @em dict as a source. Any properties that are not contained in @em dict
- * are left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param dict a `spa_dict` that contains properties to update
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_update_from_dict (WpProperties * self,
     const struct spa_dict * dict)
@@ -433,18 +398,17 @@ wp_properties_update_from_dict (WpProperties * self,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Adds new properties in \a self, using the given \a props as a source.
- * @param self: a properties object
- * @param props: a properties set that contains properties to add
  *
- * @brief Adds new properties in @em self, using the given @em props as a source.
+ * Properties (keys) from \a props that are already contained in \a self
- * Properties (keys) from @em props that are already contained in @em self
  * are not modified, unlike what happens with wp_properties_update().
- * Properties in @em self that are not contained in @em props are left untouched.
+ * Properties in \a self that are not contained in \a props are left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param props a properties set that contains properties to add
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_add (WpProperties * self, WpProperties * props)
 {
@@ -456,18 +420,17 @@ wp_properties_add (WpProperties * self, WpProperties * props)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Adds new properties in \a self, using the given \a dict as a source.
- * @param self: a properties object
- * @param dict: a `spa_dict` that contains properties to add
  *
- * @brief Adds new properties in @em self, using the given @em dict as a source.
+ * Properties (keys) from \a dict that are already contained in \a self
- * Properties (keys) from @em dict that are already contained in @em self
  * are not modified, unlike what happens with wp_properties_update_from_dict().
- * Properties in @em self that are not contained in @em dict are left untouched.
+ * Properties in \a self that are not contained in \a dict are left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param dict a `spa_dict` that contains properties to add
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_add_from_dict (WpProperties * self,
     const struct spa_dict * dict)
@@ -480,20 +443,19 @@ wp_properties_add_from_dict (WpProperties * self,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Updates (adds new or modifies existing) properties in \a self,
- * @param self: a properties set
+ * using the given \a props as a source.
- * @param props: a properties set that contains properties to update
- * @param key1: a property to update
- * @...: a list of additional properties to update, followed by %NULL
  *
- * @brief Updates (adds new or modifies existing) properties in @em self, using the
- * given @em props as a source.
  * Unlike wp_properties_update(), this function only updates properties that
  * have one of the specified keys; the rest is left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param props a properties set that contains properties to update
+ * \param key1 a property to update
+ * \param ... a list of additional properties to update, followed by NULL
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_update_keys (WpProperties * self, WpProperties * props,
     const gchar * key1, ...)
@@ -515,20 +477,19 @@ wp_properties_update_keys (WpProperties * self, WpProperties * props,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Updates (adds new or modifies existing) properties in \a self,
- * @param self: a properties set
+ * using the given \a dict as a source.
- * @param dict: a `spa_dict` that contains properties to update
- * @param key1: a property to update
- * @...: a list of additional properties to update, followed by %NULL
  *
- * @brief Updates (adds new or modifies existing) properties in @em self, using the
- * given @em dict as a source.
  * Unlike wp_properties_update_from_dict(), this function only updates
  * properties that have one of the specified keys; the rest is left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param dict a `spa_dict` that contains properties to update
+ * \param key1 a property to update
+ * \param ... a list of additional properties to update, followed by NULL
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_update_keys_from_dict (WpProperties * self,
     const struct spa_dict * dict, const gchar * key1, ...)
@@ -550,17 +511,15 @@ wp_properties_update_keys_from_dict (WpProperties * self,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief The same as wp_properties_update_keys(), using a NULL-terminated array
- * @param self: a properties set
- * @param props: a properties set that contains properties to update
- * @param keys: (array zero-terminated=1): the properties to update
- *
- * @brief The same as wp_properties_update_keys(), using a NULL-terminated array
  * for specifying the keys to update
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param props a properties set that contains properties to update
+ * \param keys (array zero-terminated=1): the properties to update
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_update_keys_array (WpProperties * self, WpProperties * props,
     const gchar * keys[])
@@ -574,19 +533,18 @@ wp_properties_update_keys_array (WpProperties * self, WpProperties * props,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Adds new properties in \a self, using the given \a props as a source.
- * @param self: a properties set
- * @param props: a properties set that contains properties to add
- * @param key1: a property to add
- * @...: a list of additional properties to add, followed by %NULL
  *
- * @brief Adds new properties in @em self, using the given @em props as a source.
  * Unlike wp_properties_add(), this function only adds properties that
  * have one of the specified keys; the rest is left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param props a properties set that contains properties to add
+ * \param key1 a property to add
+ * \param ... a list of additional properties to add, followed by NULL
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_add_keys (WpProperties * self, WpProperties * props,
     const gchar * key1, ...)
@@ -610,19 +568,18 @@ wp_properties_add_keys (WpProperties * self, WpProperties * props,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Adds new properties in \a self, using the given \a dict as a source.
- * @param self: a properties set
- * @param dict: a `spa_dict` that contains properties to add
- * @param key1: a property to add
- * @...: a list of additional properties to add, followed by %NULL
  *
- * @brief Adds new properties in @em self, using the given @em dict as a source.
  * Unlike wp_properties_add_from_dict(), this function only adds
  * properties that have one of the specified keys; the rest is left untouched.
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param dict a `spa_dict` that contains properties to add
+ * \param key1 a property to add
+ * \param ... a list of additional properties to add, followed by NULL
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_add_keys_from_dict (WpProperties * self,
     const struct spa_dict * dict, const gchar * key1, ...)
@@ -646,17 +603,15 @@ wp_properties_add_keys_from_dict (WpProperties * self,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief The same as wp_properties_add_keys(), using a NULL-terminated array
- * @param self: a properties set
- * @param props: a properties set that contains properties to add
- * @param keys: (array zero-terminated=1): the properties to add
- *
- * @brief The same as wp_properties_add_keys(), using a NULL-terminated array
  * for specifying the keys to add
  *
- * @returns the number of properties that were changed
+ * \ingroup wpproperties
+ * \param self a properties set
+ * \param props a properties set that contains properties to add
+ * \param keys (array zero-terminated=1): the properties to add
+ * \returns the number of properties that were changed
  */
-
 gint
 wp_properties_add_keys_array (WpProperties * self, WpProperties * props,
     const gchar * keys[])
@@ -670,14 +625,12 @@ wp_properties_add_keys_array (WpProperties * self, WpProperties * props,
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param self: a properties object
+ * \param self a properties object
- * @param key: a property key
+ * \param key a property key
- *
+ * \returns (transfer none) (nullable): the value of the property identified
- * @returns (transfer none) (nullable): the value of the property identified
+ *   with \a key, or NULL if this property is not contained in \a self
- *   with @em key, or %NULL if this property is not contained in @em self
  */
-
 const gchar *
 wp_properties_get (WpProperties * self, const gchar * key)
 {
@@ -688,21 +641,20 @@ wp_properties_get (WpProperties * self, const gchar * key)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Sets the given property \a key - \a value pair on \a self.
- * @param self: a properties object
- * @param key: a property key
- * @param value: (nullable): a property value
  *
- * @brief Sets the given property @em key - @em value pair on @em self. If the property
+ * If the property already existed, the value is overwritten with the new one.
- * already existed, the value is overwritten with the new one.
  *
- * If the @em value is %NULL, then the specified property is removed from @em self
+ * If the \a value is NULL, then the specified property is removed from \a self
  *
- * @returns %1 if the property was changed. %0 if nothing was changed because
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param key a property key
+ * \param value (nullable): a property value
+ * \returns 1 if the property was changed. 0 if nothing was changed because
  *   the property already existed with the same value or because the key to
  *   remove did not exist.
  */
-
 gint
 wp_properties_set (WpProperties * self, const gchar * key,
     const gchar * value)
@@ -715,20 +667,18 @@ wp_properties_set (WpProperties * self, const gchar * key,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Formats the given \a format string with the specified arguments
- * @param self: a properties object
+ * and sets the result as a value of the property specified with \a key
- * @param key: a property key
- * @param format: a printf-style format to be formatted and set as a value for
- *   this property @em key
- * @...: arguments for @em format
  *
- * @brief Formats the given @em format string with the specified arguments and sets the
+ * \ingroup wpproperties
- * result as a value of the property specified with @em key
+ * \param self a properties object
- *
+ * \param key a property key
- * @returns %1 if the property was changed. %0 if nothing was changed because
+ * \param format a printf-style format to be formatted and set as a value for
+ *   this property \a key
+ * \param ... arguments for \a format
+ * \returns 1 if the property was changed. 0 if nothing was changed because
  *   the property already existed with the same value
  */
-
 gint
 wp_properties_setf (WpProperties * self, const gchar * key,
     const gchar * format, ...)
@@ -744,19 +694,17 @@ wp_properties_setf (WpProperties * self, const gchar * key,
 }
 
 /*!
- * @memberof WpProperties
+ * \brief This is the `va_list` version of wp_properties_setf()
- * @param self: a properties object
- * @param key: a property key
- * @param format: a printf-style format to be formatted and set as a value for
- *   this property @em key
- * @param args: the variable arguments passed to wp_properties_setf()
  *
- * @brief This is the `va_list` version of wp_properties_setf()
+ * \ingroup wpproperties
- *
+ * \param self a properties object
- * @returns %1 if the property was changed. %0 if nothing was changed because
+ * \param key a property key
+ * \param format a printf-style format to be formatted and set as a value for
+ *   this property \a key
+ * \param args the variable arguments passed to wp_properties_setf()
+ * \returns 1 if the property was changed. 0 if nothing was changed because
  *   the property already existed with the same value
  */
-
 gint
 wp_properties_setf_valist (WpProperties * self, const gchar * key,
     const gchar * format, va_list args)
@@ -830,15 +778,13 @@ static const WpIteratorMethods dict_iterator_methods = {
 };
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param self: a properties object
+ * \param self a properties object
- *
+ * \returns (transfer full): an iterator that iterates over the properties.
- * @returns (transfer full): an iterator that iterates over the properties.
  *   Use wp_properties_iterator_item_get_key() and
  *   wp_properties_iterator_item_get_value() to parse the items returned by
  *   this iterator.
  */
-
 WpIterator *
 wp_properties_new_iterator (WpProperties * self)
 {
@@ -856,15 +802,11 @@ wp_properties_new_iterator (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param item: a
+ * \param item a GValue that was returned from the WpIterator of
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue">
- * GValue</a> that was returned from the [WpProperties](@ref properties_section) of
  *   wp_properties_new_iterator()
- *
+ * \returns (transfer none): the property key of the \a item
- * @returns (transfer none): the property key of the @em item
  */
-
 const gchar *
 wp_properties_iterator_item_get_key (const GValue * item)
 {
@@ -874,16 +816,11 @@ wp_properties_iterator_item_get_key (const GValue * item)
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- *
+ * \param item a GValue that was returned from the WpIterator of
- * @param item: a
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Generic-values.html#GValue">
- * GValue</a> that was returned from the [WpProperties](@ref properties_section) of
  *   wp_properties_new_iterator()
- *
+ * \returns (transfer none): the property value of the \a item
- * @returns (transfer none): the property value of the @em item
  */
-
 const gchar *
 wp_properties_iterator_item_get_value (const GValue * item)
 {
@@ -893,9 +830,9 @@ wp_properties_iterator_item_get_value (const GValue * item)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Sorts the keys in alphabetical order
- * @param self: a properties object
+ * \ingroup wpproperties
- *
+ * \param self a properties object
  */
 void
 wp_properties_sort (WpProperties * self)
@@ -908,12 +845,10 @@ wp_properties_sort (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param self: a properties object
+ * \param self a properties object
- *
+ * \returns (transfer none): the internal properties set as a `struct spa_dict *`
- * @returns (transfer none): the internal properties set as a `struct spa_dict *`
  */
-
 const struct spa_dict *
 wp_properties_peek_dict (WpProperties * self)
 {
@@ -923,13 +858,11 @@ wp_properties_peek_dict (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \ingroup wpproperties
- * @param self: a properties object
+ * \param self a properties object
- *
+ * \returns (transfer full): a copy of the properties in \a self
- * @returns (transfer full): a copy of the properties in @em self
  *   as a `struct pw_properties`
  */
-
 struct pw_properties *
 wp_properties_to_pw_properties (WpProperties * self)
 {
@@ -939,49 +872,45 @@ wp_properties_to_pw_properties (WpProperties * self)
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Similar to wp_properties_to_pw_properties(), but this method avoids making
- * @param self: (transfer full): a properties object
- *
- * @brief Similar to wp_properties_to_pw_properties(), but this method avoids making
  * a copy of the properties by returning the `struct pw_properties` that is
- * stored internally and then freeing the [WpProperties](@ref properties_section) wrapper.
+ * stored internally and then freeing the WpProperties wrapper.
  *
- * If @em self is not uniquely owned (see wp_properties_ensure_unique_owner()),
+ * If \a self is not uniquely owned (see wp_properties_ensure_unique_owner()),
  * then this method does make a copy and is the same as
  * wp_properties_to_pw_properties(), performance-wise.
  *
- * @returns (transfer full): the properties in @em self as a `struct pw_properties`
+ * \ingroup wpproperties
+ * \param self (transfer full): a properties object
+ * \returns (transfer full): the properties in \a self as a `struct pw_properties`
  */
-
 struct pw_properties *
 wp_properties_unref_and_take_pw_properties (WpProperties * self)
 {
   g_return_val_if_fail (self != NULL, NULL);
 
   g_autoptr (WpProperties) unique = wp_properties_ensure_unique_owner (self);
-  /* set the flag so that unref-ing @em unique will not destroy unique->props */
+  /* set the flag so that unref-ing \a unique will not destroy unique->props */
   unique->flags = FLAG_NO_OWNERSHIP;
   return unique->props;
 }
 
 /*!
- * @memberof WpProperties
+ * \brief Checks if all property values contained in \a other are matching with
- * @param self: a properties object
+ * the values in \a self.
- * @param other: a set of properties to match
  *
- * @brief Checks if all property values contained in @em other are matching with the
+ * If a property is contained in \a other and not in \a self, the result is not
- * values in @em self.
- *
- * If a property is contained in @em other and not in @em self, the result is not
  * matched. If a property is contained in both sets, then the value of the
- * property in @em other is interpreted as a glob-style pattern
+ * property in \a other is interpreted as a glob-style pattern
- * (using g_pattern_match_simple()) and the value in @em self is checked to
+ * (using g_pattern_match_simple()) and the value in \a self is checked to
  * see if it matches with this pattern.
  *
- * @returns %TRUE if all matches were successfull, %FALSE if at least one
+ * \ingroup wpproperties
+ * \param self a properties object
+ * \param other a set of properties to match
+ * \returns TRUE if all matches were successfull, FALSE if at least one
  *   property value did not match
  */
-
 gboolean
 wp_properties_matches (WpProperties * self, WpProperties *other)
 {
@@ -1000,4 +929,4 @@ wp_properties_matches (WpProperties * self, WpProperties *other)
   }
 
   return TRUE;
-}
+}

lib/wp/properties.h

@@ -19,16 +19,8 @@ struct pw_properties;
 struct spa_dict;
 
 /*!
- * @memberof WpProperties
+ * \brief The WpProperties GType
- *
+ * \ingroup wpproperties
- * @brief The [WpProperties](@ref properties_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_PROPERTIES (wp_properties_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_PROPERTIES (wp_properties_get_type ())
 WP_API

lib/wp/proxy-interfaces.c

@@ -5,76 +5,55 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
+
- * @file proxy-interfaces.c
- */
 #define G_LOG_DOMAIN "wp-proxy-ifaces"
 
 #include "proxy-interfaces.h"
 #include "properties.h"
 
+/*! \defgroup wppipewireobject WpPipewireObject */
 /*!
- * @section proxy_interfaces_section PipeWire Object Proxy Interfaces
+ * \struct WpPipewireObject
  *
- * @struct WpPipewireObject
+ * An interface for standard PipeWire objects.
- * @section pipewire_object_section PipeWire Object
  *
- * @brief An interface for standard PipeWire objects. The common characteristic
+ * The common characteristic of all objects that implement this interface is
- * of all objects that implement this interface is the presence of
+ * the presence of an "info" structure that contains additional properties
- * an "info" structure that contains additional properties for this object
+ * for this object (in the form of a spa_dict / pw_properties) and optionally
- * (in the form of a spa_dict / pw_properties) and optionally also
+ * also some parameters that can be enumerated and set on the object.
- * some parameters that can be enumerated and set on the object.
  *
- * @section pipewire_object_signals_section Signals
+ * \gproperties
  *
- * @b params-changed
+ * \gproperty{properties, WpProperties *, G_PARAM_READABLE,
+ *   The properties of the pipewire object}
  *
- * @code
+ * \gproperty{param-info, GVariant * (a{ss}), G_PARAM_READABLE,
+ *   The param info of the object}
+ *
+ * \gproperty{native-info, gpointer, G_PARAM_READABLE,
+ *   The native info structure}
+ *
+ * \gsignals
+ *
+ * \par params-changed
+ * \parblock
+ * \code
  * params_changed_callback (WpPipewireObject * self,
  *                          guint id,
  *                          gpointer user_data)
- * @endcode
+ * \endcode
  *
- * Emitted when the params for id have changed. On proxies that cache params from a remote object,
+ * Emitted when the params for id have changed. On proxies that cache params
- * this is emitted after the cached values have changed.
+ * from a remote object, this is emitted after the cached values have changed.
  *
- * You can expect this to be emitted only when the relevant WP_PIPEWIRE_OBJECT_FEATURE_PARAM_*
+ * You can expect this to be emitted only when the relevant
- * has been activated.
+ * WP_PIPEWIRE_OBJECT_FEATURE_PARAM_* has been activated.
  *
- * @b Parameters:
+ * Parameters:
- *
+ * - `id` - the parameter id
- * @arg `self` - the pipewire object
- * @arg `is` - the parameter id
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @section plugin_props_section Properties
- *
- * @b native-info
- *
- * @code
- * "native-info" gpointer
- * @endcode
- *
- * Flags : Read
- *
- * @b param-info
- *
- * @code
- * "param-info" GVariant *
- * @endcode
- *
- * Flags : Read
- *
- * @b properties
- *
- * @code
- * "properties" WpProperties *
- * @endcode
- *
- * Flags : Read
  *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
  */
 
 G_DEFINE_INTERFACE (WpPipewireObject, wp_pipewire_object, WP_TYPE_PROXY)
@@ -97,32 +76,20 @@ wp_pipewire_object_default_init (WpPipewireObjectInterface * iface)
           "The param info of the object", G_VARIANT_TYPE ("a{ss}"), NULL,
           G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
 
-  /*
-   * WpPipewireObject::params-changed:
-   * @self: the pipewire object
-   * @id: the parameter id
-   *
-   * @brief Emitted when the params for @em id have changed. On proxies that cache
-   * params from a remote object, this is emitted after the cached values
-   * have changed.
-   *
-   * You can expect this to be emitted only when the relevant
-   * WP_PIPEWIRE_OBJECT_FEATURE_PARAM_* has been activated.
-   */
   g_signal_new ("params-changed", G_TYPE_FROM_INTERFACE (iface),
       G_SIGNAL_RUN_FIRST, 0, NULL, NULL, NULL, G_TYPE_NONE, 1, G_TYPE_UINT);
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Retrieves the native infor structure of this object
- * @param self: the pipewire object
+ * (pw_node_info, pw_port_info, etc...)
  *
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns (nullable): the native pipewire info structure of this object
+ * \ingroup wppipewireobject
- *    (pw_node_info, pw_port_info, etc...)
+ * \param self the pipewire object
+ * \returns (nullable): the native pipewire info structure of this object
  */
-
 gconstpointer
 wp_pipewire_object_get_native_info (WpPipewireObject * self)
 {
@@ -134,15 +101,15 @@ wp_pipewire_object_get_native_info (WpPipewireObject * self)
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Retrieves the PipeWire properties of this object
- * @param self: the pipewire object
  *
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns (transfer full): the pipewire properties of this object;
+ * \ingroup wppipewireobject
+ * \param self the pipewire object
+ * \returns (transfer full): the pipewire properties of this object;
  *   normally these are the properties that are part of the info structure
  */
-
 WpProperties *
 wp_pipewire_object_get_properties (WpPipewireObject * self)
 {
@@ -154,17 +121,17 @@ wp_pipewire_object_get_properties (WpPipewireObject * self)
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Iterates over the object's PipeWire properties
- * @param self: the pipewire object
  *
- * @brief Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns (transfer full): an iterator that iterates over the pipewire
+ * \ingroup wppipewireobject
+ * \param self the pipewire object
+ * \returns (transfer full): an iterator that iterates over the pipewire
  *   properties of this object. Use wp_properties_iterator_item_get_key() and
  *   wp_properties_iterator_item_get_value() to parse the items returned by
  *   this iterator.
  */
-
 WpIterator *
 wp_pipewire_object_new_properties_iterator (WpPipewireObject * self)
 {
@@ -174,25 +141,24 @@ wp_pipewire_object_new_properties_iterator (WpPipewireObject * self)
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Returns the value of a single pipewire property.
- * @param self: the pipewire object
- * @param key: the property name
  *
- * @brief Returns the value of a single pipewire property. This is the same as getting
+ * This is the same as getting the whole properties structure with
- * the whole properties structure with wp_pipewire_object_get_properties() and
+ * wp_pipewire_object_get_properties() and accessing a single property with
- * accessing a single property with wp_properties_get(), but saves one call
+ * wp_properties_get(), but saves one call and having to clean up the
- * and having to clean up the [WpProperties](@ref properties_section)
+ * WpProperties reference count afterwards.
- * reference count afterwards.
  *
  * The value is owned by the proxy, but it is guaranteed to stay alive
  * until execution returns back to the event loop.
  *
- * Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns (transfer none) (nullable): the value of the pipewire property @em key
+ * \ingroup wppipewireobject
- *   or %NULL if the property doesn't exist
+ * \param self the pipewire object
+ * \param key the property name
+ * \returns (transfer none) (nullable): the value of the pipewire property
+ *   \a key or NULL if the property doesn't exist
  */
-
 const gchar *
 wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
 {
@@ -202,14 +168,12 @@ wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Returns the available parameters of this pipewire object.
- * @param self: the pipewire object
  *
- * @brief Returns the available parameters of this pipewire object. The return value
+ * The return value is a GVariant of type `a{ss}`, where the key of each map
- * is a variant of type `a{ss}`, where the key of each map entry is a spa param
+ * entry is a spa param type id (the same ids that you can pass in
- * type id (the same ids that you can pass in wp_pipewire_object_enum_params())
+ * wp_pipewire_object_enum_params()) and the value is a string that can
- * and the value is a string that can contain the following letters,
+ * contain the following letters, each of them representing a flag:
- * each of them representing a flag:
  *   - `r`: the param is readable (`SPA_PARAM_INFO_READ`)
  *   - `w`: the param is writable (`SPA_PARAM_INFO_WRITE`)
  *
@@ -218,12 +182,13 @@ wp_pipewire_object_get_property (WpPipewireObject * self, const gchar * key)
  *
  * Params that are writable can be set with wp_pipewire_object_set_param()
  *
- * Requires %WP_PIPEWIRE_OBJECT_FEATURE_INFO
+ * \remark Requires WP_PIPEWIRE_OBJECT_FEATURE_INFO
  *
- * @returns (transfer full) (nullable): a variant of type `a{ss}` or %NULL
+ * \ingroup wppipewireobject
+ * \param self the pipewire object
+ * \returns (transfer full) (nullable): a variant of type `a{ss}` or NULL
  *   if the object does not support params at all
  */
-
 GVariant *
 wp_pipewire_object_get_param_info (WpPipewireObject * self)
 {
@@ -235,21 +200,21 @@ wp_pipewire_object_get_param_info (WpPipewireObject * self)
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Enumerate object parameters.
- * @param self: the pipewire object
- * @param id: (nullable): the parameter id to enumerate or %NULL for all parameters
- * @param filter: (nullable): a param filter or %NULL
- * @param cancellable: (nullable): a cancellable for the async operation
- * @param callback: (scope async): a callback to call with the result
- * @param user_data: (closure): data to pass to @em callback
  *
- * @brief Enumerate object parameters. This will asynchronously return the result,
+ * This will asynchronously return the result, or an error, by calling the
- * or an error, by calling the given @em callback. The result is going to
+ * given \a callback. The result is going to be a WpIterator containing
- * be a [WpIterator](@ref iterator_section) containing
+ * WpSpaPod objects, which can be retrieved
- * [WpSpaPod](@ref spa_pod_section) objects, which can be retrieved
  * with wp_pipewire_object_enum_params_finish().
+ *
+ * \ingroup wppipewireobject
+ * \param self the pipewire object
+ * \param id (nullable): the parameter id to enumerate or NULL for all parameters
+ * \param filter (nullable): a param filter or NULL
+ * \param cancellable (nullable): a cancellable for the async operation
+ * \param callback (scope async): a callback to call with the result
+ * \param user_data (closure): data to pass to \a callback
  */
-
 void
 wp_pipewire_object_enum_params (WpPipewireObject * self, const gchar * id,
     WpSpaPod *filter, GCancellable * cancellable,
@@ -263,16 +228,14 @@ wp_pipewire_object_enum_params (WpPipewireObject * self, const gchar * id,
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \ingroup wppipewireobject
- * @param self: the pipewire object
+ * \param self the pipewire object
- * @param res: the async result
+ * \param res the async result
- * @param error: (out) (optional): the reported error of the operation, if any
+ * \param error (out) (optional): the reported error of the operation, if any
- *
+ * \returns (transfer full) (nullable): an iterator to iterate over the
- * @returns (transfer full) (nullable): an iterator to iterate over the
+ *   collected params, or NULL if the operation resulted in error;
- *   collected params, or %NULL if the operation resulted in error;
+ *   the items in the iterator are WpSpaPod
- *   the items in the iterator are [WpSpaPod](@ref spa_pod_section)
  */
-
 WpIterator *
 wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
     GAsyncResult * res, GError ** error)
@@ -286,15 +249,11 @@ wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief This method can be used to retrieve object parameters in a synchronous
- * @param self: the pipewire object
+ * way (in contrast with wp_pipewire_object_enum_params(), which is async).
- * @param id: the parameter id to enumerate
- * @param filter: (nullable): a param filter or %NULL
  *
- * @brief This method can be used to retrieve object parameters in a synchronous way
+ * The `WP_PIPEWIRE_OBJECT_FEATURE_PARAM_<something>` feature
- * (in contrast with wp_pipewire_object_enum_params(), which is async),
+ * that corresponds to the specified \a id must have been activated earlier.
- * provided that the `WP_PIPEWIRE_OBJECT_FEATURE_PARAM_<something>` feature
- * that corresponds to the specified @em id has been activated earlier.
  * These features enable monitoring and caching of params underneath, so that
  * they are always available for retrieval with this method.
  *
@@ -303,11 +262,14 @@ wp_pipewire_object_enum_params_finish (WpPipewireObject * self,
  * able to update them yet, so if you really need up-to-date information you
  * should only rely on wp_pipewire_object_enum_params() instead.
  *
- * @returns (transfer full) (nullable): an iterator to iterate over cached
+ * \ingroup wppipewireobject
- *    parameters, or %NULL if paramteres for this @em id are not cached;
+ * \param self the pipewire object
- *    the items in the iterator are [WpSpaPod](@ref spa_pod_section)
+ * \param id the parameter id to enumerate
+ * \param filter (nullable): a param filter or NULL
+ * \returns (transfer full) (nullable): an iterator to iterate over cached
+ *    parameters, or NULL if parameters for this \a id are not cached;
+ *    the items in the iterator are WpSpaPod
  */
-
 WpIterator *
 wp_pipewire_object_enum_params_sync (WpPipewireObject * self,
     const gchar * id, WpSpaPod * filter)
@@ -321,17 +283,15 @@ wp_pipewire_object_enum_params_sync (WpPipewireObject * self,
 }
 
 /*!
- * @memberof WpPipewireObject
+ * \brief Sets a parameter on the object.
- * @param self: the pipewire object
- * @param id: the parameter id to set
- * @param flags: optional flags or 0
- * @param param: (transfer full): the parameter to set
  *
- * @brief Sets a parameter on the object.
+ * \ingroup wppipewireobject
- *
+ * \param self the pipewire object
- * @returns %TRUE on success, %FALSE if setting the param failed
+ * \param id the parameter id to set
+ * \param flags optional flags or 0
+ * \param param (transfer full): the parameter to set
+ * \returns TRUE on success, FALSE if setting the param failed
  */
-
 gboolean
 wp_pipewire_object_set_param (WpPipewireObject * self, const gchar * id,
     guint32 flags, WpSpaPod * param)
@@ -341,4 +301,4 @@ wp_pipewire_object_set_param (WpPipewireObject * self, const gchar * id,
 
   return WP_PIPEWIRE_OBJECT_GET_IFACE (self)->set_param (self, id, flags,
       param);
-}
+}

lib/wp/proxy-interfaces.h

@@ -16,26 +16,14 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpPipewireObject
+ * \brief The WpPipewireObject GType
- *
+ * \ingroup wppipewireobject
- * @brief The [WpPipewireObject](@ref pipewire_object_section) 
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_PIPEWIRE_OBJECT (wp_pipewire_object_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_PIPEWIRE_OBJECT (wp_pipewire_object_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpPipewireObject, wp_pipewire_object,
                      WP, PIPEWIRE_OBJECT, WpProxy)
 
-/*!
- * @brief
- * @em parent_iface
- */
 struct _WpPipewireObjectInterface
 {
   GTypeInterface parent_iface;

lib/wp/proxy.c

@@ -5,9 +5,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
+
- * @file proxy.c
- */
 #define G_LOG_DOMAIN "wp-proxy"
 
 #include "proxy.h"
@@ -18,6 +16,85 @@
 #include <spa/utils/hook.h>
 #include <spa/utils/result.h>
 
+/*! \defgroup wpproxy WpProxy */
+/*!
+ * \struct WpProxy
+ *
+ * Base class for all objects that expose PipeWire objects using `pw_proxy`
+ * underneath.
+ *
+ * This base class cannot be instantiated. It provides handling of
+ * pw_proxy's events and exposes common functionality.
+ *
+ * \gproperties
+ *
+ * \gproperty{bound-id, guint, G_PARAM_READABLE,
+ *   The id that this object has on the registry}
+ *
+ * \gproperty{pw-proxy, gpointer, G_PARAM_READABLE,
+ *   The `struct pw_proxy *`}
+ *
+ * \gsignals
+ *
+ * \par bound
+ * \parblock
+ * \code
+ * void
+ * bound_callback (WpProxy * self,
+ *                 guint id,
+ *                 gpointer user_data)
+ * \endcode
+ * Parameters:
+ * - `id` - the bound id of the proxy
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par pw-proxy-created
+ * \parblock
+ * \code
+ * void
+ * pw_proxy_created_callback (WpProxy * self,
+ *                            gpointer object,
+ *                            gpointer user_data)
+ * \endcode
+ * Parameters:
+ * - `object` - pointer to the pw_proxy that was just created
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par pw-proxy-destroyed
+ * \parblock
+ * \code
+ * void
+ * pw_proxy_destroyed_callback (WpProxy * self,
+ *                              gpointer user_data)
+ * \endcode
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ *
+ * \par error
+ * \parblock
+ * \code
+ * void
+ * error_callback (WpProxy * self,
+ *                 gint seq, gint res, const gchar *message,
+ *                 gpointer user_data)
+ * \endcode
+ * Emitted when an error occurs on the remote object.
+ * The parameters are exactly the same as on the underlying pw_proxy error
+ * callback.
+ *
+ * Parameters:
+ * - `seq` - the sequence number of the operation that caused the error
+ * - `res` - the error code
+ * - `message` - a description of the error
+ *
+ * Flags: G_SIGNAL_RUN_FIRST
+ * \endparblock
+ */
+
 typedef struct _WpProxyPrivate WpProxyPrivate;
 struct _WpProxyPrivate
 {
@@ -25,82 +102,12 @@ struct _WpProxyPrivate
   struct spa_hook listener;
 };
 
-/*!
- * @memberof WpProxy
- *
- * @props @b bound-id
- *
- * @code
- * "bound-id" guint
- * @endcode
- *
- * Flags : Read
- *
- * @props @b pw-proxy
- *
- * @code
- * "pw-proxy" gpointer
- * @endcode
- *
- * Flags : Read
- *
- */
 enum {
   PROP_0,
   PROP_BOUND_ID,
   PROP_PW_PROXY,
 };
 
-/*!
- * @memberof WpProxy
- *
- * @signal @b bound
- *
- * @code
- * bound_callback (WpProxy * self,
- *                 guint object,
- *                 gpointer user_data)
- * @endcode
- *
- * @b Parameters:
- *
- * @arg `self`
- * @arg `object`
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @signal @b pw-proxy-created
- *
- * @code
- * pw_proxy_created_callback (WpProxy * self,
- *                            gpointer object,
- *                            gpointer user_data)
- * @endcode
- *
- * @b Parameters:
- *
- * @arg `self`
- * @arg `object`
- * @arg `user_data`
- *
- * Flags: Run First
- *
- * @signal @b pw-proxy-destroyed
- *
- * @code
- * pw_proxy_destroyed_callback (WpProxy * self,
- *                            gpointer user_data)
- * @endcode
- *
- * @b Parameters:
- *
- * @arg `self`
- * @arg `user_data`
- *
- * Flags: Run First
- *
- */
 enum
 {
   SIGNAL_PW_PROXY_CREATED,
@@ -112,18 +119,6 @@ enum
 
 static guint signals[LAST_SIGNAL] = { 0 };
 
-/*!
- * @struct WpProxy
- * @section proxy_section Pipewire Object Proxy
- *
- * @brief Base class for all objects that expose PipeWire objects using `pw_proxy`
- * underneath.
- *
- * This base class cannot be instantiated. It provides handling of
- * pw_proxy's events and exposes common functionality.
- *
- */
-
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpProxy, wp_proxy, WP_TYPE_OBJECT)
 
 static void
@@ -255,16 +250,18 @@ wp_proxy_class_init (WpProxyClass * klass)
 }
 
 /*!
- * @memberof WpProxy
+ * \brief Returns the proxy bound id.
- * @param self: the proxy
  *
- * @brief Returns the bound id, which is the id that this object has on the
+ * The bound id is the id that this object has on the
- * pipewire registry (a.k.a. the global id). The object must have the
+ * PipeWire registry (a.k.a. the global id). The object must have the
- * %WP_PROXY_FEATURE_BOUND feature before this method can be called.
+ * WP_PROXY_FEATURE_BOUND feature before this method can be called.
  *
- * @returns the bound id of this object
+ * \remarks Requires WP_PROXY_FEATURE_BOUND
+ *
+ * \ingroup wpproxy
+ * \param self the proxy
+ * \returns the bound id of this object
  */
-
 guint32
 wp_proxy_get_bound_id (WpProxy * self)
 {
@@ -277,13 +274,11 @@ wp_proxy_get_bound_id (WpProxy * self)
 }
 
 /*!
- * @memberof WpProxy
+ * \ingroup wpproxy
- * @param self: the proxy
+ * \param self the proxy
- * @param version: (out) (optional): the version of the interface
+ * \param version (out) (optional): the version of the interface
- *
+ * \returns the PipeWire type of the interface that is being proxied
- * @returns the PipeWire type of the interface that is being proxied
  */
-
 const gchar *
 wp_proxy_get_interface_type (WpProxy * self, guint32 * version)
 {
@@ -301,12 +296,10 @@ wp_proxy_get_interface_type (WpProxy * self, guint32 * version)
 }
 
 /*!
- * @memberof WpProxy
+ * \ingroup wpproxy
- *
+ * \param self the proxy
- * @param self: the proxy
+ * \returns a pointer to the underlying `pw_proxy` object
- * @returns a pointer to the underlying `pw_proxy` object
  */
-
 struct pw_proxy *
 wp_proxy_get_pw_proxy (WpProxy * self)
 {
@@ -317,13 +310,14 @@ wp_proxy_get_pw_proxy (WpProxy * self)
 }
 
 /*!
- * @memberof WpProxy
+ * \brief Private method to be used by subclasses to set the `pw_proxy` pointer
+ * when it is available.
  *
- * @brief Private method to be used by subclasses to set the `pw_proxy` pointer
+ * This can be called only if there is no `pw_proxy` already set.
- * when it is available. This can be called only if there is no `pw_proxy`
+ * Takes ownership of \a proxy.
- * already set. Takes ownership of @em proxy.
+ *
+ * \ingroup wpproxy
  */
-
 void
 wp_proxy_set_pw_proxy (WpProxy * self, struct pw_proxy * proxy)
 {
@@ -358,6 +352,17 @@ bind_success (WpProxy * proxy, uint32_t global_id, WpTransition * transition)
   g_signal_handlers_disconnect_by_func (proxy, bind_success, transition);
 }
 
+/*!
+ * \brief Private method to be used by subclasses to watch for errors
+ * during a \a transition that leads the proxy to become bound
+ *
+ * If an error is signaled on the proxy before the \c bound signal is emitted,
+ * the transition will return an error.
+ *
+ * \param proxy the proxy
+ * \param transition the transition that binds the proxy
+ * \ingroup wpproxy
+ */
 void
 wp_proxy_watch_bind_error (WpProxy * proxy, WpTransition * transition)
 {

lib/wp/proxy.h

@@ -16,12 +16,8 @@ G_BEGIN_DECLS
 struct pw_proxy;
 
 /*!
- * @memberof WpProxy
+ * \brief Flags to be used as WpObjectFeatures for WpProxy subclasses.
- *
+ * \ingroup wpproxy
- * @section proxy_features_section WpProxyFeatures
- *
- * @brief Flags to be used as [WpObjectFeatures](@ref object_features_section) for
- * [WpProxy](@ref proxy_section) subclasses.
  */
 typedef enum { /*< flags >*/
   /* standard features */
@@ -39,21 +35,17 @@ typedef enum { /*< flags >*/
 } WpProxyFeatures;
 
 /*!
- * @memberof WpProxy
+ * \brief The minimal feature set for proxies implementing WpPipewireObject.
- * WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL:
+ * This is a subset of \em WP_PIPEWIRE_OBJECT_FEATURES_ALL
- *
+ * \ingroup wpproxy
- * @brief The minimal feature set for proxies implementing [WpPipewireObject](@ref pipewire_object_section).
- * This is a subset of @em WP_PIPEWIRE_OBJECT_FEATURES_ALL
  */
 static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL =
     (WP_PROXY_FEATURE_BOUND | WP_PIPEWIRE_OBJECT_FEATURE_INFO);
 
 /*!
- * @memberof WpProxy
+ * \brief The complete common feature set for proxies implementing
- * WP_PIPEWIRE_OBJECT_FEATURES_ALL:
+ * WpPipewireObject. This is a subset of \em WP_OBJECT_FEATURES_ALL
- *
+ * \ingroup wpproxy
- * @brief The complete common feature set for proxies implementing [WpPipewireObject](@ref pipewire_object_section).
- * This is a subset of @em WP_OBJECT_FEATURES_ALL
  */
 static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_ALL =
     (WP_PIPEWIRE_OBJECT_FEATURES_MINIMAL |
@@ -64,33 +56,23 @@ static const WpObjectFeatures WP_PIPEWIRE_OBJECT_FEATURES_ALL =
      WP_PIPEWIRE_OBJECT_FEATURE_PARAM_ROUTE);
 
 /*!
- * @memberof WpProxy
+ * \brief The WpProxy GType
- *
+ * \ingroup wpproxy
- * @brief The [WpProxy](@ref proxy_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_PROXY (wp_proxy_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_PROXY (wp_proxy_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpProxy, wp_proxy, WP, PROXY, WpObject)
 
-/*!
- * @brief
- * @em pw_iface_type: the PipeWire type of the interface that is being proxied by
- *    this class (ex. `PW_TYPE_INTERFACE_Node` for [WpNode](@ref node_section))
- * @em pw_iface_version: the PipeWire version of the interface that is being
- *    proxied by this class
- */
 struct _WpProxyClass
 {
   WpObjectClass parent_class;
 
+  /*! \brief the PipeWire type of the interface that is being proxied by
+   *  this class (ex. `PW_TYPE_INTERFACE_Node` for WpNode */
   const gchar * pw_iface_type;
+
+  /*! \brief the PipeWire version of the interface that is being
+   *  proxied by this class */
   guint32 pw_iface_version;
 
   /* signals */

lib/wp/session-item.c

@@ -5,9 +5,7 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
+
- * @file session-item.c
- */
 #define G_LOG_DOMAIN "wp-si"
 
 #include "session-item.h"
@@ -15,6 +13,19 @@
 #include "error.h"
 #include "private/registry.h"
 
+/*! \defgroup wpsessionitem WpSessionItem */
+/*!
+ * \struct WpSessionItem
+ *
+ * \gproperties
+ *
+ * \gproperty{id, guint, G_PARAM_READABLE,
+ *   The session item unique id}
+ *
+ * \gproperty{properties, WpProperties *, G_PARAM_READABLE,
+ *   The session item properties}
+ */
+
 enum {
   STEP_ACTIVATE = WP_TRANSITION_STEP_CUSTOM_START,
   STEP_EXPORT,
@@ -27,38 +38,12 @@ struct _WpSessionItemPrivate
   WpProperties *properties;
 };
 
-/*!
- * @memberof WpSessionItem
- *
- * @props @b id
- *
- * @code
- * "id" guint
- * @endcode
- *
- * Flags : Read
- *
- * @props @b properties
- *
- * @code
- * "properties" WpProperties *
- * @endcode
- *
- * Flags : Read
- *
- */
 enum {
   PROP_0,
   PROP_ID,
   PROP_PROPERTIES,
 };
 
-/*!
- * @struct WpSessionItem
- * @section session_item_section Sessio Item
- *
- */
-
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpSessionItem, wp_session_item,
     WP_TYPE_OBJECT)
 
@@ -237,12 +222,10 @@ wp_session_item_class_init (WpSessionItemClass * klass)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Gets the unique Id of the session item
- * @param self: the session item
+ * \ingroup wpsessionitem
- *
+ * \param self the session item
- * @brief Gets the unique Id of the session item
  */
-
 guint
 wp_session_item_get_id (WpSessionItem * self)
 {
@@ -255,13 +238,13 @@ wp_session_item_get_id (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Resets the session item.
- * @param self: the session item
  *
- * @brief Resets the session item. This essentially removes the configuration and
+ * This essentially removes the configuration and deactivates all active features.
- * and deactivates all active features.
+ *
+ * \ingroup wpsessionitem
+ * \param self the session item
  */
-
 void
 wp_session_item_reset (WpSessionItem * self)
 {
@@ -272,13 +255,11 @@ wp_session_item_reset (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \ingroup wpsessionitem
- * @param self: the session item
+ * \param self the session item
- * @param props: (transfer full): the properties used to configure the item
+ * \param props (transfer full): the properties used to configure the item
- *
+ * \returns TRUE on success, FALSE if the item could not be configured
- * @returns %TRUE on success, %FALSE if the item could not be configured
  */
-
 gboolean
 wp_session_item_configure (WpSessionItem * self, WpProperties * props)
 {
@@ -290,12 +271,10 @@ wp_session_item_configure (WpSessionItem * self, WpProperties * props)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \ingroup wpsessionitem
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns TRUE if the item is configured, FALSE otherwise
- * @returns %TRUE if the item is configured, %FALSE otherwise
  */
-
 gboolean
 wp_session_item_is_configured (WpSessionItem * self)
 {
@@ -308,25 +287,21 @@ wp_session_item_is_configured (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief An associated proxy is a WpProxy subclass instance that
- * @param self: the session item
- * @param proxy_type: a [WpProxy](@ref proxy_section) subclass
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @brief An associated proxy is a [WpProxy](@ref proxy_section) subclass instance that
  * is somehow related to this item. For example:
- *  - An exported [WpSiEndpoint](@ref si_endpoint_section) should have at least:
+ *  - An exported WpSiEndpoint should have at least:
- *      - an associated [WpSiEndpoint](@ref si_endpoint_section)
+ *      - an associated WpSiEndpoint
- *      - an associated [WpSession](@ref session_section)
+ *      - an associated WpSession
  *  - In cases where the item wraps a single PipeWire node, it should also
- *    have an associated [WpNode](@ref node_section)
+ *    have an associated WpNode
  *
- * @returns (nullable) (transfer full) (type WpProxy): the associated proxy
+ * \ingroup wpsessionitem
- *   of the specified @em proxy_type, or %NULL if there is no association to
+ * \param self the session item
+ * \param proxy_type a WpProxy subclass GType
+ * \returns (nullable) (transfer full) (type WpProxy): the associated proxy
+ *   of the specified @em proxy_type, or NULL if there is no association to
  *   such a proxy
  */
-
 gpointer
 wp_session_item_get_associated_proxy (WpSessionItem * self, GType proxy_type)
 {
@@ -339,16 +314,12 @@ wp_session_item_get_associated_proxy (WpSessionItem * self, GType proxy_type)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \ingroup wpsessionitem
- * @param self: the session item
+ * \param self the session item
- * @param proxy_type: a [WpProxy](@ref proxy_section) subclass
+ * \param proxy_type a WpProxy subclass GType
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
+ * \returns the bound id of the associated proxy of the specified @em proxy_type,
- * GType</a>
- *
- * @returns the bound id of the associated proxy of the specified @em proxy_type,
  *   or `SPA_ID_INVALID` if there is no association to such a proxy
  */
-
 guint32
 wp_session_item_get_associated_proxy_id (WpSessionItem * self, GType proxy_type)
 {
@@ -361,12 +332,11 @@ wp_session_item_get_associated_proxy_id (WpSessionItem * self, GType proxy_type)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Registers the session item to its associated core
- * @param self: (transfer full): the session item
  *
- * @brief Registers the session item to its associated core
+ * \ingroup wpsessionitem
+ * \param self (transfer full): the session item
  */
-
 void
 wp_session_item_register (WpSessionItem * self)
 {
@@ -379,12 +349,11 @@ wp_session_item_register (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Removes the session item from the registry
- * @param self: (transfer none): the session item
  *
- * @brief Removes the session item from the registry
+ * \ingroup wpsessionitem
+ * \param self (transfer none): the session item
  */
-
 void
 wp_session_item_remove (WpSessionItem * self)
 {
@@ -397,12 +366,10 @@ wp_session_item_remove (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \ingroup wpsessionitem
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns (transfer full): the item's properties.
- * @returns (transfer full): the item's properties.
  */
-
 WpProperties *
 wp_session_item_get_properties (WpSessionItem * self)
 {
@@ -415,11 +382,10 @@ wp_session_item_get_properties (WpSessionItem * self)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \ingroup wpsessionitem
- * @param self: the session item
+ * \param self the session item
- * @param key: the property key
+ * \param key the property key
- *
+ * \returns the item property value for the given key.
- * @returns the item property value for the given key.
  */
 const gchar *
 wp_session_item_get_property (WpSessionItem * self, const gchar *key)
@@ -433,14 +399,14 @@ wp_session_item_get_property (WpSessionItem * self, const gchar *key)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Sets the item's properties.
- * @param self: the session item
- * @param props: (transfer full): the new properties to set
  *
- * @brief Sets the item's properties. This should only be done by sub-classes after
+ * This should only be done by sub-classes after the configuration has been done.
- * the configuration has been done.
+ *
+ * \ingroup wpsessionitem
+ * \param self the session item
+ * \param props (transfer full): the new properties to set
  */
-
 void
 wp_session_item_set_properties (WpSessionItem * self,
     WpProperties *props)
@@ -463,14 +429,15 @@ on_session_item_proxy_destroyed_deferred (WpSessionItem * item)
 }
 
 /*!
- * @memberof WpSessionItem
+ * \brief Helper callback for sub-classes that deffers and unexports
- * @param proxy: the proxy that was destroyed by the server
+ * the session item.
- * @param item: the associated session item
  *
- * @brief Helper callback for sub-classes that deffers and unexports the session item.
  * Only meant to be used when the pipewire proxy destroyed signal is triggered.
+ *
+ * \ingroup wpsessionitem
+ * \param proxy the proxy that was destroyed by the server
+ * \param item the associated session item
  */
-
 void
 wp_session_item_handle_proxy_destroyed (WpProxy * proxy, WpSessionItem * item)
 {

lib/wp/session-item.h

@@ -15,10 +15,8 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpSessionItem
+ * \brief Flags to be used as WpObjectFeatures for WpSessionItem subclasses.
- *
+ * \ingroup wpsessionitem
- * @brief Flags to be used as [WpObjectFeatures](@ref object_features_section) for
- * [WpSessionItem](@ref session_item_section) subclasses.
  */
 typedef enum { /*< flags >*/
   /* main features */
@@ -29,43 +27,32 @@ typedef enum { /*< flags >*/
 } WpSessionItemFeatures;
 
 /*!
- * @memberof WpSessionItem
+ * \brief The WpSessionItem GType
- *
+ * \ingroup wpsessionitem
- * @brief The [WpSessionItem](@ref session_item_section) 
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SESSION_ITEM (wp_session_item_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SESSION_ITEM (wp_session_item_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpSessionItem, wp_session_item,
                           WP, SESSION_ITEM, WpObject)
 
-/*!
- * @brief
- * @em reset: See wp_session_item_reset()
- * @em configure: See wp_session_item_configure()
- * @em get_associated_proxy: See wp_session_item_get_associated_proxy()
- * @em disable_active: disables the active feature of the session item
- * @em disable_exported: disables the exported feature of the session item
- * @em enable_active: enables the active feature of the session item
- * @em enable_exported: enables the exported feature of the session item
- */
 struct _WpSessionItemClass
 {
   WpObjectClass parent_class;
 
+  /*! See wp_session_item_reset() */
   void (*reset) (WpSessionItem * self);
+  /*! See wp_session_item_configure() */
   gboolean (*configure) (WpSessionItem * self, WpProperties * props);
+  /*! See wp_session_item_get_associated_proxy() */
   gpointer (*get_associated_proxy) (WpSessionItem * self, GType proxy_type);
 
+  /*! disables the active feature of the session item */
   void (*disable_active) (WpSessionItem * self);
+  /*! disables the exported feature of the session item */
   void (*disable_exported) (WpSessionItem * self);
+  /*! enables the active feature of the session item */
   void (*enable_active) (WpSessionItem * self, WpTransition * transition);
+  /*! enables the exported feature of the session item */
   void (*enable_exported) (WpSessionItem * self, WpTransition * transition);
 };
 

lib/wp/si-factory.c

@@ -6,26 +6,32 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file si-factory.c
- */
-
 #define G_LOG_DOMAIN "wp-si-factory"
 
 #include "si-factory.h"
 #include "private/registry.h"
 
+/*! \defgroup wpsifactory WpSiFactory */
 /*!
- * @memberof WpSiFactory
+ * \struct WpSiFactory
  *
- * @props @b name
+ * A factory for session items.
  *
- * @code
+ * The most simple way to register a new item implementation would be:
- * "name" gchar *
+ * \code
- * @endcode
+ * wp_si_factory_register (core,
+ *    wp_si_factory_new_simple ("foobar", FOO_TYPE_BAR));
+ * \endcode
  *
- * Flags : Read / Write / Construct Only
+ * And the most simple way to construct an item from a registered factory:
+ * \code
+ * item = wp_session_item_make (core, "foobar");
+ * \endcode
  *
+ * \gproperties
+ *
+ * \gproperty{name, gchar *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The factory's name}
  */
 enum {
   PROP_0,
@@ -38,27 +44,6 @@ struct _WpSiFactoryPrivate
   GQuark name_quark;
 };
 
-/*!
- * @struct WpSiFactory
- * @section si_factory_section Session Items Factory
- *
- * @brief A factory for session items.
- *
- * The most simple way to register a new item implementation would be:
- * |[
- * GVariantBuilder b = G_VARIANT_BUILDER_INIT ("a(ssymv)");
- * g_variant_builder_add (&b, ...);
- * wp_si_factory_register (core, wp_si_factory_new_simple (
- *    "foobar", FOO_TYPE_BAR, g_variant_builder_end (&b)));
- * ]|
- *
- * And the most simple way to construct an item from a registered factory:
- * |[
- * item = wp_session_item_make (core, "foobar");
- * ]|
- *
- */
-
 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (WpSiFactory, wp_si_factory, G_TYPE_OBJECT)
 
 static void
@@ -114,12 +99,10 @@ wp_si_factory_class_init (WpSiFactoryClass * klass)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \ingroup wpsifactory
- * @param self: the factory
+ * \param self the factory
- *
+ * \returns the factory name
- * @returns the factory name
  */
-
 const gchar *
 wp_si_factory_get_name (WpSiFactory * self)
 {
@@ -130,16 +113,14 @@ wp_si_factory_get_name (WpSiFactory * self)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \brief Creates a new instance of the session item that is constructed
- * @param self: the factory
- * @param core: the core
- *
- * @brief Creates a new instance of the session item that is constructed
  * by this factory
  *
- * @returns (transfer full): a new session item instance
+ * \ingroup wpsifactory
+ * \param self the factory
+ * \param core the core
+ * \returns (transfer full): a new session item instance
  */
-
 WpSessionItem *
 wp_si_factory_construct (WpSiFactory * self, WpCore * core)
 {
@@ -150,13 +131,12 @@ wp_si_factory_construct (WpSiFactory * self, WpCore * core)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \brief Registers the \a factory on the \a core.
- * @param core: the core
- * @param factory: (transfer full): the factory to register
  *
- * @brief Registers the @em factory on the @em core.
+ * \ingroup wpsifactory
+ * \param core the core
+ * \param factory (transfer full): the factory to register
  */
-
 void
 wp_si_factory_register (WpCore * core, WpSiFactory * factory)
 {
@@ -178,13 +158,11 @@ find_factory_func (gpointer factory, gpointer name_quark)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \ingroup wpsifactory
- * @param core: the core
+ * \param core the core
- * @param factory_name: the lookup name
+ * \param factory_name the lookup name
- *
+ * \returns (transfer full) (nullable): the factory matching the lookup name
- * @returns (transfer full) (nullable): the factory matching the lookup name
  */
-
 WpSiFactory *
 wp_si_factory_find (WpCore * core, const gchar * factory_name)
 {
@@ -199,16 +177,15 @@ wp_si_factory_find (WpCore * core, const gchar * factory_name)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \brief Finds the factory associated with the given \a name from the \a core
- * @param core: the [WpCore](@ref core_section)
+ * and uses it to construct a new WpSessionItem.
- * @param factory_name: the name of the factory to be used for constructing the object
  *
- * @brief Finds the factory associated with the given @em name from the @em core and
+ * \ingroup wpsifactory
- * uses it to construct a new [WpSessionItem](@ref session_item_section).
+ * \param core the WpCore
- *
+ * \param factory_name the name of the factory to be used for constructing
- * @returns (transfer full) (nullable): the new session item
+ *   the object
+ * \returns (transfer full) (nullable): the new session item
  */
-
 WpSessionItem *
 wp_session_item_make (WpCore * core, const gchar * factory_name)
 {
@@ -248,14 +225,12 @@ wp_simple_si_factory_class_init (WpSimpleSiFactoryClass * klass)
 }
 
 /*!
- * @memberof WpSiFactory
+ * \ingroup wpsifactory
- * @param factory_name: the factory name; must be a static string!
+ * \param factory_name the factory name; must be a static string!
- * @param si_type: the [WpSessionItem](@ref session_item_section) subclass type to instantiate for
+ * \param si_type the WpSessionItem subclass type to instantiate for
  *    constructing items
- *
+ * \returns (transfer full): the new factory
- * @returns (transfer full): the new factory
  */
-
 WpSiFactory *
 wp_si_factory_new_simple (const gchar * factory_name, GType si_type)
 {
@@ -273,4 +248,4 @@ wp_si_factory_new_simple (const gchar * factory_name, GType si_type)
   self->si_type = si_type;
 
   return WP_SI_FACTORY (self);
-}
+}

lib/wp/si-factory.h

@@ -15,27 +15,13 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpSiFactory
+ * \brief The WpSiFactory GType
- *
+ * \ingroup wpsifactory
- * @brief The [WpSiFactory](@ref si_factory_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_FACTORY (wp_si_factory_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SI_FACTORY (wp_si_factory_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpSiFactory, wp_si_factory, WP, SI_FACTORY, GObject)
 
-/*!
- * @memberof WpSiFactory
- *
- * @brief
- * @em parent_class
- */
 struct _WpSiFactoryClass
 {
   GObjectClass parent_class;

lib/wp/si-interfaces.c

@@ -5,86 +5,33 @@
  *
  * SPDX-License-Identifier: MIT
  */
-/*!
- * @file si-interfaces.c
- */
-
-/*!
- * @section si_interfaces_section Session Item Interfaces
- *
- * @struct WpSiAcquisition
- * @section si_acquisition_section WpSiAcquisition
- *
- * @brief This interface provides a way to request an item for linking before doing
- * so. This allows item implementations to apply internal policy rules.
- *
- * A [WpSiAcquisition](@ref si_acquisition_section) is associated directly
- * with a [WpSiLinkable](@ref si_linkable_section) via
- * wp_si_linkable_get_acquisition(). In order to allow switching
- * policies, it is recommended that port info implementations use a separate
- * session item to implement this interface and allow replacing it.
- *
- * @struct WpSiEndpoint
- * @section si_endpoint_section WpSiEndpoint
- *
- * @brief An interface for session items that implement a PipeWire endpoint.
- *
- * @section si_endpoint_signals_section Signals
- *
- * @b endpoint-properties-changed
- *
- * @code
- * endpoint_properties_changed_callback (WpSiEndpoint * self,
- *                                       gpointer user_data)
- * @endcode
- *
- * Parameters:
- *
- * @arg `self` - the session
- * @arg `user_data`
- *
- * Flags: Run Last
- *
- * @struct WpSiLink
- * @section si_link_section WpSiLink
- *
- * @brief An interface for session items that provide a PipeWire endpoint link.
- *
- * @section si_link_signals_section Signals
- *
- * @b link-properties-changed
- *
- * @code
- * link_properties_changed_callback (WpSiLink * self,
- *                                   gpointer user_data)
- * @endcode
- *
- * Parameters:
- *
- * @arg `self` - the session
- * @arg `user_data`
- *
- * Flags: Run Last
- *
- * WpSiLinkable:
- *
- * @struct WpSiLinkable
- * @section si_linkable_section WpSiLinkable
- *
- * @brief An interface for retrieving PipeWire port information from a session item.
- * This information is used to create links in the nodes graph.
- *
- * This is normally implemented by the same session items that implement
- * [WpSiEndpoint](@ref si_endpoint_section). The standard link implementation expects to be able to cast
- * a [WpSiEndpoint](@ref si_endpoint_section) into a [WpSiLinkable](@ref si_linkable_section).
- *
- */
 
 #define G_LOG_DOMAIN "wp-si-interfaces"
 
 #include "si-interfaces.h"
 #include "wpenums.h"
 
+/*! \defgroup wpsiinterfaces Session Item Interfaces */
+
+/*!
+ * \struct WpSiEndpoint
+ *
+ * An interface for session items that implement a PipeWire endpoint.
+ *
+ * \gsignals
+ *
+ * \par endpoint-properties-changed
+ * \parblock
+ * \code
+ * void
+ * endpoint_properties_changed_callback (WpSiEndpoint * self,
+ *                                       gpointer user_data)
+ * \endcode
+ * Emitted when the endpoint properties change
+ *
+ * Flags: G_SIGNAL_RUN_LAST
+ * \endparblock
+ */
 G_DEFINE_INTERFACE (WpSiEndpoint, wp_si_endpoint, WP_TYPE_SESSION_ITEM)
 
 static WpProperties *
@@ -103,19 +50,20 @@ wp_si_endpoint_default_init (WpSiEndpointInterface * iface)
 }
 
 /*!
- * @memberof WpSiEndpoint
+ * \brief This should return information that is used for registering the
- * @param self: the session item
+ * endpoint.
  *
- * @brief This should return information that is used for registering the endpoint,
+ * The return value should be a GVariant tuple of type (ssya{ss}) that contains,
- * as a GVariant tuple of type (ssya{ss}) that contains, in order:
+ * in order:
  *  - s: the endpoint's name
  *  - s: the media class
  *  - y: the direction
  *  - a{ss}: additional properties to be added to the list of global properties
  *
- * @returns (transfer full): registration info for the endpoint
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \returns (transfer full): registration info for the endpoint
  */
-
 GVariant *
 wp_si_endpoint_get_registration_info (WpSiEndpoint * self)
 {
@@ -126,12 +74,10 @@ wp_si_endpoint_get_registration_info (WpSiEndpoint * self)
 }
 
 /*!
- * @memberof WpSiEndpoint
+ * \ingroup wpsiinterfaces
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns (transfer full) (nullable): the properties of the endpoint
- * @returns (transfer full) (nullable): the properties of the endpoint
  */
-
 WpProperties *
 wp_si_endpoint_get_properties (WpSiEndpoint * self)
 {
@@ -141,6 +87,10 @@ wp_si_endpoint_get_properties (WpSiEndpoint * self)
   return WP_SI_ENDPOINT_GET_IFACE (self)->get_properties (self);
 }
 
+/*!
+ * \struct WpSiAdapter
+ * An interface for port adapters
+ */
 
 G_DEFINE_INTERFACE (WpSiAdapter, wp_si_adapter, WP_TYPE_SESSION_ITEM)
 
@@ -150,14 +100,13 @@ wp_si_adapter_default_init (WpSiAdapterInterface * iface)
 }
 
 /**
- * wp_si_adapter_get_ports_format: (virtual get_ports_format)
+ * \ingroup wpsiinterfaces
- * @self: the session item
+ * \param self the session item
- * @mode: (out) (nullable): the mode
+ * \param mode (out) (nullable): the mode
- *
+ * \returns (transfer full): The format used to configure the ports of the
- * Returns: (transfer full): The format used to configure the ports of the
+ *   adapter session item. Some items automatically choose a format when being
- * adapter session item. Some items automatically choose a format when being
+ *   activated, others never set a format on activation and the user needs to
- * activated, others never set a format on activation and the user needs to
+ *   manually set it externally with wp_si_adapter_set_ports_format().
- * manually set it externally with wp_si_adapter_set_ports_format().
  */
 WpSpaPod *
 wp_si_adapter_get_ports_format (WpSiAdapter * self, const gchar **mode)
@@ -168,19 +117,21 @@ wp_si_adapter_get_ports_format (WpSiAdapter * self, const gchar **mode)
   return WP_SI_ADAPTER_GET_IFACE (self)->get_ports_format (self, mode);
 }
 
-/**
+/*!
- * wp_si_adapter_set_ports_format: (virtual set_ports_format)
+ * \brief Sets the format and configures the adapter session item ports using
- * @self: the session item
+ * the given format.
- * @format: (transfer full) (nullable): the format to be set
- * @mode (nullable): the mode
- * @callback: (scope async): the callback to call when the operation is done
- * @data: (closure): user data for @callback
  *
- * Sets the format and configures the adapter session item ports using the
+ * The result of the operation can be checked using the
- * given format. The result of the operation can be checked using the
  * wp_si_adapter_set_ports_format_finish() API. If format is NULL, the adapter
  * will be configured with the default format. If mode is NULL, the adapter
  * will use "dsp" mode.
+ *
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \param format (transfer full) (nullable): the format to be set
+ * \param mode (nullable): the mode
+ * \param callback (scope async): the callback to call when the operation is done
+ * \param data (closure): user data for \a callback
  */
 void
 wp_si_adapter_set_ports_format (WpSiAdapter * self, WpSpaPod *format,
@@ -193,16 +144,15 @@ wp_si_adapter_set_ports_format (WpSiAdapter * self, WpSpaPod *format,
       callback, data);
 }
 
-/**
+/*!
- * wp_si_adapter_set_ports_format_finish: (virtual set_ports_format_finish)
+ * \brief Finishes the operation started by wp_si_adapter_set_format().
- * @self: the session item
- * @res: the async result
- * @error: (out) (optional): the operation's error, if it occurred
- *
- * Finishes the operation started by wp_si_adapter_set_format().
  * This is meant to be called in the callback that was passed to that method.
  *
- * Returns: %TRUE on success, %FALSE if there was an error
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \param res the async result
+ * \param error (out) (optional): the operation's error, if it occurred
+ * \returns TRUE on success, FALSE if there was an error
  */
 gboolean
 wp_si_adapter_set_ports_format_finish (WpSiAdapter * self, GAsyncResult * res,
@@ -216,6 +166,16 @@ wp_si_adapter_set_ports_format_finish (WpSiAdapter * self, GAsyncResult * res,
      error);
 }
 
+/*!
+ * \struct WpSiLinkable
+ *
+ * An interface for retrieving PipeWire port information from a session item.
+ * This information is used to create links in the nodes graph.
+ *
+ * This is normally implemented by the same session items that implement
+ * WpSiEndpoint. The standard link implementation expects to be able to cast
+ * a WpSiEndpoint into a WpSiLinkable.
+ */
 
 G_DEFINE_INTERFACE (WpSiLinkable, wp_si_linkable, WP_TYPE_SESSION_ITEM)
 
@@ -232,12 +192,8 @@ wp_si_linkable_default_init (WpSiLinkableInterface * iface)
 }
 
 /*!
- * @memberof WpSiLinkable
+ * \brief This method returns a variant of type "a(uuu)", where each tuple in
- * @param self: the session item
+ * the array contains the following information:
- * @param context: (nullable): an optional context for the ports
- *
- * @brief This method returns a variant of type "a(uuu)", where each tuple in the
- * array contains the following information:
  *   - u: (guint32) node id
  *   - u: (guint32) port id (the port must belong on the node specified above)
  *   - u: (guint32) the audio channel (enum spa_audio_channel) that this port
@@ -248,35 +204,33 @@ wp_si_linkable_default_init (WpSiLinkableInterface * iface)
  * in the order they appear. This is normally a good enough substitute for
  * channel matching.
  *
- * The @em context argument can be used to get different sets of ports from
+ * The \a context argument can be used to get different sets of ports from
  * the item. The following well-known contexts are defined:
- *   - %NULL: get the standard ports to be linked
+ *   - NULL: get the standard ports to be linked
  *   - "monitor": get the monitor ports
  *   - "control": get the control port
  *   - "reverse": get the reverse direction ports, if this item controls a
  *                filter node, which would have ports on both directions
  *
- * Contexts other than %NULL may only be used internally to ease the
+ * Contexts other than NULL may only be used internally to ease the
  * implementation of more complex item relationships. For example, a
- * [WpSessionItem](@ref session_item_section) that is in control of an
+ * WpSessionItem that is in control of an input (sink) adapter node may
- * input (sink) adapter node may implement [WpSiLinkable](@ref si_linkable_section)
+ * implement WpSiLinkable where the NULL context will return the standard
- * where the %NULL context will return the standard
  * input ports and the "monitor" context will return the adapter's monitor
- * ports. When linking this item to another item, the %NULL context
+ * ports. When linking this item to another item, the NULL context
  * will always be used, but the item may internally spawn a secondary
- * [WpSessionItem](@ref session_item_section) that implements the "monitor" item.
+ * WpSessionItem that implements the "monitor" item. That secondary item
- * That secondary item may implement [WpSiLinkable](@ref si_linkable_section),
+ * may implement WpSiLinkable, chaining calls to the WpSiLinkable
- * chaining calls to the [WpSiLinkable](@ref si_linkable_section)
  * of the original item using the "monitor" context. This way, the monitor
- * [WpSessionItem](@ref session_item_section) does not need to share control of the
+ * WpSessionItem does not need to share control of the
  * underlying node; it only proxies calls to satisfy the API.
  *
- * @returns (transfer full): a
+ * \ingroup wpsiinterfaces
- * <a href="https://developer.gnome.org/glib/stable/glib-GVariant.html#GVariant">
+ * \param self the session item
- * GVariant</a> containing information about the
+ * \param context (nullable): an optional context for the ports
+ * \returns (transfer full): a GVariant containing information about the
  *   ports of this item
  */
-
 GVariant *
 wp_si_linkable_get_ports (WpSiLinkable * self, const gchar * context)
 {
@@ -287,14 +241,13 @@ wp_si_linkable_get_ports (WpSiLinkable * self, const gchar * context)
 }
 
 /*!
- * @memberof WpSiLinkable
+ * \ingroup wpsiinterfaces
- * @param self: the session item
+ * \param self the session item
  *
- * @returns (transfer none) (nullable): the acquisition interface associated
+ * \returns (transfer none) (nullable): the acquisition interface associated
- *   with this item, or %NULL if this item does not require acquiring items
+ *   with this item, or NULL if this item does not require acquiring items
  *   before linking them
  */
-
 WpSiAcquisition *
 wp_si_linkable_get_acquisition (WpSiLinkable * self)
 {
@@ -305,6 +258,27 @@ wp_si_linkable_get_acquisition (WpSiLinkable * self)
   return WP_SI_LINKABLE_GET_IFACE (self)->get_acquisition (self);
 }
 
+
+/*!
+ * \struct WpSiLink
+ *
+ * An interface for session items that provide a PipeWire endpoint link.
+ *
+ * \gsignals
+ *
+ * \par link-properties-changed
+ * \parblock
+ * \code
+ * void
+ * link_properties_changed_callback (WpSiLink * self,
+ *                                   gpointer user_data)
+ * \endcode
+ * Emitted when the properties of the link change
+ *
+ * Flags: G_SIGNAL_RUN_LAST
+ * \endparblock
+ */
+
 G_DEFINE_INTERFACE (WpSiLink, wp_si_link, WP_TYPE_SESSION_ITEM)
 
 static WpProperties *
@@ -323,16 +297,14 @@ wp_si_link_default_init (WpSiLinkInterface * iface)
 }
 
 /*!
- * @memberof WpSiLink
+ * \brief This should return information that is used for registering the link,
- * @param self: the session item
- *
- * @brief This should return information that is used for registering the link,
  * as a GVariant of type a{ss} that contains additional properties to be
  * added to the list of global properties
  *
- * @returns (transfer full): registration info for the link
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \returns (transfer full): registration info for the link
  */
-
 GVariant *
 wp_si_link_get_registration_info (WpSiLink * self)
 {
@@ -343,12 +315,10 @@ wp_si_link_get_registration_info (WpSiLink * self)
 }
 
 /*!
- * @memberof WpSiLink
+ * \ingroup wpsiinterfaces
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns (transfer full) (nullable): the properties of the link
- * @returns (transfer full) (nullable): the properties of the link
  */
-
 WpProperties *
 wp_si_link_get_properties (WpSiLink * self)
 {
@@ -359,10 +329,9 @@ wp_si_link_get_properties (WpSiLink * self)
 }
 
 /*!
- * @memberof WpSiLink
+ * \ingroup wpsiinterfaces
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns (transfer none): the output item that is linked by this link
- * @returns (transfer none): the output item that is linked by this link
  */
 WpSiLinkable *
 wp_si_link_get_out_item (WpSiLink * self)
@@ -374,10 +343,9 @@ wp_si_link_get_out_item (WpSiLink * self)
 }
 
 /*!
- * @memberof WpSiLink
+ * \ingroup wpsiinterfaces
- * @param self: the session item
+ * \param self the session item
- *
+ * \returns (transfer none): the input item that is linked by this link
- * @returns (transfer none): the input item that is linked by this link
  */
 WpSiLinkable *
 wp_si_link_get_in_item (WpSiLink * self)
@@ -388,6 +356,18 @@ wp_si_link_get_in_item (WpSiLink * self)
   return WP_SI_LINK_GET_IFACE (self)->get_in_item (self);
 }
 
+/*!
+ * \struct WpSiAcquisition
+ *
+ * This interface provides a way to request an item for linking before doing
+ * so. This allows item implementations to apply internal policy rules.
+ *
+ * A WpSiAcquisition is associated directly with a WpSiLinkable via
+ * wp_si_linkable_get_acquisition(). In order to allow switching
+ * policies, it is recommended that port info implementations use a separate
+ * session item to implement this interface and allow replacing it.
+ */
+
 G_DEFINE_INTERFACE (WpSiAcquisition, wp_si_acquisition, WP_TYPE_SESSION_ITEM)
 
 static void
@@ -396,14 +376,7 @@ wp_si_acquisition_default_init (WpSiAcquisitionInterface * iface)
 }
 
 /*!
- * @memberof WpSiAcquisition
+ * \brief Acquires the \a item for linking by \a acquisitor.
- * @param self: the session item
- * @param acquisitor: the link that is trying to acquire a port info item
- * @param item: the item that is being acquired
- * @param callback: (scope async): the callback to call when the operation is done
- * @param data: (closure): user data for @em callback
- *
- * @brief Acquires the @em item for linking by @em acquisitor.
  *
  * When a link is not allowed by policy, this operation should return
  * an error.
@@ -412,8 +385,14 @@ wp_si_acquisition_default_init (WpSiAcquisitionInterface * iface)
  * a fade out effect on another item), this operation should finish with a
  * delay. It is safe to assume that after this operation completes,
  * the item will be linked immediately.
+ *
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \param acquisitor the link that is trying to acquire a port info item
+ * \param item the item that is being acquired
+ * \param callback (scope async): the callback to call when the operation is done
+ * \param data (closure): user data for \a callback
  */
-
 void
 wp_si_acquisition_acquire (WpSiAcquisition * self, WpSiLink * acquisitor,
     WpSiLinkable * item, GAsyncReadyCallback callback, gpointer data)
@@ -426,17 +405,15 @@ wp_si_acquisition_acquire (WpSiAcquisition * self, WpSiLink * acquisitor,
 }
 
 /*!
- * @memberof WpSiAcquisition
+ * \brief Finishes the operation started by wp_si_acquisition_acquire().
- * @param self: the session item
- * @param res: the async result
- * @param error: (out) (optional): the operation's error, if it occurred
- *
- * @brief Finishes the operation started by wp_si_acquisition_acquire().
  * This is meant to be called in the callback that was passed to that method.
  *
- * @returns %TRUE on success, %FALSE if there was an error
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \param res the async result
+ * \param error (out) (optional): the operation's error, if it occurred
+ * \returns TRUE on success, FALSE if there was an error
  */
-
 gboolean
 wp_si_acquisition_acquire_finish (WpSiAcquisition * self, GAsyncResult * res,
     GError ** error)
@@ -449,14 +426,13 @@ wp_si_acquisition_acquire_finish (WpSiAcquisition * self, GAsyncResult * res,
 }
 
 /*!
- * @memberof WpSiAcquisition
+ * \brief Releases the \a item, which means that it is being unlinked.
- * @param self: the session item
- * @param acquisitor: the link that had previously acquired the item
- * @param item: the port info that is being released
  *
- * @brief Releases the @em item, which means that it is being unlinked.
+ * \ingroup wpsiinterfaces
+ * \param self the session item
+ * \param acquisitor the link that had previously acquired the item
+ * \param item the port info that is being released
  */
-
 void
 wp_si_acquisition_release (WpSiAcquisition * self, WpSiLink * acquisitor,
     WpSiLinkable * item)

lib/wp/si-interfaces.h

@@ -18,28 +18,14 @@ G_BEGIN_DECLS
 typedef struct _WpSiAcquisition WpSiAcquisition;
 
 /*!
- * @memberof WpSiEndpoint
+ * \brief The WpSiEndpoint GType
- *
+ * \ingroup wpsiinterfaces
- * @brief The [WpSiEndpoint](@ref si_endpoint_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_ENDPOINT (wp_si_endpoint_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SI_ENDPOINT (wp_si_endpoint_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpSiEndpoint, wp_si_endpoint,
                      WP, SI_ENDPOINT, WpSessionItem)
 
-/*!
- * @memberof WpSiEndpoint
- *
- * @brief
- * @em interface
- */
 struct _WpSiEndpointInterface
 {
   GTypeInterface interface;
@@ -55,30 +41,14 @@ WP_API
 WpProperties * wp_si_endpoint_get_properties (WpSiEndpoint * self);
 
 /*!
- * @memberof WpSiAdapter
+ * \brief The WpSiAdapter GType
- *
+ * \ingroup wpsiinterfaces
- * WP_TYPE_SI_ADAPTER:
- *
- * The #WpSiAdapter #GType
- * @brief The [WpSiAdapter](@ref si_adapter_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_ADAPTER (wp_si_adapter_get_type ())
- * @endcode
  */
 #define WP_TYPE_SI_ADAPTER (wp_si_adapter_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpSiAdapter, wp_si_adapter,
                      WP, SI_ADAPTER, WpSessionItem)
 
-/*!
- * @memberof WpSiAdapter
- *
- * @brief
- * @em interface
- */
 struct _WpSiAdapterInterface
 {
   GTypeInterface interface;
@@ -103,30 +73,14 @@ gboolean wp_si_adapter_set_ports_format_finish (WpSiAdapter * self,
     GAsyncResult * res, GError ** error);
 
 /*!
- * @memberof WpSiLinkable
+ * \brief The WpSiLinkable GType
- *
+ * \ingroup wpsiinterfaces
- * WP_TYPE_SI_LINKABLE:
- *
- * The #WpSiLinkable #GType
- * @brief The [WpSiLinkable](@ref si_linkable_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_LINKABLE (wp_si_linkable_get_type ())
- * @endcode
  */
 #define WP_TYPE_SI_LINKABLE (wp_si_linkable_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpSiLinkable, wp_si_linkable,
                      WP, SI_LINKABLE, WpSessionItem)
 
-/*!
- * @memberof WpSiLinkable
- *
- * @brief
- * @em interface
- */
 struct _WpSiLinkableInterface
 {
   GTypeInterface interface;
@@ -143,30 +97,14 @@ WP_API
 WpSiAcquisition * wp_si_linkable_get_acquisition (WpSiLinkable * self);
 
 /*!
- * @memberof WpSiLink
+ * \brief The WpSiLink GType
- *
+ * \ingroup wpsiinterfaces
- * WP_TYPE_SI_LINK:
- *
- * @brief The [WpSiLink](@ref si_link_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_LINK (wp_si_link_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SI_LINK (wp_si_link_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpSiLink, wp_si_link,
                      WP, SI_LINK, WpSessionItem)
 
-/*!
- * @memberof WpSiLink
- *
- * @brief
- * @em interface
- */
 struct _WpSiLinkInterface
 {
   GTypeInterface interface;
@@ -191,30 +129,14 @@ WP_API
 WpSiLinkable * wp_si_link_get_in_item (WpSiLink * self);
 
 /*!
- * @memberof WpSiAcquisition
+ * \brief The WpSiAcquisition GType
- *
+ * \ingroup wpsiinterfaces
- * WP_TYPE_SI_ACQUISITION:
- *
- * The [WpSiAcquisition](@ref si_acquisition_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SI_ACQUISITION (wp_si_acquisition_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SI_ACQUISITION (wp_si_acquisition_get_type ())
 WP_API
 G_DECLARE_INTERFACE (WpSiAcquisition, wp_si_acquisition,
                      WP, SI_ACQUISITION, WpSessionItem)
 
-/*!
- * @memberof WpSiAcquisition
- *
- * @brief
- * @em interface
- */
 struct _WpSiAcquisitionInterface
 {
   GTypeInterface interface;

lib/wp/spa-pod.h

@@ -20,16 +20,8 @@ G_BEGIN_DECLS
 struct spa_pod;
 
 /*!
- * @memberof WpSpaPod
+ * \brief The WpSpaPod GType
- *
+ * \ingroup wpspapod
- * @brief The [WpSpaPod](@ref spa_pod_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SPA_POD (wp_spa_pod_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SPA_POD (wp_spa_pod_get_type ())
 WP_API
@@ -298,18 +290,8 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC (WpSpaPod, wp_spa_pod_unref)
 
 
 /*!
- * @memberof WpSpaPod
+ * \brief The WpSpaPodBuilder GType
- *
+ * \ingroup wpspapod
- * @section spa_pod_builder_section WP_TYPE_SPA_POD_BUILDER
- *
- * @brief The [WpSpaPodBuilder](@ref spa_pod_builder_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SPA_POD_BUILDER (wp_spa_pod_builder_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SPA_POD_BUILDER (wp_spa_pod_builder_get_type ())
 WP_API
@@ -408,18 +390,8 @@ G_DEFINE_AUTOPTR_CLEANUP_FUNC (WpSpaPodBuilder, wp_spa_pod_builder_unref)
 
 
 /*!
- * @memberof WpSpaPod
+ * \brief The WpSpaPodParser GType
- *
+ * \ingroup wpspapod
- * @section spa_pod_parser_section WP_TYPE_SPA_POD_PARSER
- *
- * @brief The [WpSpaPodBuilder](@ref spa_pod_parser_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_SPA_POD_PARSER (wp_spa_pod_parser_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_SPA_POD_PARSER (wp_spa_pod_parser_get_type ())
 WP_API

lib/wp/spa-type.c

@@ -6,13 +6,15 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
+#define G_LOG_DOMAIN "wp-spa-type"
- * @file spa-type
- */
 
-/*!
+#include "spa-type.h"
- * @struct WpSpaType
+
- * @section spa_type_section Spa Type Information
+#include <spa/utils/type-info.h>
+#include <spa/debug/types.h>
+#include <pipewire/pipewire.h>
+
+/*! \defgroup wpspatype WpSpaType
  *
  * Spa has a type system that is represented by a set of arrays that contain
  * `spa_type_info` structures. This type system is simple, yet complex to
@@ -23,21 +25,16 @@
  * API is that it makes it easy to work with string representations of the
  * types, allowing easier access from script bindings.
  *
- * @section spa_type_hierarchy_section Type hierarchy
+ * \b Type \b hierarchy
- *
- * @subsection spa_type_subsection WpSpaType
  *
  * On the top level, there is a list of types like Int, Bool, String, Id, Object.
- * These are called fundamental types (terms borrowed from 
+ * These are called fundamental types (terms borrowed from GType).
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>).
  * Fundamental types can be derived and therefore we can have other types
  * that represent specific objects, for instance.
  *
  * Enum and flag types are all represented with `SPA_TYPE_Id`. These types
  * may have a list of possible values that one can select from (enums)
- * or combine (flags). These values are accessed with the
+ * or combine (flags). These values are accessed with the WpSpaIdTable API.
- * [WpSpaIdTable](@ref spa_id_table_section) API.
  *
  * Object types can have fields. All objects always have a special "id" field,
  * which is an enum. Its possible values can be given by
@@ -45,20 +42,11 @@
  * other object-specific fields, which can be accessed with
  * wp_spa_type_get_values_table().
  *
- * Every object field or enum value is represented by a
+ * Every object field or enum value is represented by a WpSpaIdValue. In the
- * [WpSpaIdValue](@ref spa_id_value_section). In the
  * case of object fields, each field can be of a specific type, which is
  * returned by wp_spa_id_value_get_value_type().
  */
 
-#define G_LOG_DOMAIN "wp-spa-type"
-
-#include "spa-type.h"
-
-#include <spa/utils/type-info.h>
-#include <spa/debug/types.h>
-#include <pipewire/pipewire.h>
-
 static const WpSpaType SPA_TYPE_VENDOR_WirePlumber = 0x03000000;
 static GArray *extra_types = NULL;
 static GArray *extra_id_tables = NULL;
@@ -102,14 +90,8 @@ GType wp_spa_type_get_type (void)
   return id__volatile;
 }
 
-/*
- * WpSpaIdTable:
- */
 G_DEFINE_POINTER_TYPE (WpSpaIdTable, wp_spa_id_table)
 
-/*
- * WpSpaIdValue:
- */
 G_DEFINE_POINTER_TYPE (WpSpaIdValue, wp_spa_id_value)
 
 
@@ -166,15 +148,13 @@ wp_spa_type_info_find_by_name (const gchar *name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Looks up the type id from a given type name
- * @param name: the name to look up
  *
- * @brief Looks up the type id from a given type name
+ * \ingroup wpspatype
- *
+ * \param name the name to look up
- * @returns (transfer none): the corresponding type id or %WP_SPA_TYPE_INVALID
+ * \returns (transfer none): the corresponding type id or WP_SPA_TYPE_INVALID
  *   if not found
  */
-
 WpSpaType
 wp_spa_type_from_name (const gchar *name)
 {
@@ -183,14 +163,12 @@ wp_spa_type_from_name (const gchar *name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns (transfer none): the direct parent type of the given \a type; if the
- * @returns (transfer none): the direct parent type of the given @em type; if the
  *   type is fundamental (i.e. has no parent), the returned type is the same
- *   as @em type
+ *   as \a type
  */
-
 WpSpaType
 wp_spa_type_parent (WpSpaType type)
 {
@@ -199,12 +177,10 @@ wp_spa_type_parent (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns the complete name of the given \a type or NULL if \a type is invalid
- * @returns the complete name of the given @em type or %NULL if @em type is invalid
  */
-
 const gchar *
 wp_spa_type_name (WpSpaType type)
 {
@@ -213,12 +189,10 @@ wp_spa_type_name (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns TRUE if the \a type has no parent, FALSE otherwise
- * @returns %TRUE if the @em type has no parent, %FALSE otherwise
  */
-
 gboolean
 wp_spa_type_is_fundamental (WpSpaType type)
 {
@@ -227,12 +201,10 @@ wp_spa_type_is_fundamental (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns TRUE if the \a type is a SPA_TYPE_Id, FALSE otherwise
- * @returns %TRUE if the @em type is a SPA_TYPE_Id, %FALSE otherwise
  */
-
 gboolean
 wp_spa_type_is_id (WpSpaType type)
 {
@@ -241,12 +213,10 @@ wp_spa_type_is_id (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns TRUE if the \a type is a SPA_TYPE_Object, FALSE otherwise
- * @returns %TRUE if the @em type is a SPA_TYPE_Object, %FALSE otherwise
  */
-
 gboolean
 wp_spa_type_is_object (WpSpaType type)
 {
@@ -255,18 +225,19 @@ wp_spa_type_is_object (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Gets the table with the values that can be stored in the special "id"
- * @param type: the type id of an object type
+ *   field of an object of the given \a type
  *
- * @brief Object pods (see [WpSpaPod](@ref spa_pod_section)) always have a special "id" field along with
+ * Object pods (see WpSpaPod) always have a special "id" field along with
  * other fields that can be defined. This "id" field can only store values
  * of a specific `SPA_TYPE_Id` type. This function returns the table that
  * contains the possible values for that field.
  *
- * @returns the table with the values that can be stored in the special "id"
+ * \ingroup wpspatype
- *   field of an object of the given @em type
+ * \param type the type id of an object type
+ * \returns the table with the values that can be stored in the special "id"
+ *   field of an object of the given \a type
  */
-
 WpSpaIdTable
 wp_spa_type_get_object_id_values_table (WpSpaType type)
 {
@@ -282,13 +253,11 @@ wp_spa_type_get_object_id_values_table (WpSpaType type)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param type: a type id
+ * \param type a type id
- *
+ * \returns the associated WpSpaIdTable that contains possible
- * @returns the associated [WpSpaIdTable](@ref spa_id_table_section) that contains possible
+ *   values or object fields for this type, or NULL
- *   values or object fields for this type, or %NULL
  */
-
 WpSpaIdTable
 wp_spa_type_get_values_table (WpSpaType type)
 {
@@ -353,19 +322,17 @@ static const WpIteratorMethods spa_type_info_iterator_methods = {
 };
 
 /*!
- * @memberof WpSpaType
+ * \brief Finds a WpSpaIdTable given its name.
- * @param name: the full name of an id table
- *
- * @brief Finds a [WpSpaIdTable](@ref spa_id_table_section) given its name.
- * This name can either be the full type
- * name of an object type, or the name of an enum (which is not(!!) a type).
  *
+ * This name can either be the full type name of an object type,
+ * or the name of an enum (which is \b not(!!) a type).
  * For example, "Spa:Pod:Object:Param:Format" and "Spa:Enum:ParamId" are
  * both valid table names.
  *
- * @returns (nullable): the associated table, or %NULL
+ * \ingroup wpspatype
+ * \param name the full name of an id table
+ * \returns (nullable): the associated table, or NULL
  */
-
 WpSpaIdTable
 wp_spa_id_table_from_name (const gchar *name)
 {
@@ -396,17 +363,15 @@ wp_spa_id_table_from_name (const gchar *name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief This function returns an iterator that allows you to iterate
- * @param table: the id table
+ * through the values associated with this table.
  *
- * @brief This function returns an iterator that allows you to iterate through the
+ * The items in the iterator are of type WpSpaIdValue.
- * values associated with this table.
- * The items in the iterator are of type [WpSpaIdValue](@ref spa_id_value_section).
  *
- * @returns a [WpIterator](@ref iterator_section) that iterates over
+ * \ingroup wpspatype
- * [WpSpaIdValue](@ref spa_id_value_section) items
+ * \param table the id table
+ * \returns a WpIterator that iterates over WpSpaIdValue items
  */
-
 WpIterator *
 wp_spa_id_table_new_iterator (WpSpaIdTable table)
 {
@@ -421,14 +386,11 @@ wp_spa_id_table_new_iterator (WpSpaIdTable table)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param table: the id table
+ * \param table the id table
- * @param value: a numeric value that is contained in the table
+ * \param value a numeric value that is contained in the table
- *
+ * \returns (nullable): the WpSpaIdValue associated with \a value, or NULL
- * @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
- * associated with @em value, or %NULL
  */
-
 WpSpaIdValue
 wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
 {
@@ -444,14 +406,11 @@ wp_spa_id_table_find_value (WpSpaIdTable table, guint value)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param table: the id table
+ * \param table the id table
- * @param name: the full name of a value that is contained in the table
+ * \param name the full name of a value that is contained in the table
- *
+ * \returns (nullable): the WpSpaIdValue associated with \a name, or NULL
- * @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
- * associated with @em name, or %NULL
  */
-
 WpSpaIdValue
 wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
 {
@@ -467,14 +426,11 @@ wp_spa_id_table_find_value_from_name (WpSpaIdTable table, const gchar * name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param table: the id table
+ * \param table the id table
- * @param short_name: the short name of a value that is contained in the table
+ * \param short_name the short name of a value that is contained in the table
- *
+ * \returns (nullable): the WpSpaIdValue associated with \a short_name, or NULL
- * @returns (nullable): the [WpSpaIdValue](@ref spa_id_value_section)
- * associated with @em short_name, or %NULL
  */
-
 WpSpaIdValue
 wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
     const gchar * short_name)
@@ -514,16 +470,16 @@ wp_spa_id_name_find_id_table (const gchar * name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Looks up an id value (enum, flag or object field) directly from its
- * @param name: the full name of an id value
+ * full name.
  *
- * @brief Looks up an id value (enum, flag or object field) directly from its full
+ * For instance, "Spa:Enum:Direction:Input" will resolve to the
- * name. For instance, "Spa:Enum:Direction:Input" will resolve to the
  * id value that represents "Input" in the "Spa:Enum:Direction" enum.
  *
- * @returns the id value for @em name, or %NULL if no such id value was found
+ * \ingroup wpspatype
+ * \param name the full name of an id value
+ * \returns the id value for \a name, or NULL if no such id value was found
  */
-
 WpSpaIdValue
 wp_spa_id_value_from_name (const gchar * name)
 {
@@ -534,15 +490,14 @@ wp_spa_id_value_from_name (const gchar * name)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Looks up an id value given its container \a table_name and its
- * @param table_name: the name of the [WpSpaIdTable](@ref spa_id_table_section) to look up the value in
+ * \a short_name
- * @param short_name: the short name of the value to look up
  *
- * @brief Looks up an id value given its container @em table_name and its @em short_name
+ * \ingroup wpspatype
- *
+ * \param table_name the name of the WpSpaIdTable to look up the value in
- * @returns the id value or %NULL if it was not found
+ * \param short_name the short name of the value to look up
+ * \returns the id value or NULL if it was not found
  */
-
 WpSpaIdValue
 wp_spa_id_value_from_short_name (const gchar * table_name,
     const gchar * short_name)
@@ -555,16 +510,14 @@ wp_spa_id_value_from_short_name (const gchar * table_name,
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Looks up an id value given its container \a table_name and its numeric
- * @param table_name: the name of the [WpSpaIdTable](@ref spa_id_table_section) to look up the value in
+ * representation, \a id
- * @param id: the numeric representation of the value to look up
  *
- * @brief Looks up an id value given its container @em table_name and its numeric
+ * \ingroup wpspatype
- * representation, @em id
+ * \param table_name the name of the WpSpaIdTable to look up the value in
- *
+ * \param id the numeric representation of the value to look up
- * @returns the id value or %NULL if it was not found
+ * \returns the id value or NULL if it was not found
  */
-
 WpSpaIdValue
 wp_spa_id_value_from_number (const gchar * table_name, guint id)
 {
@@ -575,12 +528,10 @@ wp_spa_id_value_from_number (const gchar * table_name, guint id)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param id: an id value
+ * \param id an id value
- *
+ * \returns the numeric representation of this id value
- * @returns the numeric representation of this id value
  */
-
 guint
 wp_spa_id_value_number (WpSpaIdValue id)
 {
@@ -591,12 +542,10 @@ wp_spa_id_value_number (WpSpaIdValue id)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param id: an id value
+ * \param id an id value
- *
+ * \returns the full name of this id value
- * @returns the full name of this id value
  */
-
 const gchar *
 wp_spa_id_value_name (WpSpaIdValue id)
 {
@@ -607,12 +556,10 @@ wp_spa_id_value_name (WpSpaIdValue id)
 }
 
 /*!
- * @memberof WpSpaType
+ * \ingroup wpspatype
- * @param id: an id value
+ * \param id an id value
- *
+ * \returns the short name of this id value
- * @returns the short name of this id value
  */
-
 const gchar *
 wp_spa_id_value_short_name (WpSpaIdValue id)
 {
@@ -623,21 +570,20 @@ wp_spa_id_value_short_name (WpSpaIdValue id)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Returns the value type associated with this WpSpaIdValue.
- * @param id: an id value
- * @param table: (out) (optional): the associated [WpSpaIdTable](@ref spa_id_table_section)
  *
- * @brief Returns the value type associated with this [WpSpaIdValue](@ref spa_id_value_section).
+ * This information is useful when \a id represents an object field,
- * This information is useful when @em id represents an object field, which can take a value
+ * which can take a value of an arbitrary type.
- * of an arbitrary type.
  *
  * When the returned type is (or is derived from) `SPA_TYPE_Id` or
- * `SPA_TYPE_Object`, @em table is set to point to the [WpSpaIdTable](@ref spa_id_table_section)
+ * `SPA_TYPE_Object`, \a table is set to point to the WpSpaIdTable
  * that contains the possible Id values / object fields.
  *
- * @returns (transfer none): the value type associated with @em id
+ * \ingroup wpspatype
+ * \param id an id value
+ * \param table (out) (optional): the associated WpSpaIdTable
+ * \returns (transfer none): the value type associated with \a id
  */
-
 WpSpaType
 wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
 {
@@ -662,21 +608,19 @@ wp_spa_id_value_get_value_type (WpSpaIdValue id, WpSpaIdTable * table)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief If the value type of \a id is `SPA_TYPE_Array`, this function
- * @param id: an id value
+ * returns the type that is allowed to be contained inside the array.
- * @param table: (out) (optional): the associated [WpSpaIdTable](@ref spa_id_table_section)
- *
- * @brief If the value type of @em id is `SPA_TYPE_Array`, this function returns the
- * type that is allowed to be contained inside the array.
  *
  * When the returned type is (or is derived from) `SPA_TYPE_Id` or
- * `SPA_TYPE_Object`, @em table is set to point to the [WpSpaIdTable](@ref spa_id_table_section)
+ * `SPA_TYPE_Object`, \a table is set to point to the WpSpaIdTable
  * that contains the possible Id values / object fields.
  *
- * @returns (transfer none): the type that is allowed in the array, if @em id
+ * \ingroup wpspatype
+ * \param id an id value
+ * \param table (out) (optional): the associated WpSpaIdTable
+ * \returns (transfer none): the type that is allowed in the array, if \a id
  *   represents an object field that takes an array as value
  */
-
 WpSpaType
 wp_spa_id_value_array_get_item_type (WpSpaIdValue id, WpSpaIdTable * table)
 {
@@ -691,14 +635,15 @@ wp_spa_id_value_array_get_item_type (WpSpaIdValue id, WpSpaIdTable * table)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Initializes the spa dynamic type registry.
- * @brief Initializes the spa dynamic type registry.
+ *
  * This allows registering new spa types at runtime. The spa type system
  * still works if this function is not called.
  *
- * Normally called by wp_init() when %WP_INIT_SPA_TYPES is passed in its flags.
+ * Normally called by wp_init() when WP_INIT_SPA_TYPES is passed in its flags.
+ *
+ * \ingroup wpspatype
  */
-
 void
 wp_spa_dynamic_type_init (void)
 {
@@ -713,14 +658,14 @@ wp_spa_dynamic_type_init (void)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Deinitializes the spa type registry.
  *
- * @brief Deinitializes the spa type registry.
  * You do not need to ever call this, unless you want to free memory at the
  * end of the execution of a test, so that it doesn't show as leaked in
  * the memory profiler.
+ *
+ * \ingroup wpspatype
  */
-
 void
 wp_spa_dynamic_type_deinit (void)
 {
@@ -729,22 +674,21 @@ wp_spa_dynamic_type_deinit (void)
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Registers an additional type in the spa type system.
- * @param name: the name of the type
- * @param parent: the parent type
- * @param values: an array of `spa_type_info` that contains the values of the type,
- *   used only for Object types
  *
- * @brief Registers an additional type in the spa type system.
  * This is useful to add a custom pod object type.
  *
- * Note that both @em name and @em values must be statically allocated, or
+ * Note that both \a name and \a values must be statically allocated, or
  * otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit()
  * is called. No memory copy is done by this function.
  *
- * @returns (transfer none): the new type
+ * \ingroup wpspatype
+ * \param name the name of the type
+ * \param parent the parent type
+ * \param values an array of `spa_type_info` that contains the values of the type,
+ *   used only for Object types
+ * \returns (transfer none): the new type
  */
-
 WpSpaType
 wp_spa_dynamic_type_register (const gchar *name, WpSpaType parent,
     const struct spa_type_info * values)
@@ -759,20 +703,19 @@ wp_spa_dynamic_type_register (const gchar *name, WpSpaType parent,
 }
 
 /*!
- * @memberof WpSpaType
+ * \brief Registers an additional WpSpaIdTable in the spa type system.
- * @param name: the name of the id table
- * @param values: an array of `spa_type_info` that contains the values of the table
  *
- * @brief Registers an additional [WpSpaIdTable](@ref spa_id_table_section) in the spa type system.
  * This is useful to add custom enumeration types.
  *
- * Note that both @em name and @em values must be statically allocated, or
+ * Note that both \a name and \a values must be statically allocated, or
  * otherwise guaranteed to be kept in memory until wp_spa_dynamic_type_deinit()
  * is called. No memory copy is done by this function.
  *
- * @returns the new table
+ * \ingroup wpspatype
+ * \param name the name of the id table
+ * \param values an array of `spa_type_info` that contains the values of the table
+ * \returns the new table
  */
-
 WpSpaIdTable
 wp_spa_dynamic_id_table_register (const gchar *name,
     const struct spa_type_info * values)
@@ -782,4 +725,4 @@ wp_spa_dynamic_id_table_register (const gchar *name,
   info.values = values;
   g_array_append_val (extra_id_tables, info);
   return values;
-}
+}

lib/wp/spa-type.h

@@ -14,18 +14,25 @@
 
 G_BEGIN_DECLS
 
+/*!
+ * \ingroup wpspatype
+ */
 typedef guint32 WpSpaType;
+/*!
+ * \ingroup wpspatype
+ */
 typedef gconstpointer WpSpaIdTable;
+/*!
+ * \ingroup wpspatype
+ */
 typedef gconstpointer WpSpaIdValue;
 struct spa_type_info;
 
 /* WpSpaType */
+
 /*!
- * @memberof WpSpaType
+ * \brief The WpSpaType GType
- *
+ * \ingroup wpspatype
- * @code
- * #define WP_TYPE_SPA_TYPE (wp_spa_type_get_type ())
- * @endcode
  */
 #define WP_TYPE_SPA_TYPE (wp_spa_type_get_type ())
 WP_API
@@ -58,11 +65,8 @@ WP_API
 WpSpaIdTable wp_spa_type_get_values_table (WpSpaType type);
 
 /*!
- * @memberof WpSpaType
+ * \brief The WpSpaIdTable GType
- *
+ * \ingroup wpspatype
- * @code
- * #define WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ())
- * @endcode
  */
 #define WP_TYPE_SPA_ID_TABLE (wp_spa_id_table_get_type ())
 WP_API
@@ -86,11 +90,8 @@ WpSpaIdValue wp_spa_id_table_find_value_from_short_name (WpSpaIdTable table,
     const gchar * short_name);
 
 /*!
- * @memberof WpSpaType
+ * \brief The WpSpaIdValue GType
- *
+ * \ingroup wpspatype
- * @code
- * #define WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ())
- * @endcode
  */
 #define WP_TYPE_SPA_ID_VALUE (wp_spa_id_value_get_type ())
 WP_API

lib/wp/state.c

@@ -6,18 +6,6 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file state.c
- */
-
-/*!
- * @struct WpState
- * @section state_section State Storage
- *
- * The [WpState](@ref state_section) class saves and loads properties from a file
- *
- */
-
 #define G_LOG_DOMAIN "wp-state"
 
 #define WP_STATE_DIR_NAME "wireplumber"
@@ -31,32 +19,22 @@
 #include "log.h"
 #include "state.h"
 
+/*! \defgroup wpstate WpState */
 /*!
- * @memberof WpState
+ * \struct WpState
  *
- * @props @b name
+ * The WpState class saves and loads properties from a file
- *
- * @code
- * "name" gchar *
- * @endcode
- *
- * @brief The file name where the state will be stored.
- *
- * Flags : Read / Write / Construct Only
  *
+ * \gproperties
+ * \gproperty{name, gchar *, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY,
+ *   The file name where the state will be stored.}
  */
+
 enum {
   PROP_0,
   PROP_NAME,
 };
 
-/*!
- * @brief
- * @em parent
- * @em name
- * @em location
- * @em keyfile
- */
 struct _WpState
 {
   GObject parent;
@@ -161,10 +139,6 @@ wp_state_class_init (WpStateClass * klass)
   object_class->set_property = wp_state_set_property;
   object_class->get_property = wp_state_get_property;
 
-  /*
-   * WpState:name:
-   * The file name where the state will be stored.
-   */
   g_object_class_install_property (object_class, PROP_NAME,
       g_param_spec_string ("name", "name",
           "The file name where the state will be stored", NULL,
@@ -172,12 +146,10 @@ wp_state_class_init (WpStateClass * klass)
 }
 
 /*!
- * @memberof WpState
+ * \ingroup wpstate
- * @param name: the state name
+ * \param name the state name
- *
+ * \returns (transfer full): the new WpState
- * @returns (transfer full): the new [WpState](@ref state_section)
  */
-
 WpState *
 wp_state_new (const gchar *name)
 {
@@ -188,12 +160,10 @@ wp_state_new (const gchar *name)
 }
 
 /*!
- * @memberof WpState
+ * \ingroup wpstate
- * @param self: the state
+ * \param self the state
- *
+ * \returns the name of this state
- * @returns the name of this state
  */
-
 const gchar *
 wp_state_get_name (WpState *self)
 {
@@ -203,12 +173,10 @@ wp_state_get_name (WpState *self)
 }
 
 /*!
- * @memberof WpState
+ * \ingroup wpstate
- * @param self: the state
+ * \param self the state
- *
+ * \returns the location of this state
- * @returns the location of this state
  */
-
 const gchar *
 wp_state_get_location (WpState *self)
 {
@@ -219,12 +187,10 @@ wp_state_get_location (WpState *self)
 }
 
 /*!
- * @memberof WpState
+ * \brief Clears the state removing its file
- * @param self: the state
+ * \ingroup wpstate
- *
+ * \param self the state
- * Clears the state removing its file
  */
-
 void
 wp_state_clear (WpState *self)
 {
@@ -236,16 +202,13 @@ wp_state_clear (WpState *self)
 }
 
 /*!
- * @memberof WpState
+ * \brief Saves new properties in the state, overwriting all previous data.
- * @param self: the state
+ * \ingroup wpstate
- * @param group: the group name where the properties will be save
+ * \param self the state
- * @param props: (transfer none): the properties to save
+ * \param group the group name where the properties will be save
- *
+ * \param props (transfer none): the properties to save
- * @brief Saves new properties in the state, overwriting all previous data.
+ * \returns TRUE if the properties could be saved, FALSE otherwise
- *
- * @returns TRUE if the properties could be saved, FALSE otherwise
  */
-
 gboolean
 wp_state_save (WpState *self, const gchar *group, WpProperties *props)
 {
@@ -278,15 +241,12 @@ wp_state_save (WpState *self, const gchar *group, WpProperties *props)
 }
 
 /*!
- * @memberof WpState
+ * \brief Loads the state data into new properties.
- * @param self: the state
+ * \ingroup wpstate
- * @param group: the group which the properties will be loaded from
+ * \param self the state
- *
+ * \param group the group which the properties will be loaded from
- * @brief Loads the state data into new properties.
+ * \returns (transfer full): the new properties with the state data
- *
- * @returns (transfer full): the new properties with the state data
  */
-
 WpProperties *
 wp_state_load (WpState *self, const gchar *group)
 {
@@ -319,4 +279,4 @@ wp_state_load (WpState *self, const gchar *group)
   g_strfreev (keys);
 
   return g_steal_pointer (&props);
-}
+}

lib/wp/state.h

@@ -16,16 +16,8 @@ G_BEGIN_DECLS
 /* WpState */
 
 /*!
- * @memberof WpState
+ * \brief The WpState GType
- *
+ * \ingroup wpstate
- * @brief The [WpState](@ref state_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_STATE (wp_state_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_STATE (wp_state_get_type ())
 WP_API

lib/wp/transition.c

@@ -6,44 +6,49 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file transition.c
- */
-
-/*!
- * @struct WpTransition
- * @section transition_section Transitions
- *
- * A transition is an asynchronous operation, like
- * <a href="https://developer.gnome.org/gio/stable/GTask.html">
- * GTask</a>, that contains an internal state machine,
- * where a series of 'steps' are executed in order to complete the operation.
- *
- * For every step, [WpTransitionClass](@ref transition_class_section).get_next_step()
- * is called in order to determine the next step to execute. Afterwards,
- * [WpTransitionClass](@ref transition_class_section).execute_step() is called
- * to perform any actions necessary to complete this step. When execution
- * of the step is done, the operation's code must call wp_transition_advance()
- * in order to continue to the next step. If an error occurs, the operation's
- * code must call wp_transition_return_error() instead, in which case the
- * transition completes immediately and wp_transition_had_error() returns %TRUE.
- *
- * Typically, every step will start an asynchronous operation. Although is is
- * possible, the [WpTransition](@ref transition_section) base class does not expect
- * [WpTransitionClass](@ref transition_class_section).execute_step()
- * to call wp_transition_advance() directly.
- * Instead, it is expected that wp_transition_advance() will be called from
- * the callback that the step's asyncrhonous operation will call when it is
- * completed.
- *
- */
-
 #define G_LOG_DOMAIN "wp-transition"
 
 #include "transition.h"
 #include "log.h"
 #include "error.h"
 
+/*! \defgroup wptransition Transitions */
+/*!
+ * \struct WpTransition
+ *
+ * A transition is an asynchronous operation, like GTask, that contains an
+ * internal state machine, where a series of 'steps' are executed in order to
+ * complete the operation.
+ *
+ * For every step, _WpTransitionClass::get_next_step()
+ * is called in order to determine the next step to execute. Afterwards,
+ * _WpTransitionClass::execute_step() is called
+ * to perform any actions necessary to complete this step. When execution
+ * of the step is done, the operation's code must call wp_transition_advance()
+ * in order to continue to the next step. If an error occurs, the operation's
+ * code must call wp_transition_return_error() instead, in which case the
+ * transition completes immediately and wp_transition_had_error() returns TRUE.
+ *
+ * Typically, every step will start an asynchronous operation. Although is is
+ * possible, the WpTransition base class does not expect
+ * _WpTransitionClass::execute_step() to call wp_transition_advance() directly.
+ * Instead, it is expected that wp_transition_advance() will be called from
+ * the callback that the step's asyncrhonous operation will call when it is
+ * completed.
+ *
+ * \gproperties
+
+ * \gproperty{completed, gboolean, G_PARAM_READABLE,
+ *   Whether the transition has completed\, meaning its callback (if set)
+ *   has been invoked. This can only happen after the final step has been
+ *   reached or wp_transition_return_error() has been called.
+ *   \n
+ *   This property is guaranteed to change from FALSE to TRUE exactly once.
+ *   \n
+ *   The GObject \c notify signal for this change is emitted in the same context
+ *   as the transition’s callback\, immediately after that callback is invoked.}
+ */
+
 typedef struct _WpTransitionPrivate WpTransitionPrivate;
 struct _WpTransitionPrivate
 {
@@ -64,18 +69,6 @@ struct _WpTransitionPrivate
   GError *error;
 };
 
-/*!
- * @memberof WpTransition
- *
- * @props @b completed
- *
- * @code
- * "completed" gboolean
- * @endcode
- *
- * Flags : Read
- *
- */
 enum {
   PROP_0,
   PROP_COMPLETED,
@@ -133,18 +126,6 @@ wp_transition_class_init (WpTransitionClass * klass)
   object_class->finalize = wp_transition_finalize;
   object_class->get_property = wp_transition_get_property;
 
-  /*
-   * WpTransition::completed:
-   *
-   * @brief Whether the transition has completed, meaning its callback (if set)
-   * has been invoked. This can only happen after the final step has been
-   * reached or wp_transition_return_error() has been called.
-   *
-   * This property is guaranteed to change from %FALSE to %TRUE exactly once.
-   *
-   * The “notify” signal for this change is emitted in the same context
-   * as the transition’s callback, immediately after that callback is invoked.
-   */
   g_object_class_install_property (object_class, PROP_COMPLETED,
       g_param_spec_boolean ("completed", "completed",
           "Whether the transition has completed", FALSE,
@@ -170,36 +151,26 @@ wp_transition_async_result_init (GAsyncResultIface * iface)
 }
 
 /*!
+ * \brief Creates a WpTransition acting on \a source_object.
  *
- * @memberof WpTransition
+ * When the transition is done, \a callback will be invoked.
- *
- * @param type: the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a> of the [WpTransition](@ref transition_section) subclass to instantiate
- * @param source_object: (nullable) (type GObject): the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
- * GObject</a> that owns this task, or %NULL
- * @param cancellable: (nullable): optional
- * <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
- * GCancellable</a>
- * @param callback: (scope async): a
- * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
- * GAsyncReadyCallback</a>
- * @param callback_data: (closure): user data passed to @em callback
- *
- * @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object. When the transition is
- * done, @em callback will be invoked.
  *
  * The transition does not automatically start executing steps. You must
  * call wp_transition_advance() after creating it in order to start it.
  *
- * Note that the transition is automatically unref'ed after the @em callback
+ * \note The transition is automatically unref'ed after the \a callback
  * has been executed. If you wish to keep an additional reference on it,
  * you need to ref it explicitly.
  *
- * @returns (transfer none): the new transition
+ * \ingroup wptransition
+ * \param type the GType of the WpTransition subclass to instantiate
+ * \param source_object (nullable) (type GObject): the GObject that owns this
+ *   task, or NULL
+ * \param cancellable (nullable): optional GCancellable
+ * \param callback (scope async): a GAsyncReadyCallback
+ * \param callback_data (closure): user data passed to \a callback
+ * \returns (transfer none): the new transition
  */
-
 WpTransition *
 wp_transition_new (GType type,
     gpointer source_object, GCancellable * cancellable,
@@ -210,36 +181,24 @@ wp_transition_new (GType type,
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Creates a WpTransition acting on \a source_object.
- * @param type: the
+ * When the transition is done, \a closure will be invoked.
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- * of the [WpTransition](@ref transition_section) subclass to instantiate
- * @param source_object: (nullable) (type GObject): the
- * <a href="https://developer.gnome.org/gobject/stable/gobject-The-Base-Object-Type.html#GObject">
- * GObject</a> that owns this task, or %NULL
- * @param cancellable: (nullable): optional
- * <a href="https://developer.gnome.org/gio/stable/GCancellable.html">
- * GCancellable</a>
- * @param closure: (nullable): a
- * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
- * GAsyncReadyCallback</a> wrapped in a
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Closures.html#GClosure">
- * GClosure</a>
- *
- * @brief Creates a [WpTransition](@ref transition_section) acting on @em source_object.
- * When the transition is done, @em closure will be invoked.
  *
  * The transition does not automatically start executing steps. You must
  * call wp_transition_advance() after creating it in order to start it.
  *
- * Note that the transition is automatically unref'ed after the @em closure
+ * Note that the transition is automatically unref'ed after the \a closure
  * has been executed. If you wish to keep an additional reference on it,
  * you need to ref it explicitly.
  *
- * @returns (transfer none): the new transition
+ * \ingroup wptransition
+ * \param type the GType of the WpTransition subclass to instantiate
+ * \param source_object (nullable) (type GObject): the GObject that owns this
+ *   task, or NULL
+ * \param cancellable (nullable): optional GCancellable
+ * \param closure (nullable): a GAsyncReadyCallback wrapped in a GClosure
+ * \returns (transfer none): the new transition
  */
-
 WpTransition *
 wp_transition_new_closure (GType type, gpointer source_object,
     GCancellable * cancellable, GClosure * closure)
@@ -264,15 +223,14 @@ wp_transition_new_closure (GType type, gpointer source_object,
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Gets the source object from the transition.
- * @param self: the transition
  *
- * @brief Gets the source object from the transition.
  * Like g_async_result_get_source_object(), but does not ref the object.
  *
- * @returns (transfer none) (type GObject): the source object
+ * \ingroup wptransition
+ * \param self the transition
+ * \returns (transfer none) (type GObject): the source object
  */
-
 gpointer
 wp_transition_get_source_object (WpTransition * self)
 {
@@ -283,16 +241,14 @@ wp_transition_get_source_object (WpTransition * self)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Checks if \a self has the given \a tag (generally a function pointer
- * @param self: the transition
+ * indicating the function \a self was created by).
- * @param tag: a tag
  *
- * @brief Checks if @em self has the given @em tag (generally a function pointer
+ * \ingroup wptransition
- * indicating the function @em self was created by).
+ * \param self the transition
- *
+ * \param tag a tag
- * @returns TRUE if @em self has the indicated @em tag , FALSE if not.
+ * \returns TRUE if \a self has the indicated \a tag , FALSE if not.
  */
-
 gboolean
 wp_transition_is_tagged (WpTransition * self, gpointer tag)
 {
@@ -303,14 +259,12 @@ wp_transition_is_tagged (WpTransition * self, gpointer tag)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Gets \a self 's source tag.
- * @param self: the transition
+ * \see wp_transition_set_source_tag().
- *
+ * \ingroup wptransition
- * @brief Gets @em self 's source tag. See wp_transition_set_source_tag().
+ * \param self the transition
- *
+ * \returns (transfer none): the transition's source tag
- * @returns (transfer none): the transition's source tag
  */
-
 gpointer
 wp_transition_get_source_tag (WpTransition * self)
 {
@@ -321,17 +275,18 @@ wp_transition_get_source_tag (WpTransition * self)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Sets \a self 's source tag.
- * @param self: the transition
- * @param tag: an opaque pointer indicating the source of this transition
  *
- * @brief Sets @em self 's source tag. You can use this to tag a transition's return
+ * You can use this to tag a transition's return
  * value with a particular pointer (usually a pointer to the function doing
  * the tagging) and then later check it using wp_transition_get_source_tag()
  * (or g_async_result_is_tagged()) in the transition's "finish" function,
  * to figure out if the response came from a particular place.
- */
 
+ * \ingroup wptransition
+ * \param self the transition
+ * \param tag an opaque pointer indicating the source of this transition
+ */
 void
 wp_transition_set_source_tag (WpTransition * self, gpointer tag)
 {
@@ -342,14 +297,12 @@ wp_transition_set_source_tag (WpTransition * self, gpointer tag)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Gets \a self 's data.
- * @param self: the transition
+ * \see wp_transition_set_data().
- *
+ * \ingroup wptransition
- * @brief Gets @em self 's data. See wp_transition_set_data().
+ * \param self the transition
- *
+ * \returns (transfer none): the transition's data
- * @returns (transfer none): the transition's data
  */
-
 gpointer
 wp_transition_get_data (WpTransition * self)
 {
@@ -360,18 +313,14 @@ wp_transition_get_data (WpTransition * self)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Sets \a self 's data (freeing the existing data, if any). This can be an
- * @param self: the transition
- * @param data: (nullable): transition-specific user data
- * @param data_destroy: (nullable):
- * <a href="https://developer.gnome.org/glib/stable/glib-Datasets.html#GDestroyNotify">
- * GDestroyNotify</a>
- * for @em data
- *
- * @brief Sets @em self 's data (freeing the existing data, if any). This can be an
  * arbitrary user structure that holds data associated with this transition.
+ *
+ * \ingroup wptransition
+ * \param self the transition
+ * \param data (nullable): transition-specific user data
+ * \param data_destroy (nullable): GDestroyNotify for \a data
  */
-
 void
 wp_transition_set_data (WpTransition * self, gpointer data,
     GDestroyNotify data_destroy)
@@ -386,13 +335,11 @@ wp_transition_set_data (WpTransition * self, gpointer data,
 }
 
 /*!
- * @memberof WpTransition
+ * \ingroup wptransition
- * @param self: the transition
+ * \param self the transition
- *
+ * \returns TRUE if the transition has completed (with or without an error),
- * @returns %TRUE if the transition has completed (with or without an error),
+ *   FALSE otherwise
- *   %FALSE otherwise
  */
-
 gboolean
 wp_transition_get_completed (WpTransition * self)
 {
@@ -404,12 +351,10 @@ wp_transition_get_completed (WpTransition * self)
 }
 
 /*!
- * @memberof WpTransition
+ * \ingroup wptransition
- * @param self: the transition
+ * \param self the transition
- *
+ * \returns TRUE if the transition completed with an error, FALSE otherwise
- * @returns %TRUE if the transition completed with an error, %FALSE otherwise
  */
-
 gboolean
 wp_transition_had_error (WpTransition * self)
 {
@@ -440,34 +385,33 @@ wp_transition_return (WpTransition * self, WpTransitionPrivate *priv)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Advances the transition to the next step.
- * @param self: the transition
  *
- * @brief Advances the transition to the next step.
+ * This initially calls _WpTransitionClass::get_next_step()
- *
- * This initially calls [WpTransitionClass](@ref transition_class_section).get_next_step()
  * in order to determine what the next step is.
- * If [WpTransitionClass](@ref transition_class_section).get_next_step() returns a step
+ * If _WpTransitionClass::get_next_step() returns a step
  * different than the previous one, it calls
- * [WpTransitionClass](@ref transition_class_section).execute_step() to execute it.
+ * _WpTransitionClass::execute_step() to execute it.
  *
- * The very first time that [WpTransitionClass](@ref transition_class_section).get_next_step()
+ * The very first time that _WpTransitionClass::get_next_step()
- * is called, its @em step parameter equals %WP_TRANSITION_STEP_NONE.
+ * is called, its \a step parameter equals WP_TRANSITION_STEP_NONE.
  *
- * When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
+ * When _WpTransitionClass::get_next_step() returns
- * %WP_TRANSITION_STEP_NONE this function completes the transition, calling the transition's
+ * WP_TRANSITION_STEP_NONE this function completes the transition,
- * callback and then unref-ing the transition.
+ * calling the transition's callback and then unref-ing the transition.
  *
- * When [WpTransitionClass](@ref transition_class_section).get_next_step() returns
+ * When _WpTransitionClass::get_next_step() returns
- * %WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(),
+ * WP_TRANSITION_STEP_ERROR, this function calls wp_transition_return_error(),
  * unless it has already been called directly by
- * [WpTransitionClass](@ref transition_class_section).get_next_step().
+ * _WpTransitionClass::get_next_step().
  *
- * In error conditions, [WpTransitionClass](@ref transition_class_section).execute_step()
+ * In error conditions, _WpTransitionClass::execute_step()
- * is called once with @em step being %WP_TRANSITION_STEP_ERROR, allowing the implementation to
+ * is called once with \a step being WP_TRANSITION_STEP_ERROR, allowing the
- * rollback any changes or cancel underlying jobs, if necessary.
+ * implementation to rollback any changes or cancel underlying jobs, if necessary.
+ *
+ * \ingroup wptransition
+ * \param self the transition
  */
-
 void
 wp_transition_advance (WpTransition * self)
 {
@@ -520,19 +464,18 @@ wp_transition_advance (WpTransition * self)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Completes the transition with an error.
- * @param self: the transition
- * @param error: (transfer full): a
- * <a href="https://developer.gnome.org/glib/stable/glib-Error-Reporting.html#GError">
- * GError</a>
  *
- * @brief Completes the transition with an error. This can be called anytime
+ * This can be called anytime from within any virtual function or an async
- * from within any virtual function or an async job handler.
+ * job handler.
  *
- * Note that in most cases this will also unref the transition, so it is
+ * \note In most cases this will also unref the transition, so it is
  * not safe to access it after this function has been called.
+ *
+ * \ingroup wptransition
+ * \param self the transition
+ * \param error (transfer full): a GError
  */
-
 void
 wp_transition_return_error (WpTransition * self, GError * error)
 {
@@ -557,22 +500,19 @@ wp_transition_return_error (WpTransition * self, GError * error)
 }
 
 /*!
- * @memberof WpTransition
+ * \brief Returns the final return status of the transition and its error,
- * @param res: a transition, as a
+ * if there was one.
- * <a href="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncResult-struct">
- * GAsyncResult</a>
- * @param error: (out) (optional): a location to return the transition's error, if any
  *
- * @brief This is meant to be called from within the
+ * This is meant to be called from within the GAsyncReadyCallback
- * <a herf="https://developer.gnome.org/gio/stable/GAsyncResult.html#GAsyncReadyCallback">
+ * that was specified in wp_transition_new().
- * GAsyncReadyCallback</a>
- * that was specified in wp_transition_new(). It returns the final return status
- * of the transition and its error, if there was one.
  *
- * @returns %TRUE if the transition completed successfully, %FALSE if there
+ * \ingroup wptransition
+ * \param res a transition, as a GAsyncResult
+ * \param error (out) (optional): a location to return the transition's error,
+ *   if any
+ * \returns TRUE if the transition completed successfully, FALSE if there
  *   was an error
  */
-
 gboolean
 wp_transition_finish (GAsyncResult * res, GError ** error)
 {
@@ -589,4 +529,4 @@ wp_transition_finish (GAsyncResult * res, GError ** error)
       (priv->step == WP_TRANSITION_STEP_NONE) ? "ok" : "with error");
 
   return (priv->step == WP_TRANSITION_STEP_NONE);
-}
+}

lib/wp/transition.h

@@ -15,50 +15,33 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof WpTransition
+ * \brief The WpTransition GType
- *
+ * \ingroup wptransition
- * @brief The [WpTransition](@ref transition_section)
- * <a href="https://developer.gnome.org/gobject/stable/gobject-Type-Information.html#GType">
- * GType</a>
- *
- * @code
- * #define WP_TYPE_TRANSITION (wp_transition_get_type ())
- * @endcode
- *
  */
 #define WP_TYPE_TRANSITION (wp_transition_get_type ())
 WP_API
 G_DECLARE_DERIVABLE_TYPE (WpTransition, wp_transition, WP, TRANSITION, GObject)
 
 /*!
- * @memberof WpTransition
+ * \brief Values for the \em steps of the implemented state machine
- *
+ * \ingroup wptransition
- * @section transition_step_section WpTransitionStep
- *
- * @brief
- * @em WP_TRANSITION_STEP_NONE: the initial and final step of the transition
- * @em WP_TRANSITION_STEP_ERROR: returned by
- * [WpTransitionClass](@ref transition_class_section).get_next_step() in
- *   case of an error
- * @em WP_TRANSITION_STEP_CUSTOM_START: starting value for steps defined in
- *   subclasses
  */
 typedef enum {
+  /*! the initial and final step of the transition */
   WP_TRANSITION_STEP_NONE = 0,
+  /*! returned by _WpTransitionClass::get_next_step() in case of an error */
   WP_TRANSITION_STEP_ERROR,
+  /*! starting value for steps defined in subclasses */
   WP_TRANSITION_STEP_CUSTOM_START = 0x10
 } WpTransitionStep;
 
-/*!
- * @brief
- * @em get_next_step: See wp_transition_advance()
- * @em execute_step: See wp_transition_advance()
- */
 struct _WpTransitionClass
 {
   GObjectClass parent_class;
 
+  /*! See wp_transition_advance() */
   guint (*get_next_step) (WpTransition * transition, guint step);
+  /*! See wp_transition_advance() */
   void (*execute_step) (WpTransition * transition, guint step);
 };
 

lib/wp/wp.c

@@ -6,30 +6,23 @@
  * SPDX-License-Identifier: MIT
  */
 
-/*!
- * @file wp.c
- */
 #define G_LOG_DOMAIN "wp"
 
 #include "wp.h"
 #include <pipewire/pipewire.h>
 
 /*!
- * @struct Wp
+ * \defgroup wp Library Initialization
- *
+ * \{
- * @section wp_section Wp
- *
  */
 
 /*!
- * @memberof Wp
+ * \param flags: initialization flags
- * @param flags: initialization flags
  *
- * @brief Initializes WirePlumber and PipeWire underneath. @em flags can modify
+ * Initializes WirePlumber and PipeWire underneath.
- * which parts are initialized, in cases where you want to handle part
+ * \em flags can modify which parts are initialized, in cases where you want
- * of this initialization externally.
+ * to handle part of this initialization externally.
  */
-
 void
 wp_init (WpInitFlags flags)
 {
@@ -68,13 +61,8 @@ wp_init (WpInitFlags flags)
 }
 
 /*!
- * @memberof Wp
+ * \returns The Wireplumber module directory
- *
- * @param Void
- *
- * @returns The Wireplumber module directory
  */
-
 const gchar *
 wp_get_module_dir (void)
 {
@@ -88,13 +76,8 @@ wp_get_module_dir (void)
 }
 
 /*!
- * @memberof Wp
+ * \returns The Wireplumber configuration directory
- *
- * @param Void
- *
- * @returns The Wireplumber config directory
  */
-
 const gchar *
 wp_get_config_dir (void)
 {
@@ -108,13 +91,8 @@ wp_get_config_dir (void)
 }
 
 /*!
- * @memberof Wp
+ * \returns The Wireplumber data directory
- *
- * @param Void
- *
- * @returns The Wireplumber data directory
  */
-
 const gchar *
 wp_get_data_dir (void)
 {
@@ -125,4 +103,6 @@ wp_get_data_dir (void)
       data_dir = WIREPLUMBER_DEFAULT_DATA_DIR;
   }
   return data_dir;
-}
+}
+
+/*! \} */

lib/wp/wp.h

@@ -42,20 +42,20 @@
 G_BEGIN_DECLS
 
 /*!
- * @memberof Wp
+ * \ingroup wp
- *
+ * Flags for wp_init()
- * @brief
- * @arg WP_INIT_PIPEWIRE
- * @arg WP_INIT_SPA_TYPES
- * @arg WP_INIT_SET_PW_LOG
- * @arg WP_INIT_SET_GLIB_LOG
- * @arg WP_INIT_ALL
  */
 typedef enum {
+  /*! Initialize PipeWire by calling pw_init() */
   WP_INIT_PIPEWIRE = (1<<0),
+  /*! Initialize support for dynamic spa types.
+   * See wp_spa_dynamic_type_init() */
   WP_INIT_SPA_TYPES = (1<<1),
+  /*! Override PipeWire's logging system with WirePlumber's one */
   WP_INIT_SET_PW_LOG = (1<<2),
+  /*! Set wp_log_writer_default() as GLib's default log writer function */
   WP_INIT_SET_GLIB_LOG = (1<<3),
+  /*! Initialize all of the above */
   WP_INIT_ALL = 0xf,
 } WpInitFlags;