From f70e547614427ff35639d3f75a740793c9a8398b Mon Sep 17 00:00:00 2001 From: Nedko Arnaudov Date: Sat, 18 Nov 2023 15:23:18 +0200 Subject: [PATCH] Fix doxygen issues in jack API headers --- common/jack/control.h | 9 +++++---- common/jack/intclient.h | 5 +++++ common/jack/jack.h | 30 ++++++++++++++++++------------ common/jack/metadata.h | 6 +++--- common/jack/midiport.h | 4 ++++ common/jack/ringbuffer.h | 3 ++- common/jack/session.h | 5 +++++ common/jack/statistics.h | 7 ++++++- common/jack/thread.h | 5 ++++- common/jack/transport.h | 5 +++++ common/jack/types.h | 9 +++++++-- doc/mainpage.dox | 2 -- 12 files changed, 64 insertions(+), 26 deletions(-) diff --git a/common/jack/control.h b/common/jack/control.h index f2f5b1de..4023debf 100644 --- a/common/jack/control.h +++ b/common/jack/control.h @@ -619,7 +619,8 @@ jack_log( * Tie two ports. This will make anything appearing on the playback port (input, sink) * to appear as if sent from the capture port (output, source) * - * @param port jack port to untie + * @param src jack port to tie + * @param dst jack port to tie * * @return 0 on success, otherwise a non-zero error code */ @@ -642,12 +643,12 @@ typedef struct jackctl_subgraph jackctl_subgraph_t; * along with virtual device for the subgraph. * For clients that are associated with a subgraph, * virtual device will be seen as JACK client named "system" and the - * name provided through @c name parameter may be used as client alias. + * name provided through @c client_name parameter may be used as client alias. * For JACK clients that are not associated with any subgraph, - * the provided through @c name parameter name will be used for + * the provided through @c client_name parameter name will be used for * jack client name and may be used as client alias. * - * @param name Name of the subgraph and virtual device. + * @param client_name Name of the subgraph and virtual device. * * @return NULL on error, handle to subgraph object on success */ diff --git a/common/jack/intclient.h b/common/jack/intclient.h index d4503aee..0d836a6a 100644 --- a/common/jack/intclient.h +++ b/common/jack/intclient.h @@ -17,6 +17,11 @@ * */ +/** + * @file jack/intclient.h + * @brief load and unload JACK internal clients + */ + #ifndef __jack_intclient_h__ #define __jack_intclient_h__ diff --git a/common/jack/jack.h b/common/jack/jack.h index b7a43b47..bfa61699 100644 --- a/common/jack/jack.h +++ b/common/jack/jack.h @@ -18,6 +18,11 @@ */ +/** + * @file jack/jack.h + * @brief The main JACK interface header + */ + #ifndef __jack_h__ #define __jack_h__ @@ -55,9 +60,9 @@ extern "C" * * @param minor_ptr pointer to variable receiving minor version of JACK. * - * @param major_ptr pointer to variable receiving micro version of JACK. + * @param micro_ptr pointer to variable receiving micro version of JACK. * - * @param major_ptr pointer to variable receiving protocol version of JACK. + * @param proto_ptr pointer to variable receiving protocol version of JACK. * */ void @@ -119,8 +124,8 @@ jack_client_t * jack_client_open (const char *client_name, jack_status_t *status, ...) JACK_OPTIONAL_WEAK_EXPORT; /** -* \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN -* NEW JACK CLIENTS +* THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN +* NEW JACK CLIENTS * * @deprecated Please use jack_client_open(). */ @@ -247,8 +252,8 @@ int jack_is_realtime (jack_client_t *client) JACK_OPTIONAL_WEAK_EXPORT; */ /** - * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN - * NEW JACK CLIENTS. + * THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN + * NEW JACK CLIENTS. * * @deprecated Please use jack_cycle_wait() and jack_cycle_signal() functions. */ @@ -316,7 +321,7 @@ int jack_set_thread_init_callback (jack_client_t *client, /** * @param client pointer to JACK client structure. - * @param function The jack_shutdown function pointer. + * @param shutdown_callback The jack_shutdown function pointer. * @param arg The arguments for the jack_shutdown function. * * Register a function (and argument) to be called if and when the @@ -347,7 +352,7 @@ void jack_on_shutdown (jack_client_t *client, /** * @param client pointer to JACK client structure. - * @param function The jack_info_shutdown function pointer. + * @param shutdown_callback The jack_info_shutdown function pointer. * @param arg The arguments for the jack_info_shutdown function. * * Register a function (and argument) to be called if and when the @@ -871,8 +876,8 @@ const char ** jack_port_get_all_connections (const jack_client_t *client, const jack_port_t *port) JACK_OPTIONAL_WEAK_EXPORT; /** - * \bold THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN - * NEW JACK CLIENTS + * THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN + * NEW JACK CLIENTS * * Modify a port's short name. May be called at any time. If the * resulting full name (including the @a "client_name:" prefix) is @@ -899,7 +904,7 @@ int jack_port_rename (jack_client_t* client, jack_port_t *port, const char *port * If the alias is longer than jack_port_name_size(), it will be truncated. * * After a successful call, and until JACK exits or - * @function jack_port_unset_alias() is called, @alias may be + * jack_port_unset_alias() is called, @a alias may be * used as a alternate name for the port. * * Ports can have up to two aliases - if both are already @@ -920,7 +925,7 @@ int jack_port_set_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEA int jack_port_unset_alias (jack_port_t *port, const char *alias) JACK_OPTIONAL_WEAK_EXPORT; /** - * Get any aliases known for @port. + * Get any aliases known for @a port. * * @return the number of aliases discovered for the port */ @@ -1251,6 +1256,7 @@ int jack_recompute_total_latency (jack_client_t*, jack_port_t* port) JACK_OPTION */ /** + * @param client pointer to JACK client structure. * @param port_name_pattern A regular expression used to select * ports by name. If NULL or of zero length, no selection based * on name will be carried out. diff --git a/common/jack/metadata.h b/common/jack/metadata.h index 891dbd62..3485a844 100644 --- a/common/jack/metadata.h +++ b/common/jack/metadata.h @@ -128,7 +128,7 @@ typedef struct { * Free a description. * * @param desc a jack_description_t whose associated memory will all be released - * @param free_description_itself if non-zero, then @param desc will also be passed to free() + * @param free_description_itself if non-zero, then @a desc will also be passed to free() */ void jack_free_description (jack_description_t* desc, int free_description_itself); @@ -212,12 +212,12 @@ typedef void (*JackPropertyChangeCallback)(jack_uuid_t subject, void* arg); /** - * Arrange for @p client to call @p callback whenever a property is created, + * Arrange for @a client to call @a callback whenever a property is created, * changed or deleted. * * @param client the JACK client making the request * @param callback the function to be invoked when a property change occurs - * @param arg the argument to be passed to @param callback when it is invoked + * @param arg the argument to be passed to @a callback when it is invoked * * @return 0 success, -1 otherwise. */ diff --git a/common/jack/midiport.h b/common/jack/midiport.h index a6dad98c..5947e779 100644 --- a/common/jack/midiport.h +++ b/common/jack/midiport.h @@ -17,6 +17,10 @@ */ +/** + * @file jack/midiport.h + * @brief Read and write MIDI data + */ #ifndef __JACK_MIDIPORT_H #define __JACK_MIDIPORT_H diff --git a/common/jack/ringbuffer.h b/common/jack/ringbuffer.h index 70985720..fe6f9e22 100644 --- a/common/jack/ringbuffer.h +++ b/common/jack/ringbuffer.h @@ -28,7 +28,8 @@ extern "C" #include -/** @file ringbuffer.h +/** @file jack/ringbuffer.h + * @brief lock-free ringbuffer * * A set of library functions to make lock-free ringbuffers available * to JACK clients. The `capture_client.c' (in the example_clients diff --git a/common/jack/session.h b/common/jack/session.h index f0bfbcbc..84c1fefe 100644 --- a/common/jack/session.h +++ b/common/jack/session.h @@ -18,6 +18,11 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ +/** + * @file jack/session.h + * @brief The @b deprecated jack-session API + */ + #ifndef __jack_session_h__ #define __jack_session_h__ diff --git a/common/jack/statistics.h b/common/jack/statistics.h index 28c270d0..aafbf549 100644 --- a/common/jack/statistics.h +++ b/common/jack/statistics.h @@ -18,6 +18,11 @@ * */ +/** + * @file jack/statistics.h + * @brief monitor the performance of a running JACK server + */ + #ifndef __statistics_h__ #define __statistics_h__ @@ -38,7 +43,7 @@ float jack_get_max_delayed_usecs (jack_client_t *client); /** * @return the delay in microseconds due to the most recent XRUN * occurrence. This probably only makes sense when called from a @ref - * JackXRunCallback defined using jack_set_xrun_callback(). + * ::JackXRunCallback defined using jack_set_xrun_callback(). */ float jack_get_xrun_delayed_usecs (jack_client_t *client); diff --git a/common/jack/thread.h b/common/jack/thread.h index 6537afdc..618e4b30 100644 --- a/common/jack/thread.h +++ b/common/jack/thread.h @@ -32,7 +32,8 @@ extern "C" * with mlockall() on many systems */ #define THREAD_STACK 524288 -/** @file thread.h +/** @file jack/thread.h + * @brief Custom JACK client threads * * Library functions to standardize thread creation for JACK and its * clients. These interfaces hide some system variations in the @@ -107,6 +108,7 @@ int jack_drop_real_time_scheduling (jack_native_thread_t thread) JACK_OPTIONAL_W /** * Stop the thread, waiting for the thread handler to terminate. * + * @param client the JACK client. * @param thread POSIX thread ID. * * @returns 0, if successful; otherwise an error number. @@ -116,6 +118,7 @@ int jack_client_stop_thread(jack_client_t* client, jack_native_thread_t thread) /** * Kill the thread. * + * @param client the JACK client. * @param thread POSIX thread ID. * * @returns 0, if successful; otherwise an error number. diff --git a/common/jack/transport.h b/common/jack/transport.h index 4a39e66c..e5efb7cd 100644 --- a/common/jack/transport.h +++ b/common/jack/transport.h @@ -18,6 +18,11 @@ */ +/** + * @file jack/transport.h + * @brief JACK Transport API + */ + #ifndef __jack_transport_h__ #define __jack_transport_h__ diff --git a/common/jack/types.h b/common/jack/types.h index 1a1ea069..0bb86e6f 100644 --- a/common/jack/types.h +++ b/common/jack/types.h @@ -18,6 +18,11 @@ */ +/** + * @file jack/types.h + * @brief The main JACK data types + */ + #ifndef __jack_types_h__ #define __jack_types_h__ @@ -371,7 +376,7 @@ typedef int (*JackSampleRateCallback)(jack_nframes_t nframes, void *arg); * @param register non-zero if the port is being registered, * zero if the port is being unregistered */ -typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int /* register */, void *arg); +typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int register, void *arg); /** * Prototype for the client supplied function that is called @@ -382,7 +387,7 @@ typedef void (*JackPortRegistrationCallback)(jack_port_id_t port, int /* registe * zero if the client is being unregistered * @param arg pointer to a client supplied structure */ -typedef void (*JackClientRegistrationCallback)(const char* name, int /* register */, void *arg); +typedef void (*JackClientRegistrationCallback)(const char* name, int register, void *arg); /** * Prototype for the client supplied function that is called diff --git a/doc/mainpage.dox b/doc/mainpage.dox index 5133f9d8..f5caf41b 100644 --- a/doc/mainpage.dox +++ b/doc/mainpage.dox @@ -121,8 +121,6 @@ The full API is described in: creation for JACK and its clients. - @ref midiport.h "" functions to handle reading and writing of MIDI data to a port - - @ref session.h "" functions that form the JACK - session API - @ref control.h "" the API for starting and controlling a JACK server - @ref metadata.h "" the API for managing metadata