doxygen: fix warnings and add missing ALSA_LIBRARY_BUILD define

BugLink: https://github.com/alsa-project/alsa-lib/pull/480
Signed-off-by: Jaroslav Kysela <perex@perex.cz>

diff --git a/doc/doxygen.cfg.in b/doc/doxygen.cfg.in
index bcc3a33e2429016b1ba63417572bb135b763be7f..c94f961ef8f4e2317d047e5220b63066ce616aff 100644 (file)
--- a/doc/doxygen.cfg.in
+++ b/doc/doxygen.cfg.in
@@ -127,7 +127,7 @@ INHERIT_DOCS         = YES
 ENABLED_SECTIONS = ""
 MACRO_EXPANSION  = YES
 EXPAND_ONLY_PREDEF = YES
-PREDEFINED      = DOXYGEN PIC "DOC_HIDDEN" \
+PREDEFINED      = DOXYGEN PIC "DOC_HIDDEN" "ALSA_LIBRARY_BUILD" \
                   "ATTRIBUTE_UNUSED=" \
                   ALSA_PCM_NEW_HW_PARAMS_API \
                   _POSIX_C_SOURCE \
@@ -140,5 +140,3 @@ TYPEDEF_HIDES_STRUCT = YES  # needed in doxygen >= 1.5.4
 
 #INPUT_FILTER   = inputfilter
 #FILTER_SOURCE_FILES = YES
-
-HTML_TIMESTAMP = NO

diff --git a/include/asoundef.h b/include/asoundef.h
index 5e158b352ed5bade70bd8eec9bde12e5beb8cc36..18d5c57536ba660ccfb5c0282a7e44d77574421e 100644 (file)
--- a/include/asoundef.h
+++ b/include/asoundef.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_ASOUNDEF_H
-#define __ALSA_ASOUNDEF_H
+#define __ALSA_ASOUNDEF_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/conf.h b/include/conf.h
index 2a6d8296aee8e2f7af59d0400d0b3faae1f77244..827396c5dc8192ce4d8c84d7c483935270a82df8 100644 (file)
--- a/include/conf.h
+++ b/include/conf.h
@@ -31,7 +31,7 @@
 #endif
 
 #ifndef __ALSA_CONF_H
-#define __ALSA_CONF_H
+#define __ALSA_CONF_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/control.h b/include/control.h
index e670e6c1b4c2a1ed8aa1a5290d782c2f0eadd5b5..e96cc068cd9fd90eaebf4f730db3802bcf169a96 100644 (file)
--- a/include/control.h
+++ b/include/control.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_CONTROL_H
-#define __ALSA_CONTROL_H
+#define __ALSA_CONTROL_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/error.h b/include/error.h
index faeff8e0994a0fd0d6d5a7880aea190647c0f965..ce3582bff13db56005abe191dc35c2bc87c2c06b 100644 (file)
--- a/include/error.h
+++ b/include/error.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_ERROR_H
-#define __ALSA_ERROR_H
+#define __ALSA_ERROR_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {
@@ -54,7 +54,7 @@ const char *snd_strerror(int errnum);
 #define SND_LOG_INFO           3       /**< info priority level */
 #define SND_LOG_DEBUG          4       /**< debug priority level */
 #define SND_LOG_TRACE          5       /**< trace priority level */
-#define SND_LOG_LAST           SND_LOG_TRACE
+#define SND_LOG_LAST           SND_LOG_TRACE /**< last known value for priority level */
 
 #define SND_ILOG_CORE           1      /**< core library code */
 #define SND_ILOG_CONFIG                2       /**< configuration parsing and operations */
@@ -68,7 +68,7 @@ const char *snd_strerror(int errnum);
 #define SND_ILOG_UCM           10      /**< UCM API */
 #define SND_ILOG_TOPOLOGY      11      /**< topology API */
 #define SND_ILOG_ASERVER       12      /**< aserver */
-#define SND_ILOG_LAST          SND_ILOG_ASERVER
+#define SND_ILOG_LAST          SND_ILOG_ASERVER /**< last known value for interface */
 
 /**
  * \brief Log handler callback.

diff --git a/include/global.h b/include/global.h
index ae706133722a6575ae49179ae8681499234b46e9..40fe2ca855694bb98c9d9814c48ef5bd15be0c6c 100644 (file)
--- a/include/global.h
+++ b/include/global.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_GLOBAL_H_
-#define __ALSA_GLOBAL_H_
+#define __ALSA_GLOBAL_H_ /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/hwdep.h b/include/hwdep.h
index 174aa899fcd2119400d4ec5f0a3996a744eac646..cadc60b5c3bf1cab2c80513e82b8e49241eab024 100644 (file)
--- a/include/hwdep.h
+++ b/include/hwdep.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_HWDEP_H
-#define __ALSA_HWDEP_H
+#define __ALSA_HWDEP_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/mixer.h b/include/mixer.h
index f9c6026c940da5a9aff69073453f0e2e18e926da..329d1faa467b4f6dd1a106f34ac4853a4031ec1a 100644 (file)
--- a/include/mixer.h
+++ b/include/mixer.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_MIXER_H
-#define __ALSA_MIXER_H
+#define __ALSA_MIXER_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/pcm.h b/include/pcm.h
index 740205110550b14ac299420be722493ee86637c4..f8c84875ca1c46f0519d42159b606ca43ccf4d8a 100644 (file)
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -33,7 +33,7 @@
 #endif
 
 #ifndef __ALSA_PCM_H
-#define __ALSA_PCM_H
+#define __ALSA_PCM_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/pcm_extplug.h b/include/pcm_extplug.h
index 9049783c179ffba7b186e97d125d225e3e2a0cb9..a8239c4c6f4e8c45cf8b0aa38a3b004e16dc99aa 100644 (file)
--- a/include/pcm_extplug.h
+++ b/include/pcm_extplug.h
@@ -34,7 +34,7 @@
 #endif
 
 #ifndef __ALSA_PCM_EXTPLUG_H
-#define __ALSA_PCM_EXTPLUG_H
+#define __ALSA_PCM_EXTPLUG_H /**< header include loop protection */
 
 /**
  * \defgroup PCM_ExtPlug External Filter plugin SDK

diff --git a/include/pcm_ioplug.h b/include/pcm_ioplug.h
index c41c5c1f3ee569310aaa8efc8dfd2e5d5dc47bc4..4777123f4a2bd44e1bf9235248f9fd13d08b2f2c 100644 (file)
--- a/include/pcm_ioplug.h
+++ b/include/pcm_ioplug.h
@@ -34,7 +34,7 @@
 #endif
 
 #ifndef __ALSA_PCM_IOPLUG_H
-#define __ALSA_PCM_IOPLUG_H
+#define __ALSA_PCM_IOPLUG_H /**< header include loop protection */
 
 /**
  * \defgroup PCM_IOPlug External I/O plugin SDK

diff --git a/include/pcm_plugin.h b/include/pcm_plugin.h
index fa95590d6909f98032b84bae2c90c6412a4eac5f..35be5e59754c54e66c6548effd72e8094e115453 100644 (file)
--- a/include/pcm_plugin.h
+++ b/include/pcm_plugin.h
@@ -202,10 +202,34 @@ int _snd_pcm_ladspa_open(snd_pcm_t **pcmp, const char *name,
 /*
  *  Jack plugin
  */
+
+/**
+ * \brief Creates a new Jack PCM
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param playback_conf Playback configuration
+ * \param capture_conf Capture configuration
+ * \param stream Stream direction
+ * \param mode PCM open mode
+ * \retval zero on success otherwise a negative error code
+ * \warning alsa-lib must be compiled against the JACK library for this plugin to be available
+ */
 int snd_pcm_jack_open(snd_pcm_t **pcmp, const char *name,
                                        snd_config_t *playback_conf,
                                        snd_config_t *capture_conf,
                      snd_pcm_stream_t stream, int mode);
+
+/**
+ * \brief Creates a new Jack PCM (internal)
+ * \param pcmp Returns created PCM handle
+ * \param name Name of PCM
+ * \param root Root configuration node
+ * \param conf Configuration for this PCM
+ * \param stream Stream direction
+ * \param mode PCM open mode
+ * \retval zero on success otherwise a negative error code
+ * \warning alsa-lib must be compiled against the JACK library for this plugin to be available
+ */
 int _snd_pcm_jack_open(snd_pcm_t **pcmp, const char *name,
                       snd_config_t *root, snd_config_t *conf,
                       snd_pcm_stream_t stream, int mode);

diff --git a/include/rawmidi.h b/include/rawmidi.h
index 554e706f0da265aa474be34b063bfe4a24314502..8031e1edc13d974912325cc13b5157cc37a0b95e 100644 (file)
--- a/include/rawmidi.h
+++ b/include/rawmidi.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_RAWMIDI_H
-#define __ALSA_RAWMIDI_H
+#define __ALSA_RAWMIDI_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {
@@ -103,7 +103,7 @@ typedef enum _snd_rawmidi_read_mode {
 #define SND_RAWMIDI_INFO_UMP                   0x00000008      /**< rawmidi is UMP */
 #define SND_RAWMIDI_INFO_STREAM_INACTIVE       0x00000010      /**< the selected substream is inactive */
 #ifndef SNDRV_RAWMIDI_INFO_STREAM_INACTIVE
-#define SNDRV_RAWMIDI_INFO_STREAM_INACTIVE     SND_RAWMIDI_INFO_STREAM_INACTIVE /* only for compatibility */
+#define SNDRV_RAWMIDI_INFO_STREAM_INACTIVE     SND_RAWMIDI_INFO_STREAM_INACTIVE /**< compatibility alias for SND_RAWMIDI_INFO_STREAM_INACTIVE */
 #endif
 
 int snd_rawmidi_open(snd_rawmidi_t **in_rmidi, snd_rawmidi_t **out_rmidi,

diff --git a/include/seq.h b/include/seq.h
index 686f69dde46375ca9c15356e89291b6f92cde1ae..ece42cca9a896ca391cb51f86711479c421738e0 100644 (file)
--- a/include/seq.h
+++ b/include/seq.h
@@ -33,7 +33,7 @@
 #endif
 
 #ifndef __ALSA_SEQ_H
-#define __ALSA_SEQ_H
+#define __ALSA_SEQ_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/seq_event.h b/include/seq_event.h
index 268578b8ac105bf66820562dff37600df5c12eef..c4054c9f31391372bb5f724c2a6a59e3425d9688 100644 (file)
--- a/include/seq_event.h
+++ b/include/seq_event.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_SEQ_EVENT_H
-#define __ALSA_SEQ_EVENT_H
+#define __ALSA_SEQ_EVENT_H /**< header include loop protection */
 
 /**
  *  \defgroup SeqEvents Sequencer Event Definitions

diff --git a/include/seqmid.h b/include/seqmid.h
index 1df03bad2e21464f675ab493fad010109455c388..c93428f8c2921715d2efe035a089224e83d8ac57 100644 (file)
--- a/include/seqmid.h
+++ b/include/seqmid.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_SEQMID_H
-#define __ALSA_SEQMID_H
+#define __ALSA_SEQMID_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/timer.h b/include/timer.h
index 7a41331a3d6f4cc470014910cd02a8214bc2ff60..42e1942e83366dcb0cad42ff70e905d445c53bb7 100644 (file)
--- a/include/timer.h
+++ b/include/timer.h
@@ -32,7 +32,7 @@
 #endif
 
 #ifndef __ALSA_TIMER_H
-#define __ALSA_TIMER_H
+#define __ALSA_TIMER_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/include/ump.h b/include/ump.h
index d19ab5570bfbfcb8f851d3eb0bccb8fb11db7539..54144e70caa3a0b222c75c04e920020eda404685 100644 (file)
--- a/include/ump.h
+++ b/include/ump.h
@@ -13,7 +13,7 @@
 #endif
 
 #ifndef __ALSA_UMP_H
-#define __ALSA_UMP_H
+#define __ALSA_UMP_H /**< header include loop protection */
 
 #ifdef __cplusplus
 extern "C" {

diff --git a/src/error.c b/src/error.c
index 1f4de78e5e9bfa04c5c79068ecae83a8e8512df4..e6ed6abb035e059880da44016c6f06dc020253c2 100644 (file)
--- a/src/error.c
+++ b/src/error.c
@@ -419,7 +419,9 @@ snd_local_error_handler_t snd_lib_error_set_local(snd_local_error_handler_t func
        local_error = func;
        return old;
 }
+#ifndef DOC_HIDDEN
 link_warning(snd_lib_error_set_local, "Warning: snd_lib_error_set_local is deprecated, use snd_lib_log_set_local");
+#endif
 
 /**
  * \brief The default error handler function.
@@ -448,7 +450,9 @@ static void snd_lib_error_default(const char *file, int line, const char *functi
  * For internal use only.
  */
 snd_lib_error_handler_t snd_lib_error = snd_lib_error_default;
+#ifndef DOC_HIDDEN
 link_warning(snd_lib_error, "Warning: snd_lib_error is deprecated, use snd_log interface");
+#endif
 
 /**
  * \brief Sets the error handler.

diff --git a/src/pcm/pcm_hw.c b/src/pcm/pcm_hw.c
index e4dc90859f085547a7de58d79757e41bd00156ba..efd838d33dbb2892d729c065c486b4f17183b26e 100644 (file)
--- a/src/pcm/pcm_hw.c
+++ b/src/pcm/pcm_hw.c
@@ -379,8 +379,10 @@ static int snd_pcm_hw_hw_refine(snd_pcm_t *pcm, snd_pcm_hw_params_t *params)
        return 0;
 }
 
+#ifndef DOC_HIDDEN
 #define hw_param_mask(params,var) \
        &((params)->masks[(var) - SND_PCM_HW_PARAM_FIRST_MASK])
+#endif
 
 static int hw_params_call(snd_pcm_hw_t *pcm_hw, snd_pcm_hw_params_t *params)
 {