Fix doxygen issues in jack API headers

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
  */

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__
 

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
+* <b> THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
-*  NEW JACK CLIENTS
+*  NEW JACK CLIENTS</b>
 *
 * @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
+ * <b> THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
- *  NEW JACK CLIENTS.
+ *  NEW JACK CLIENTS. </b>
  *
  * @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
+ * <b>THIS FUNCTION IS DEPRECATED AND SHOULD NOT BE USED IN
- *  NEW JACK CLIENTS
+ *  NEW JACK CLIENTS</b>
  *
  * 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.

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.
  */

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

common/jack/ringbuffer.h

@@ -28,7 +28,8 @@ extern "C"
 
 #include <sys/types.h>
 
-/** @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

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__
 

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);
 

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.

common/jack/transport.h

@@ -18,6 +18,11 @@
 
 */
 
+/**
+ * @file   jack/transport.h
+ * @brief  JACK Transport API
+ */
+
 #ifndef __jack_transport_h__
 #define __jack_transport_h__
 

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

doc/mainpage.dox

@@ -121,8 +121,6 @@ The full API is described in:
   creation for JACK and its clients.
   - @ref midiport.h "<jack/midiport.h>" functions to handle reading
   and writing of MIDI data to a port
-  - @ref session.h "<jack/session.h>" functions that form the JACK
-  session API
   - @ref control.h "<jack/control.h>" the API for starting and
 controlling a JACK server
   - @ref metadata.h "<jack/metadata.h>" the API for managing metadata