From: Jaroslav Kysela <perex@perex.cz>
Date: Fri, 7 Nov 2025 20:30:32 +0000 (+0100)
Subject: doxygen: fix warnings and add missing ALSA_LIBRARY_BUILD define
X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=2b6dedeb74acd5e8adbef5080d62c66507a6af3d;p=alsa-lib.git

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 bcc3a33e..c94f961e 100644
--- 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 5e158b35..18d5c575 100644
--- 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 2a6d8296..827396c5 100644
--- 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 e670e6c1..e96cc068 100644
--- 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 faeff8e0..ce3582bf 100644
--- 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 ae706133..40fe2ca8 100644
--- 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 174aa899..cadc60b5 100644
--- 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 f9c6026c..329d1faa 100644
--- 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 74020511..f8c84875 100644
--- 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 9049783c..a8239c4c 100644
--- 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 c41c5c1f..4777123f 100644
--- 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 fa95590d..35be5e59 100644
--- 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 554e706f..8031e1ed 100644
--- 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 686f69dd..ece42cca 100644
--- 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 268578b8..c4054c9f 100644
--- 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 1df03bad..c93428f8 100644
--- 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 7a41331a..42e1942e 100644
--- 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 d19ab557..54144e70 100644
--- 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 1f4de78e..e6ed6abb 100644
--- 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 e4dc9085..efd838d3 100644
--- 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)
 {