doc: add brief explanations for all groups

2025-10-29 05:40:27 -04:00 · 2021-10-04 00:00:41 +03:00 · 2021-10-04 00:00:41 +03:00 · 49901f2d61
commit 49901f2d61
parent 125051a700
44 changed files with 46 additions and 31 deletions
--- a/doc/api-tree.dox
+++ b/doc/api-tree.dox
@ -80,6 +80,7 @@
 \addtogroup spa_param
 \addtogroup spa_pod
 \defgroup spa_utils Utilities
+Utility data structures, macros, etc.
 \{
 \addtogroup spa_ansi
 \addtogroup spa_utils_defs
@ -96,6 +97,7 @@
 \addtogroup spa_types
 \}
 \defgroup spa_support Support
+Support interfaces provided by host
 \{
 \addtogroup spa_cpu
 \addtogroup spa_dbus
--- a/spa/include/spa/control/control.h
+++ b/spa/include/spa/control/control.h
@ -33,7 +33,7 @@ extern "C" {
 #include <spa/pod/pod.h>

 /** \defgroup spa_control Control
- *
+ * Control type declarations
 */

 /**
--- a/spa/include/spa/debug/buffer.h
+++ b/spa/include/spa/debug/buffer.h
@ -30,7 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_debug Debug
- *
+ * Debugging utilities
 */

 /**
--- a/spa/include/spa/graph/graph.h
+++ b/spa/include/spa/graph/graph.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_graph Graph
+ * Node graph
 */

 /**
--- a/spa/include/spa/param/param.h
+++ b/spa/include/spa/param/param.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_param Parameters
+ * Parameter value enumerations and type information
 */

 /**
--- a/spa/include/spa/pod/builder.h
+++ b/spa/include/spa/pod/builder.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_pod POD
+ * Binary data serialization format
 */

 /**
--- a/spa/include/spa/support/cpu.h
+++ b/spa/include/spa/support/cpu.h
@ -35,7 +35,7 @@ extern "C" {
 #include <spa/utils/hook.h>

 /** \defgroup spa_cpu CPU
- *
+ * Querying CPU properties
 */

 /**
--- a/spa/include/spa/support/dbus.h
+++ b/spa/include/spa/support/dbus.h
@ -32,7 +32,7 @@ extern "C" {
 #include <spa/support/loop.h>

 /** \defgroup spa_dbus DBus
- *
+ * DBus communication
 */

 /**
--- a/spa/include/spa/support/i18n.h
+++ b/spa/include/spa/support/i18n.h
@ -33,7 +33,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup spa_i18n I18N
- *
+ * Gettext interface
 */

 /**
--- a/spa/include/spa/support/log.h
+++ b/spa/include/spa/support/log.h
@ -36,6 +36,7 @@ extern "C" {
 #include <spa/utils/hook.h>

 /** \defgroup spa_log Log
+ * Logging interface
 */

 /**
--- a/spa/include/spa/support/loop.h
+++ b/spa/include/spa/support/loop.h
@ -34,7 +34,7 @@ extern "C" {
 #include <spa/support/system.h>

 /** \defgroup spa_loop Loop
- *
+ * Event loop interface
 */

 /**
--- a/spa/include/spa/support/plugin-loader.h
+++ b/spa/include/spa/support/plugin-loader.h
@ -33,7 +33,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup spa_plugin_loader Plugin Loader
- *
+ * SPA plugin loader
 */

 /**
--- a/spa/include/spa/support/plugin.h
+++ b/spa/include/spa/support/plugin.h
@ -34,6 +34,7 @@ extern "C" {

 /**
 * \defgroup spa_handle Plugin Handle
+ * SPA plugin handle and factory interfaces
 */

 /**
--- a/spa/include/spa/support/system.h
+++ b/spa/include/spa/support/system.h
@ -38,7 +38,7 @@ struct itimerspec;
 #include <spa/utils/hook.h>

 /** \defgroup spa_system System
- *
+ * I/O, clock, polling, timer, and signal interfaces
 */

 /**
--- a/spa/include/spa/support/thread.h
+++ b/spa/include/spa/support/thread.h
@ -37,7 +37,7 @@ extern "C" {
 #include <spa/utils/dict.h>

 /** \defgroup spa_thread Thread
- *
+ * Threading utility interfaces
 */

 /**
--- a/spa/include/spa/utils/ansi.h
+++ b/spa/include/spa/utils/ansi.h
@ -31,7 +31,7 @@ extern "C" {

 /**
 * \defgroup spa_ansi ANSI codes
- *
+ * ANSI color code macros
 */

 /**
--- a/spa/include/spa/utils/defs.h
+++ b/spa/include/spa/utils/defs.h
@ -39,7 +39,7 @@ extern "C" {

 /**
 * \defgroup spa_utils_defs Miscellaneous
- *
+ * Helper macros and functions
 */

 /**
--- a/spa/include/spa/utils/dict.h
+++ b/spa/include/spa/utils/dict.h
@ -35,7 +35,7 @@ extern "C" {

 /**
 * \defgroup spa_dict Dictionary
- *
+ * Dictionary data structure
 */

 /**
--- a/spa/include/spa/utils/json.h
+++ b/spa/include/spa/utils/json.h
@ -38,6 +38,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup spa_json JSON
+ * Relaxed JSON variant parsing
 */

 /**
--- a/spa/include/spa/utils/keys.h
+++ b/spa/include/spa/utils/keys.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_keys  Key Names
+ * Key names used by SPA plugins
 */

 /**
--- a/spa/include/spa/utils/list.h
+++ b/spa/include/spa/utils/list.h
@ -31,7 +31,7 @@ extern "C" {

 /**
 * \defgroup spa_list List
- *
+ * Doubly linked list data structure
 */

 /**
--- a/spa/include/spa/utils/names.h
+++ b/spa/include/spa/utils/names.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup spa_names Factory Names
+ * SPA plugin factory names
 */

 /**
--- a/spa/include/spa/utils/result.h
+++ b/spa/include/spa/utils/result.h
@ -31,7 +31,7 @@ extern "C" {

 /**
 * \defgroup spa_result Result handling
- *
+ * Asynchronous result utilities
 */

 /**
--- a/spa/include/spa/utils/ringbuffer.h
+++ b/spa/include/spa/utils/ringbuffer.h
@ -31,7 +31,7 @@ extern "C" {

 /**
 * \defgroup spa_ringbuffer Ringbuffer
- *
+ * Ring buffer implementation
 */

 /**
--- a/spa/include/spa/utils/string.h
+++ b/spa/include/spa/utils/string.h
@ -37,7 +37,7 @@ extern "C" {

 /**
 * \defgroup spa_string String handling
- *
+ * String handling utilities
 */

 /**
--- a/spa/include/spa/utils/type.h
+++ b/spa/include/spa/utils/type.h
@ -32,6 +32,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup spa_types Types
+ * Data type information enumerations
 */

 /**
--- a/src/pipewire/buffers.h
+++ b/src/pipewire/buffers.h
@ -35,6 +35,7 @@ extern "C" {
 #endif

 /** \defgroup pw_buffers Buffers
+ * Buffer handling
 */

 /**
--- a/src/pipewire/client.h
+++ b/src/pipewire/client.h
@ -36,7 +36,7 @@ extern "C" {
 #include <pipewire/permission.h>

 /** \defgroup pw_client Client
- *
+ * Client interface
 */

 /**
--- a/src/pipewire/conf.h
+++ b/src/pipewire/conf.h
@ -25,7 +25,7 @@
 #include <pipewire/context.h>

 /** \defgroup pw_conf Configuration
- *
+ * Loading/saving properties from/to configuration files.
 */

 /**
--- a/src/pipewire/device.h
+++ b/src/pipewire/device.h
@ -35,7 +35,7 @@ extern "C" {
 #include <pipewire/proxy.h>

 /** \defgroup pw_device Device
- *
+ * Device interface
 */

 /**
--- a/src/pipewire/extensions/client-node.h
+++ b/src/pipewire/extensions/client-node.h
@ -33,7 +33,7 @@ extern "C" {
 #include <spa/param/param.h>

 /** \defgroup pw_client_node Client Node
- *
+ * Client node interface
 */

 /**
--- a/src/pipewire/extensions/metadata.h
+++ b/src/pipewire/extensions/metadata.h
@ -32,7 +32,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup pw_metadata Metadata
- *
+ * Metadata interface
 */

 /**
--- a/src/pipewire/extensions/profiler.h
+++ b/src/pipewire/extensions/profiler.h
@ -32,7 +32,7 @@ extern "C" {
 #include <spa/utils/defs.h>

 /** \defgroup pw_profiler Profiler
- *
+ * Profiler interface
 */

 /**
--- a/src/pipewire/extensions/protocol-native.h
+++ b/src/pipewire/extensions/protocol-native.h
@ -35,7 +35,7 @@ extern "C" {
 #include <pipewire/resource.h>

 /** \defgroup pw_protocol_native Native Protocol
- *
+ * PipeWire native protocol interface
 */

 /**
--- a/src/pipewire/extensions/session-manager.h
+++ b/src/pipewire/extensions/session-manager.h
@ -27,7 +27,7 @@
 #define PIPEWIRE_EXT_SESSION_MANAGER_H

 /** \defgroup pw_session_manager Session Manager
- *
+ * Session manager interface
 */

 /**
--- a/src/pipewire/factory.h
+++ b/src/pipewire/factory.h
@ -38,7 +38,7 @@ extern "C" {
 #include <pipewire/proxy.h>

 /** \defgroup pw_factory Factory
- *
+ * Factory interface
 */

 /**
--- a/src/pipewire/i18n.h
+++ b/src/pipewire/i18n.h
@ -30,7 +30,7 @@ extern "C" {
 #endif

 /** \defgroup pw_gettext Internationalization
- *
+ * Gettext interface
 */

 /**
--- a/src/pipewire/mem.h
+++ b/src/pipewire/mem.h
@ -32,7 +32,7 @@ extern "C" {
 #endif

 /** \defgroup pw_memblock Memory Blocks
- *
+ * Memory allocation and pools.
 */

 /**
--- a/src/pipewire/module.h
+++ b/src/pipewire/module.h
@ -35,7 +35,7 @@ extern "C" {
 #include <pipewire/proxy.h>

 /** \defgroup pw_module Module
- *
+ * Module interface
 */

 /**
--- a/src/pipewire/node.h
+++ b/src/pipewire/node.h
@ -40,7 +40,7 @@ extern "C" {
 #include <pipewire/proxy.h>

 /** \defgroup pw_node Node
- *
+ * Node interface
 */

 /**
--- a/src/pipewire/pipewire.h
+++ b/src/pipewire/pipewire.h
@ -61,6 +61,7 @@ extern "C" {
 #include <pipewire/version.h>

 /** \defgroup pw_pipewire Initialization
+ * Initializing PipeWire and loading SPA modules.
 */

 /**
--- a/src/pipewire/port.h
+++ b/src/pipewire/port.h
@ -39,7 +39,7 @@ extern "C" {
 #include <pipewire/proxy.h>

 /** \defgroup pw_port Port
- *
+ * Port interface
 */

 /**
--- a/src/pipewire/type.h
+++ b/src/pipewire/type.h
@ -31,7 +31,8 @@ extern "C" {

 #include <spa/utils/type.h>

-/** \defgroup pw_type Type
+/** \defgroup pw_type Type info
+ * Type information
 */

 /**
--- a/src/pipewire/work-queue.h
+++ b/src/pipewire/work-queue.h
@ -30,6 +30,7 @@ extern "C" {
 #endif

 /** \defgroup pw_work_queue Work Queue
+ * Queued processing of work items.
 */

 /**