Adjust parameters of doxygen documentation generation

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

@@ -188,7 +188,7 @@ ALIASES                =
 # For instance, some of the names that are used will be different. The list
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
 # sources only. Doxygen will then generate output that is more tailored for
@@ -274,22 +274,6 @@ SUBGROUPING            = YES
 
 TYPEDEF_HIDES_STRUCT   = NO
 
-# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to
-# determine which symbols to keep in memory and which to flush to disk.
-# When the cache is full, less often used symbols will be written to disk.
-# For small to medium size projects (<1000 input files) the default value is
-# probably good enough. For larger projects a too small cache size can cause
-# doxygen to be busy swapping symbols to and from disk most of the time
-# causing a significant performance penality.
-# If the system has enough physical memory increasing the cache will improve the
-# performance by keeping more symbols in memory. Note that the value works on
-# a logarithmic scale so increasing the size by one will rougly double the
-# memory usage. The cache size is given by this formula:
-# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0,
-# corresponding to a cache size of 2^16 = 65536 symbols
-
-SYMBOL_CACHE_SIZE      = 0
-
 #---------------------------------------------------------------------------
 # Build related configuration options
 #---------------------------------------------------------------------------
@@ -338,14 +322,14 @@ EXTRACT_ANON_NSPACES   = NO
 # various overviews, but no documentation section is generated.
 # This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_MEMBERS     = YES
 
 # If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all
 # undocumented classes that are normally visible in the class hierarchy.
 # If set to NO (the default) these classes will be included in the various
 # overviews. This option has no effect if EXTRACT_ALL is enabled.
 
-HIDE_UNDOC_CLASSES     = NO
+HIDE_UNDOC_CLASSES     = YES
 
 # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
 # friend (class|struct|union) declarations.
@@ -478,12 +462,6 @@ MAX_INITIALIZER_LINES  = 30
 
 SHOW_USED_FILES        = YES
 
-# If the sources in your project are distributed over multiple directories
-# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
-# in the documentation. The default is NO.
-
-SHOW_DIRECTORIES       = NO
-
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page.
 # This will remove the Files entry from the Quick Index and from the
 # Folder Tree View (if specified). The default is YES.
@@ -656,7 +634,7 @@ EXAMPLE_RECURSIVE      = NO
 # directories that contain image that are included in the documentation (see
 # the \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = @SRCDIR@/doc/
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
@@ -695,7 +673,7 @@ FILTER_SOURCE_FILES    = NO
 # Note: To get rid of all source code in the generated output, make sure also
 # VERBATIM_HEADERS is set to NO.
 
-SOURCE_BROWSER         = YES
+SOURCE_BROWSER         = NO
 
 # Setting the INLINE_SOURCES tag to YES will include the body
 # of functions and classes directly in the documentation.
@@ -726,7 +704,7 @@ REFERENCES_RELATION    = NO
 # link to the source code.
 # Otherwise they will link to the documentation.
 
-REFERENCES_LINK_SOURCE = YES
+REFERENCES_LINK_SOURCE = NO
 
 # If the USE_HTAGS tag is set to YES then the references to source code
 # will point to the HTML generated by the htags(1) tool instead of doxygen
@@ -740,7 +718,7 @@ USE_HTAGS              = NO
 # will generate a verbatim copy of the header file for each class for
 # which an include is specified. Set to NO to disable this.
 
-VERBATIM_HEADERS       = YES
+VERBATIM_HEADERS       = NO
 
 #---------------------------------------------------------------------------
 # configuration options related to the alphabetical class index
@@ -752,12 +730,6 @@ VERBATIM_HEADERS       = YES
 
 ALPHABETICAL_INDEX     = NO
 
-# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then
-# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns
-# in which this list will be split (can be a number in the range [1..20])
-
-COLS_IN_ALPHA_INDEX    = 5
-
 # In case all classes in a project start with a common prefix, all
 # classes will be put under the same header in the alphabetical index.
 # The IGNORE_PREFIX tag can be used to specify one or more prefixes that
@@ -820,12 +792,6 @@ HTML_EXTRA_FILES = ../doc/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js
 
 HTML_TIMESTAMP         = NO
 
-# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes,
-# files or namespaces will be aligned in HTML using tables. If set to
-# NO a bullet list will be used.
-
-HTML_ALIGN_MEMBERS     = YES
-
 # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML
 # documentation will contain sections that can be hidden and shown after the
 # page has loaded. For this to work a browser that supports
@@ -990,11 +956,6 @@ ENUM_VALUES_PER_LINE   = 4
 
 GENERATE_TREEVIEW      = NO
 
-# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories,
-# and Class Hierarchy pages using a tree view instead of an ordered list.
-
-USE_INLINE_TREES       = NO
-
 # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
 # used to set the initial width (in pixels) of the frame in which the tree
 # is shown.
@@ -1058,10 +1019,10 @@ MAKEINDEX_CMD_NAME     = makeindex
 COMPACT_LATEX          = NO
 
 # The PAPER_TYPE tag can be used to set the paper type that is used
-# by the printer. Possible values are: a4, a4wide, letter, legal and
+# by the printer. Possible values are: a4, letter, legal and
 # executive. If left blank a4wide will be used.
 
-PAPER_TYPE             = a4wide
+PAPER_TYPE             = a4
 
 # The EXTRA_PACKAGES tag can be to specify one or more names of LaTeX
 # packages that should be included in the LaTeX output.
@@ -1101,10 +1062,6 @@ LATEX_BATCHMODE        = NO
 
 LATEX_HIDE_INDICES     = NO
 
-# If LATEX_SOURCE_CODE is set to YES then doxygen will include source code with syntax highlighting in the LaTeX output. Note that which sources are shown also depends on other settings such as SOURCE_BROWSER.
-
-LATEX_SOURCE_CODE      = NO
-
 #---------------------------------------------------------------------------
 # configuration options related to the RTF output
 #---------------------------------------------------------------------------
@@ -1191,18 +1148,6 @@ GENERATE_XML           = NO
 
 XML_OUTPUT             = xml
 
-# The XML_SCHEMA tag can be used to specify an XML schema,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_SCHEMA             =
-
-# The XML_DTD tag can be used to specify an XML DTD,
-# which can be used by a validating XML parser to check the
-# syntax of the XML files.
-
-XML_DTD                =
-
 # If the XML_PROGRAMLISTING tag is set to YES Doxygen will
 # dump the program listings (including syntax highlighting
 # and cross-referencing information) to the XML output. Note that
@@ -1363,33 +1308,10 @@ ALLEXTERNALS           = NO
 
 EXTERNAL_GROUPS        = YES
 
-# The PERL_PATH should be the absolute path and name of the perl script
-# interpreter (i.e. the result of `which perl').
-
-PERL_PATH              =
-
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
 
-# If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will
-# generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base
-# or super classes. Setting the tag to NO turns the diagrams off. Note that
-# this option is superseded by the HAVE_DOT option below. This is only a
-# fallback. It is recommended to install and use dot, since it yields more
-# powerful graphs.
-
-CLASS_DIAGRAMS         = YES
-
-# You can define message sequence charts within doxygen comments using the \msc
-# command. Doxygen will then run the mscgen tool (see
-# http://www.mcternan.me.uk/mscgen/) to produce the chart and insert it in the
-# documentation. The MSCGEN_PATH tag allows you to specify the directory where
-# the mscgen tool resides. If left empty the tool is assumed to be found in the
-# default search path.
-
-MSCGEN_PATH            =
-
 # If set to YES, the inheritance and collaboration graphs will hide
 # inheritance and usage relations if the target is undocumented
 # or is not a class.
@@ -1403,22 +1325,6 @@ HIDE_UNDOC_RELATIONS   = YES
 
 HAVE_DOT               = NO
 
-# By default doxygen will write a font called FreeSans.ttf to the output
-# directory and reference it in all dot files that doxygen generates. This
-# font does not include all possible unicode characters however, so when you need
-# these (or just want a differently looking font) you can specify the font name
-# using DOT_FONTNAME. You need need to make sure dot is able to find the font,
-# which can be done by putting it in a standard location or by setting the
-# DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory
-# containing the font.
-
-DOT_FONTNAME           = FreeSans
-
-# The DOT_FONTSIZE tag can be used to set the size of the font of dot graphs.
-# The default size is 10pt.
-
-DOT_FONTSIZE           = 10
-
 # By default doxygen will tell dot to use the output directory to look for the
 # FreeSans.ttf font (which doxygen will put there itself). If you specify a
 # different font using DOT_FONTNAME you can set the path where dot
@@ -1535,14 +1441,6 @@ DOT_GRAPH_MAX_NODES    = 50
 
 MAX_DOT_GRAPH_DEPTH    = 0
 
-# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent
-# background. This is disabled by default, because dot on Windows does not
-# seem to support this out of the box. Warning: Depending on the platform used,
-# enabling this option may lead to badly anti-aliased labels on the edges of
-# a graph (i.e. they become hard to read).
-
-DOT_TRANSPARENT        = NO
-
 # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output
 # files in one run (i.e. multiple -o and -T options on the command line). This
 # makes dot run faster, but since only newer versions of dot (>1.8.10)

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