docs: update docs

src/pipewire/context.h

@@ -36,9 +36,25 @@ extern "C" {
  *
  * \brief the PipeWire context
  *
- * The context object manages all available resources.
+ * The context object manages all locally available resources. It
+ * is used by both clients and servers.
  *
- * See \ref page_context_api
+ * The context is used to:
+ *
+ *  - Load modules and extend the functionality. This includes
+ *    extending the protocol with new object types or creating
+ *    any of the available objects.
+ *
+ *  - Create implementations of various objects like nodes,
+ *    devices, factories, modules, etc.. This will usually also
+ *    create pw_global objects that can then be shared with
+ *    clients.
+ *
+ *  - Connect to another PipeWire instance (the main daemon, for
+ *    example) and interact with it (See \subpage page_core_api).
+ *
+ *  - Export a local implementation of an object to another
+ *    instance.
  */
 struct pw_context;
 

src/pipewire/pipewire.h

@@ -67,15 +67,16 @@ extern "C" {
  * This document describes the API for the PipeWire multimedia framework.
  * The API consists of two parts:
  *
- * \li The context API and tools to build new modules (See
- * \subpage page_context_api)
- * \li The remote API (See \subpage page_remote_api)
+ * \li The core API to access a PipeWire instance.
+ * (See \subpage page_core_api)
+ * \li The implementation API and tools to build new objects and
+ * modules (See \subpage page_implementation_api)
  *
  * \section sec_errors Error reporting
  *
- * Functions return either NULL or a negative int error code when an
- * error occurs. Error codes are used from the SPA plugin library on
- * which PipeWire is built.
+ * Functions return either NULL with errno set or a negative int error
+ * code when an error occurs. Error codes are used from the SPA plugin
+ * library on which PipeWire is built.
  *
  * Some functions might return asynchronously. The error code for such
  * functions is positive and SPA_RESULT_IS_ASYNC() will return true.