doc: reorganize Doxygen groups/modules to make more sense

The Doxygen "Modules" page is not very illuminative, as different parts
of the API are mixed together and not all parts are included.

Try to address this:

Put all parts of the public API to some Doxygen group, usually one group
per header file. Use short, systematic names.

Make these groups sub-groups of a few top-level groups, roughly
corresponding to the different logical parts of the API (core, impl,
stream, filter, spa, utilities).
This commit is contained in:
Pauli Virtanen 2021-10-02 20:55:53 +03:00
parent 43a84c4a2c
commit 8159797f89
95 changed files with 588 additions and 154 deletions

View file

@ -33,7 +33,7 @@ extern "C" {
#include <spa/utils/defs.h>
/** \defgroup pw_array Array Objects
/** \defgroup pw_array Array
*
* \brief An array object
*

View file

@ -34,6 +34,14 @@
extern "C" {
#endif
/** \defgroup pw_buffers Buffers
*/
/**
* \addtogroup pw_buffers
* \{
*/
#define PW_BUFFERS_FLAG_NONE 0
#define PW_BUFFERS_FLAG_NO_MEM (1<<0) /**< don't allocate buffer memory */
#define PW_BUFFERS_FLAG_SHARED (1<<1) /**< buffers can be shared */
@ -53,6 +61,10 @@ int pw_buffers_negotiate(struct pw_context *context, uint32_t flags,
void pw_buffers_clear(struct pw_buffers *buffers);
/**
* \}
*/
#ifdef __cplusplus
}
#endif

View file

@ -35,7 +35,7 @@ extern "C" {
#include <pipewire/proxy.h>
#include <pipewire/permission.h>
/** \defgroup pw_client PipeWire Client
/** \defgroup pw_client Client
*
*/

View file

@ -24,9 +24,22 @@
#include <pipewire/context.h>
/** \defgroup pw_conf Configuration
*
*/
/**
* \addtogroup pw_conf
* \{
*/
int pw_conf_load_conf(const char *prefix, const char *name, struct pw_properties *conf);
int pw_conf_load_state(const char *prefix, const char *name, struct pw_properties *conf);
int pw_conf_save_state(const char *prefix, const char *name, const struct pw_properties *conf);
int pw_context_parse_conf_section(struct pw_context *context,
struct pw_properties *conf, const char *section);
/**
* \}
*/

View file

@ -32,7 +32,7 @@ extern "C" {
#include <spa/utils/defs.h>
#include <spa/utils/hook.h>
/** \defgroup pw_context PipeWire Context
/** \defgroup pw_context Context
*
* \brief The PipeWire context object manages all locally available
* resources. It is used by both clients and servers.

View file

@ -34,7 +34,7 @@ extern "C" {
#include <spa/utils/hook.h>
/** \defgroup pw_core The PipeWire Core Global Object
/** \defgroup pw_core Core
*
* \brief The core global object.
*
@ -112,7 +112,6 @@ void pw_core_info_free(struct pw_core_info *info);
/** \struct pw_core_events
* \brief Core events
* \ingroup pw_core_interface The pw_core interface
*/
struct pw_core_events {
#define PW_VERSION_CORE_EVENTS 0

View file

@ -31,7 +31,9 @@ extern "C" {
#include <spa/utils/hook.h>
/** \defgroup pw_data_loop PipeWire rt-loop object
/** \defgroup pw_data_loop Data Loop
*
* \brief PipeWire rt-loop object
*
* This loop starts a new real-time thread that
* is designed to run the processing graph.

View file

@ -34,6 +34,15 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_device Device
*
*/
/**
* \addtogroup pw_device
* \{
*/
#define PW_TYPE_INTERFACE_Device PW_TYPE_INFO_INTERFACE_BASE "Device"
#define PW_VERSION_DEVICE 3
@ -158,6 +167,10 @@ struct pw_device_methods {
#define pw_device_enum_params(c,...) pw_device_method(c,enum_params,0,__VA_ARGS__)
#define pw_device_set_param(c,...) pw_device_method(c,set_param,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -32,6 +32,14 @@ extern "C" {
#include <spa/utils/defs.h>
#include <spa/param/param.h>
/** \defgroup pw_client_node Client Node
*
*/
/**
* \addtogroup pw_client_node
* \{
*/
#define PW_TYPE_INTERFACE_ClientNode PW_TYPE_INFO_INTERFACE_BASE "ClientNode"
#define PW_VERSION_CLIENT_NODE 4
@ -338,6 +346,10 @@ pw_client_node_get_node(struct pw_client_node *p, uint32_t version, size_t user_
#define pw_client_node_event(c,...) pw_client_node_method(c,event,0,__VA_ARGS__)
#define pw_client_node_port_buffers(c,...) pw_client_node_method(c,port_buffers,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -31,6 +31,14 @@ extern "C" {
#include <spa/utils/defs.h>
/** \defgroup pw_metadata Metadata
*
*/
/**
* \addtogroup pw_metadata
* \{
*/
#define PW_TYPE_INTERFACE_Metadata PW_TYPE_INFO_INTERFACE_BASE "Metadata"
#define PW_VERSION_METADATA 3
@ -93,6 +101,10 @@ struct pw_metadata_methods {
#define PW_KEY_METADATA_NAME "metadata.name"
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -31,6 +31,14 @@ extern "C" {
#include <spa/utils/defs.h>
/** \defgroup pw_profiler Profiler
*
*/
/**
* \addtogroup pw_profiler
* \{
*/
#define PW_TYPE_INTERFACE_Profiler PW_TYPE_INFO_INTERFACE_BASE "Profiler"
#define PW_VERSION_PROFILER 3
@ -76,6 +84,10 @@ struct pw_profiler_methods {
#define PW_KEY_PROFILER_NAME "profiler.name"
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -34,6 +34,14 @@ extern "C" {
#include <pipewire/proxy.h>
#include <pipewire/resource.h>
/** \defgroup pw_protocol_native Native Protocol
*
*/
/**
* \addtogroup pw_protocol_native
* \{
*/
#define PW_TYPE_INFO_PROTOCOL_Native PW_TYPE_INFO_PROTOCOL_BASE "Native"
struct pw_protocol_native_message {
@ -86,6 +94,10 @@ struct pw_protocol_native_ext {
#define pw_protocol_native_get_resource_fd(r,...) pw_protocol_ext(pw_resource_get_protocol(r),struct pw_protocol_native_ext,get_resource_fd,r,__VA_ARGS__)
#define pw_protocol_native_end_resource(r,...) pw_protocol_ext(pw_resource_get_protocol(r),struct pw_protocol_native_ext,end_resource,r,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -26,9 +26,22 @@
#ifndef PIPEWIRE_EXT_SESSION_MANAGER_H
#define PIPEWIRE_EXT_SESSION_MANAGER_H
/** \defgroup pw_session_manager Session Manager
*
*/
/**
* \addtogroup pw_session_manager
* \{
*/
#include "session-manager/introspect.h"
#include "session-manager/interfaces.h"
#include "session-manager/impl-interfaces.h"
#include "session-manager/keys.h"
/**
* \}
*/
#endif /* PIPEWIRE_EXT_SESSION_MANAGER_H */

View file

@ -36,6 +36,15 @@
extern "C" {
#endif
/** \defgroup pw_session_manager_impl Implementation
*
*/
/**
* \addtogroup pw_session_manager_impl
* \{
*/
#define PW_TYPE_INTERFACE_ClientEndpoint PW_TYPE_INFO_INTERFACE_BASE "ClientEndpoint"
#define PW_VERSION_CLIENT_ENDPOINT 0
@ -282,6 +291,10 @@ struct pw_client_session_methods {
#define pw_client_session_update(o,...) pw_client_session_method(o,update,0,__VA_ARGS__)
#define pw_client_session_link_update(o,...) pw_client_session_method(o,link_update,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -35,6 +35,11 @@
extern "C" {
#endif
/**
* \addtogroup pw_session_manager
* \{
*/
#define PW_TYPE_INTERFACE_Session PW_TYPE_INFO_INTERFACE_BASE "Session"
#define PW_VERSION_SESSION 0
struct pw_session;
@ -463,6 +468,10 @@ struct pw_endpoint_link_methods {
#define pw_endpoint_link_request_state(c,...) pw_endpoint_link_method(c,request_state,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -34,6 +34,11 @@
extern "C" {
#endif
/**
* \addtogroup pw_session_manager
* \{
*/
static inline struct pw_session_info *
pw_session_info_update (struct pw_session_info *info,
const struct pw_session_info *update)
@ -307,6 +312,10 @@ pw_endpoint_link_info_free (struct pw_endpoint_link_info *info)
free(ext);
}
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -34,6 +34,11 @@
extern "C" {
#endif
/**
* \addtogroup pw_session_manager
* \{
*/
enum pw_endpoint_link_state {
PW_ENDPOINT_LINK_STATE_ERROR = -1,
PW_ENDPOINT_LINK_STATE_PREPARING,
@ -114,6 +119,10 @@ struct pw_endpoint_link_info {
uint32_t n_params; /**< number of items in \a params */
};
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -30,6 +30,11 @@
extern "C" {
#endif
/**
* \addtogroup pw_session_manager
* \{
*/
#define PW_KEY_SESSION_ID "session.id" /**< id of a session manager */
#define PW_KEY_ENDPOINT_ID "endpoint.id" /**< id of an endpoint */
@ -51,6 +56,10 @@ extern "C" {
#define PW_KEY_ENDPOINT_LINK_INPUT_ENDPOINT "endpoint-link.input.endpoint" /**< input endpoint of link */
#define PW_KEY_ENDPOINT_LINK_INPUT_STREAM "endpoint-link.input.stream" /**< input stream of link */
/**
* \}
*/
#ifdef __cplusplus
}
#endif

View file

@ -37,6 +37,14 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_factory Factory
*
*/
/**
* \addtogroup pw_factory
* \{
*/
#define PW_TYPE_INTERFACE_Factory PW_TYPE_INFO_INTERFACE_BASE "Factory"
#define PW_VERSION_FACTORY 3
@ -104,6 +112,10 @@ struct pw_factory_methods {
#define pw_factory_add_listener(c,...) pw_factory_method(c,add_listener,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -29,14 +29,14 @@
extern "C" {
#endif
/** \defgroup pw_filter PipeWire Filter
/** \defgroup pw_filter Filter API
*
* \brief PipeWire filter object class
*
* The filter object provides a convenient way to implement
* processing filters.
*
* See also \ref page_core_api
* See also \ref api_pw_core
*/
/**

View file

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

View file

@ -29,6 +29,14 @@
extern "C" {
#endif
/** \defgroup pw_gettext Internationalization
*
*/
/**
* \addtogroup pw_gettext
* \{
*/
#include <spa/support/i18n.h>
SPA_FORMAT_ARG_FUNC(1) const char *pw_gettext(const char *msgid);
@ -37,6 +45,10 @@ SPA_FORMAT_ARG_FUNC(1) const char *pw_ngettext(const char *msgid, const char *ms
#define _(String) (pw_gettext(String))
#define N_(String) (String)
/**
* \}
*/
#ifdef __cplusplus
}
#endif

View file

@ -31,7 +31,7 @@ extern "C" {
#include <spa/utils/hook.h>
/** \page page_client Client
/** \page page_client Client Implementation
*
* \section sec_page_client_overview Overview
*
@ -61,7 +61,7 @@ extern "C" {
* See also \ref pw_resource
*/
/** \defgroup pw_impl_client Client Object
/** \defgroup pw_impl_client Client Impl
*
* \brief PipeWire client object class
*

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_core PipeWire Core Interface
/** \defgroup pw_impl_core Core Impl
*
* \brief PipeWire core interface.
*

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_device PipeWire Device Interface
/** \defgroup pw_impl_device Device Impl
*
* The device is an object that manages nodes. It typically
* corresponds to a physical hardware device but it does not

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_factory PipeWire Factory Interface
/** \defgroup pw_impl_factory Factory Impl
*
* The factory is used to make objects on demand.
*/

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_link Link Objects
/** \defgroup pw_impl_link Link Impl
*
* \brief PipeWire link object.
*/

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_metadata PipeWire Metadata Interface
/** \defgroup pw_impl_metadata Metadata Impl
*
* The metadata is used to store key/type/value pairs per object id.
*/

View file

@ -37,13 +37,13 @@ extern "C" {
#define PIPEWIRE_SYMBOL_MODULE_INIT "pipewire__module_init"
#define PIPEWIRE_MODULE_PREFIX "libpipewire-"
/** \defgroup pw_impl_module Dynamically loadable Module
/** \defgroup pw_impl_module Module Impl
*
* A dynamically loadable module
*/
/**
* \addtogropu pw_impl_module
* \addtogroup pw_impl_module
* \{
*/
struct pw_impl_module;

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_impl_node Node
/** \defgroup pw_impl_node Node Impl
*
* The node object processes data. The node has a list of
* input and output ports (\ref pw_impl_port) on which it

View file

@ -31,7 +31,7 @@ extern "C" {
#include <spa/utils/hook.h>
/** \defgroup pw_impl_port Port Object
/** \defgroup pw_impl_port Port Impl
*
* \brief A port can be used to link two nodes.
*/

View file

@ -29,6 +29,10 @@
extern "C" {
#endif
/**
* \addtogroup api_pw_impl
*/
struct pw_impl_client;
struct pw_impl_module;
struct pw_global;

View file

@ -30,7 +30,7 @@ extern "C" {
#endif
/**
* \defgroup pw_keys PipeWire Keys
* \defgroup pw_keys Key Names
*
* A collection of keys that are used to add extra information on objects.
*

View file

@ -34,7 +34,7 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_link PipeWire Link
/** \defgroup pw_link Link
*
* A link is the connection between 2 nodes (\ref pw_node). Nodes are
* linked together on ports.

View file

@ -32,7 +32,7 @@ extern "C" {
#include <spa/support/loop.h>
#include <spa/utils/dict.h>
/** \defgroup pw_loop PipeWire Loop
/** \defgroup pw_loop Loop
*
* PipeWire loop object provides an implementation of
* the spa loop interfaces. It can be used to implement various

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_main_loop PipeWire Main-Loop Interface
/** \defgroup pw_main_loop Main Loop
*
* A main loop object
*/

View file

@ -35,7 +35,7 @@ extern "C" {
#include <spa/utils/defs.h>
#include <pipewire/array.h>
/** \defgroup pw_map Map Objects
/** \defgroup pw_map Map
*
* \brief A map that holds objects indexed by id
*/

View file

@ -34,6 +34,14 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_module Module
*
*/
/**
* \addtogroup pw_module
* \{
*/
#define PW_TYPE_INTERFACE_Module PW_TYPE_INFO_INTERFACE_BASE "Module"
#define PW_VERSION_MODULE 3
@ -102,6 +110,10 @@ struct pw_module_methods {
#define pw_module_add_listener(c,...) pw_module_method(c,add_listener,0,__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -39,7 +39,7 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_node PipeWire Node
/** \defgroup pw_node Node
*
*/

View file

@ -31,7 +31,7 @@ extern "C" {
#include <spa/utils/defs.h>
/** \defgroup pw_permission PipeWire Permission
/** \defgroup pw_permission Permission
*
* Permissions are kept for a client and describe what the client is
* allowed to do with an object.

View file

@ -60,10 +60,9 @@ extern "C" {
#include <pipewire/utils.h>
#include <pipewire/version.h>
/** \defgroup pw_pipewire PipeWire initialization and infrastructure functions
/** \defgroup pw_pipewire Initialization etc.
*/
/**
* \addtogroup pw_pipewire
* \{

View file

@ -38,7 +38,7 @@ extern "C" {
#include <pipewire/proxy.h>
/** \defgroup pw_port PipeWire Port
/** \defgroup pw_port Port
*
*/

View file

@ -34,7 +34,7 @@ extern "C" {
#include <spa/utils/dict.h>
#include <spa/utils/string.h>
/** \defgroup pw_properties Key-Value pairs
/** \defgroup pw_properties Properties
*
* Properties are used to pass around arbitrary key/value pairs.
* Both keys and values are strings which keeps things simple.

View file

@ -31,7 +31,7 @@ extern "C" {
#include <spa/utils/list.h>
/** \defgroup pw_protocol PipeWire Protocol
/** \defgroup pw_protocol Protocol
*
* \brief Manages protocols and their implementation
*/

View file

@ -87,7 +87,7 @@ extern "C" {
* associated to the proxy.
*/
/** \defgroup pw_proxy Proxy Object
/** \defgroup pw_proxy Proxy
*
* \brief Represents an object on the client side.
*

View file

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

View file

@ -144,14 +144,14 @@ extern "C" {
*
* Use \ref pw_stream_disconnect() to disconnect a stream after use.
*/
/** \defgroup pw_stream Stream Object
/** \defgroup pw_stream Stream API
*
* \brief PipeWire stream objects
*
* The stream object provides a convenient way to send and
* receive data streams from/to PipeWire.
*
* See also \ref page_streams and \ref page_core_api
* See also \ref page_streams and \ref api_pw_core
*/
/**

View file

@ -31,7 +31,7 @@ extern "C" {
#include <pipewire/loop.h>
/** \page page_thread_loop Threaded Loop
/** \page page_thread_loop Thread Loop
*
* \section sec_thread_loop_overview Overview
*
@ -80,7 +80,7 @@ extern "C" {
* All events and callbacks are called with the thread lock held.
*
*/
/** \defgroup pw_thread_loop PipeWire Threaded Loop Object
/** \defgroup pw_thread_loop Thread Loop
*
* The threaded loop object runs a \ref pw_loop in a separate thread
* and ensures proper locking is done.

View file

@ -34,11 +34,16 @@ extern "C" {
#include <spa/support/thread.h>
/** \defgroup spa_thread Thread related functions
/** \defgroup pw_thread Thread
*
* \brief functions to manipulate threads
*/
/**
* \addtogroup pw_thread
* \{
*/
void pw_thread_utils_set(struct spa_thread_utils *impl);
struct spa_thread_utils *pw_thread_utils_get(void);
@ -48,6 +53,10 @@ struct spa_thread_utils *pw_thread_utils_get(void);
#define pw_thread_utils_acquire_rt(...) spa_thread_utils_acquire_rt(pw_thread_utils_get(), ##__VA_ARGS__)
#define pw_thread_utils_drop_rt(...) spa_thread_utils_drop_rt(pw_thread_utils_get(), ##__VA_ARGS__)
/**
* \}
*/
#ifdef __cplusplus
} /* extern "C" */
#endif

View file

@ -31,7 +31,7 @@ extern "C" {
#include <spa/utils/type.h>
/** \defgroup pw_type PipeWire Types
/** \defgroup pw_type Type
*/
/**

View file

@ -38,7 +38,7 @@ extern "C" {
#include <spa/utils/defs.h>
#include <spa/pod/pod.h>
/** \defgroup pw_utils PipeWire Utility Functions
/** \defgroup pw_utils Utilities
*
* Various utility functions
*/

View file

@ -29,7 +29,7 @@
extern "C" {
#endif
/** \defgroup pw_work_queue PipeWire Work Queue Object
/** \defgroup pw_work_queue Work Queue
*/
/**