doc: document the core/implementation API split a bit better

Still missing a proper review of the linked objects, but at least this
now explains why those two are split.

doc/api.dox

@@ -2,7 +2,93 @@
 
 The API consists of two parts:
 
-- The \subpage page_core_api to access a PipeWire instance.
-- The \subpage page_implementation_api and tools to build new objects and modules
+- The \ref page_core_api to access a PipeWire instance. This API is used
+by all clients that need to communicate with the \ref page_daemon and provides
+the necessary structs to interface with the daemon.
+- The \ref page_implementation_api and tools to build new objects and modules.
+This API is primarily used by the \ref page_daemon itself but also by the
+\ref page_session_manager and modules/extensions that need to build objects in
+the graph.
+
+The APIs work through proxy objects, so that calling a method on an object
+invokes that same method on the remote side. Marshalling and de-marshalling is
+handled transparently by the \ref page_module_protocol_native.
+The below graph illustrates this approach:
+
+@dot
+digraph API {
+  compound=true;
+  node [shape="box"];
+  rankdir="RL";
+
+  subgraph cluster_daemon {
+       rankdir="TB";
+       label="PipeWire daemon";
+       style="dashed";
+
+       impl_core [label="Core Impl. Object"];
+       impl_device [label="Device Impl. Object"];
+       impl_node [label="Node Impl. Object"];
+  }
+
+  subgraph cluster_client {
+       rankdir="TB";
+       label="PipeWire client";
+       style="dashed";
+
+       obj_core [label="Core Object"];
+       obj_device [label="Device Object"];
+       obj_node [label="Node Object"];
+  }
+
+  obj_core -> impl_core;
+  obj_device -> impl_device;
+  obj_node -> impl_node;
+
+}
+@enddot
+
+It is common for clients to use both the Core API and the Implementation API
+and both APIs are provided by the same library.
+
+\section page_core_api Core API
+
+The Core API serves to access a PipeWire instance. This API is used by all
+clients to communicate with the \ref page_daemon. It consists of the
+following object-specific APIs:
+
+- \ref pw_core
+- \ref pw_context
+- \ref pw_global
+- \ref pw_client
+- \ref pw_resource
+- \ref pw_node
+- \ref pw_port
+- \ref pw_link
+
+If you are familiar with Wayland implementation, the Core API is
+roughly equivalent to libwayland-client.
+
+\section page_implementation_api Implementation API
+
+The implementation API provides the tools to build new objects and
+modules. It consists of the following object-specific APIs:
+
+- \ref pw_impl_core
+- \ref pw_impl_client
+- \ref pw_impl_device
+- \ref pw_impl_factory
+- \ref pw_impl_link
+- \ref pw_impl_metadata
+- \ref pw_impl_module
+- \ref pw_impl_node
+- \ref pw_impl_port
+- \ref pw_control
+- \ref pw_global
+- \ref pw_resource
+- \ref pw_work_queue
+
+If you are familiar with Wayland implementation, the Implementation API is
+roughly equivalent to libwayland-server.
 
 */

src/pipewire/context.h

@@ -32,21 +32,6 @@ extern "C" {
 #include <spa/utils/defs.h>
 #include <spa/utils/hook.h>
 
-/** \page page_core_api Core API
- *
- * The Core API serves to access a PipeWire instance. It consists of the
- * following object-specific APIs:
- *
- * - \ref pw_context
- * - \ref pw_global
- * - \ref pw_client
- * - \ref pw_resource
- * - \ref pw_node
- * - \ref pw_port
- * - \ref pw_link
- *
- */
-
 /** \defgroup pw_context PipeWire Context
  *
  * \brief The PipeWire context object manages all locally available

src/pipewire/core.h

@@ -34,11 +34,11 @@ extern "C" {
 
 #include <spa/utils/hook.h>
 
-/** \defgroup pw_core The Core Global Object
+/** \defgroup pw_core The PipeWire Core Global Object
  *
  * \brief The core global object.
  *
- * This is a special singleton object.  It
+ * This is a special singleton object. It
  * is used for internal PipeWire protocol features.
  */
 

src/pipewire/global.h

@@ -29,7 +29,7 @@
 extern "C" {
 #endif
 
-/** \defgroup pw_global Global Object
+/** \defgroup pw_global PipeWire Global Object
  *
  * \brief A global object visible to remote clients
  *

src/pipewire/impl.h

@@ -29,28 +29,6 @@
 extern "C" {
 #endif
 
-/** \page page_implementation_api Implementation API
- *
- * The implementation API provides the tools to build new objects and
- * modules. It consists of the following object-specific APIs:
- *
- * - \ref pw_impl_core
- * - \ref pw_impl_client
- * - \ref pw_impl_device
- * - \ref pw_impl_factory
- * - \ref pw_impl_link
- * - \ref pw_impl_metadata
- * - \ref pw_impl_module
- * - \ref pw_impl_node
- * - \ref pw_impl_port
- * - \ref pw_control
- * - \ref pw_global
- * - \ref pw_resource
- * - \ref pw_work_queue
- *
- */
-
-
 struct pw_impl_client;
 struct pw_impl_module;
 struct pw_global;

src/pipewire/resource.h

@@ -31,7 +31,7 @@ extern "C" {
 
 #include <spa/utils/hook.h>
 
-/** \defgroup pw_resource Resources
+/** \defgroup pw_resource PipeWire Resources
  *
  * \brief Client owned objects
  *