More documentation

diff --git a/include/control.h b/include/control.h
index e3b311a..abb8147 100644 (file)
--- a/include/control.h
+++ b/include/control.h
@@ -241,19 +241,40 @@ void snd_ctl_elem_list_free_space(snd_ctl_elem_list_t *obj);
  *  Highlevel API for controls
  */
 
+/** HCTL element handle */
 typedef struct _snd_hctl_elem snd_hctl_elem_t;
 
+/** HCTL handle */
 typedef struct _snd_hctl snd_hctl_t;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * \brief Compare function for sorting HCTL elements
+ * \param e1 First element
+ * \param e2 Second element
+ * \return -1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2
+ */
 typedef int (*snd_hctl_compare_t)(const snd_hctl_elem_t *e1,
                                  const snd_hctl_elem_t *e2);
+/** 
+ * \brief HCTL callback function
+ * \param hctl HCTL handle
+ * \param mask event mask
+ * \param elem related HCTL element (if any)
+ * \return 0 on success otherwise a negative error code
+ */
 typedef int (*snd_hctl_callback_t)(snd_hctl_t *hctl,
                                   unsigned int mask,
                                   snd_hctl_elem_t *elem);
+/** 
+ * \brief HCTL element callback function
+ * \param elem HCTL element
+ * \param mask event mask
+ * \return 0 on success otherwise a negative error code
+ */
 typedef int (*snd_hctl_elem_callback_t)(snd_hctl_elem_t *elem,
                                        unsigned int mask);
 

diff --git a/include/control_m4.h b/include/control_m4.h
index 1023bc2..9804a7c 100644 (file)
--- a/include/control_m4.h
+++ b/include/control_m4.h
@@ -3,6 +3,10 @@ extern "C" {
 #endif
 
 size_t snd_ctl_elem_id_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_elem_id_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_elem_id_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_id_t *) alloca(snd_ctl_elem_id_sizeof()); memset(*ptr, 0, snd_ctl_elem_id_sizeof()); } while (0)
 int snd_ctl_elem_id_malloc(snd_ctl_elem_id_t **ptr);
 void snd_ctl_elem_id_free(snd_ctl_elem_id_t *obj);
@@ -33,6 +37,10 @@ void snd_ctl_elem_id_set_name(snd_ctl_elem_id_t *obj, const char *val);
 void snd_ctl_elem_id_set_index(snd_ctl_elem_id_t *obj, unsigned int val);
 
 size_t snd_ctl_card_info_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_card_info_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_card_info_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_card_info_t *) alloca(snd_ctl_card_info_sizeof()); memset(*ptr, 0, snd_ctl_card_info_sizeof()); } while (0)
 int snd_ctl_card_info_malloc(snd_ctl_card_info_t **ptr);
 void snd_ctl_card_info_free(snd_ctl_card_info_t *obj);
@@ -55,6 +63,10 @@ const char *snd_ctl_card_info_get_mixerid(const snd_ctl_card_info_t *obj);
 const char *snd_ctl_card_info_get_mixername(const snd_ctl_card_info_t *obj);
 
 size_t snd_ctl_event_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_event_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_event_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_event_t *) alloca(snd_ctl_event_sizeof()); memset(*ptr, 0, snd_ctl_event_sizeof()); } while (0)
 int snd_ctl_event_malloc(snd_ctl_event_t **ptr);
 void snd_ctl_event_free(snd_ctl_event_t *obj);
@@ -63,6 +75,10 @@ void snd_ctl_event_copy(snd_ctl_event_t *dst, const snd_ctl_event_t *src);
 snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj);
 
 size_t snd_ctl_elem_list_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_elem_list_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_elem_list_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_list_t *) alloca(snd_ctl_elem_list_sizeof()); memset(*ptr, 0, snd_ctl_elem_list_sizeof()); } while (0)
 int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr);
 void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj);
@@ -89,6 +105,10 @@ const char *snd_ctl_elem_list_get_name(const snd_ctl_elem_list_t *obj, unsigned
 unsigned int snd_ctl_elem_list_get_index(const snd_ctl_elem_list_t *obj, unsigned int idx);
 
 size_t snd_ctl_elem_info_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_elem_info_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_elem_info_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_info_t *) alloca(snd_ctl_elem_info_sizeof()); memset(*ptr, 0, snd_ctl_elem_info_sizeof()); } while (0)
 int snd_ctl_elem_info_malloc(snd_ctl_elem_info_t **ptr);
 void snd_ctl_elem_info_free(snd_ctl_elem_info_t *obj);
@@ -151,6 +171,10 @@ void snd_ctl_elem_info_set_name(snd_ctl_elem_info_t *obj, const char *val);
 void snd_ctl_elem_info_set_index(snd_ctl_elem_info_t *obj, unsigned int val);
 
 size_t snd_ctl_elem_value_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_ctl_elem_value_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_value_t *) alloca(snd_ctl_elem_value_sizeof()); memset(*ptr, 0, snd_ctl_elem_value_sizeof()); } while (0)
 int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr);
 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj);

diff --git a/include/error.h b/include/error.h
index d13046d..0a03ac8 100644 (file)
--- a/include/error.h
+++ b/include/error.h
@@ -11,6 +11,15 @@ extern "C" {
 
 const char *snd_strerror(int errnum);
 
+/**
+ * \brief Error handler
+ * \param file File name
+ * \param line Line number
+ * \param function Function name
+ * \param err errno value (or 0 if not relevant)
+ * \param fmt printf(3) format
+ * \param ... printf(3) arguments
+ */
 typedef void (snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((weak, format (printf, 5, 6))) */;
 extern snd_lib_error_handler_t *snd_lib_error;
 extern int snd_lib_error_set_handler(snd_lib_error_handler_t *handler);

diff --git a/include/pcm.h b/include/pcm.h
index 04d1547..f339d92 100644 (file)
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -410,19 +410,33 @@ ssize_t snd_pcm_samples_to_bytes(snd_pcm_t *pcm, int samples);
 
 /** #SND_PCM_TYPE_METER scope functions */
 typedef struct _snd_pcm_scope_ops {
-       /** Enable and prepare it using current params */
+       /** \brief Enable and prepare it using current params
+        * \param scope scope handle
+        */
        int (*enable)(snd_pcm_scope_t *scope);
-       /** Disable */
+       /** \brief Disable
+        * \param scope scope handle
+        */
        void (*disable)(snd_pcm_scope_t *scope);
-       /** PCM has been started */
+       /** \brief PCM has been started
+        * \param scope scope handle
+        */
        void (*start)(snd_pcm_scope_t *scope);
-       /** PCM has been stopped */
+       /** \brief PCM has been stopped
+        * \param scope scope handle
+        */
        void (*stop)(snd_pcm_scope_t *scope);
-       /** New frames are present */
+       /** \brief New frames are present
+        * \param scope scope handle
+        */
        void (*update)(snd_pcm_scope_t *scope);
-       /** Reset status */
+       /** \brief Reset status
+        * \param scope scope handle
+        */
        void (*reset)(snd_pcm_scope_t *scope);
-       /** PCM is closing */
+       /** \brief PCM is closing
+        * \param scope scope handle
+        */
        void (*close)(snd_pcm_scope_t *scope);
 } snd_pcm_scope_ops_t;
 

diff --git a/include/rawmidi.h b/include/rawmidi.h
index d7296e7..7859dca 100644 (file)
--- a/include/rawmidi.h
+++ b/include/rawmidi.h
@@ -5,40 +5,39 @@
  *                                                                          *
  ****************************************************************************/
 
+/** RawMidi information container */
 typedef struct _snd_rawmidi_info snd_rawmidi_info_t;
+/** RawMidi settings container */
 typedef struct _snd_rawmidi_params snd_rawmidi_params_t;
+/** RawMidi status container */
 typedef struct _snd_rawmidi_status snd_rawmidi_status_t;
 
-#ifdef SND_ENUM_TYPECHECK
-typedef struct __snd_rawmidi_stream *snd_rawmidi_stream_t;
-#else
-typedef enum sndrv_rawmidi_stream snd_rawmidi_stream_t;
-#endif
-
-#define SND_RAWMIDI_STREAM_OUTPUT ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_OUTPUT)
-#define SND_RAWMIDI_STREAM_INPUT ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_INPUT)
-#define SND_RAWMIDI_STREAM_LAST ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_LAST)
+/** RawMidi stream (direction) */
+typedef enum _snd_rawmidi_stream {
+       /** Output stream */
+       SND_RAWMIDI_STREAM_OUTPUT = SNDRV_RAWMIDI_STREAM_OUTPUT,
+       /** Input stream */
+       SND_RAWMIDI_STREAM_INPUT = SNDRV_RAWMIDI_STREAM_INPUT,
+       SND_RAWMIDI_STREAM_LAST = SNDRV_RAWMIDI_STREAM_LAST,
+} snd_rawmidi_stream_t;
 
+/** Append \hideinitializer */
 #define SND_RAWMIDI_APPEND     1
+/** Non blocking mode \hideinitializer */
 #define SND_RAWMIDI_NONBLOCK   2
 
+/** RawMidi handle */
 typedef struct _snd_rawmidi snd_rawmidi_t;
 
-enum _snd_rawmidi_type {
+/** RawMidi type */
+typedef enum _snd_rawmidi_type {
+       /** Kernel level RawMidi */
        SND_RAWMIDI_TYPE_HW,
+       /** Shared memory client RawMidi (not yet implemented) */
        SND_RAWMIDI_TYPE_SHM,
+       /** INET client RawMidi (not yet implemented) */
        SND_RAWMIDI_TYPE_INET,
-};
-
-#ifdef SND_ENUM_TYPECHECK
-typedef struct __snd_rawmidi_type *snd_rawmidi_type_t;
-#else
-typedef enum _snd_rawmidi_type snd_rawmidi_type_t;
-#endif
-
-#define        SND_RAWMIDI_TYPE_HW ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_HW)
-#define        SND_RAWMIDI_TYPE_SHM ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_SHM)
-#define        SND_RAWMIDI_TYPE_INET ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_INET)
+} snd_rawmidi_type_t;
 
 #ifdef __cplusplus
 extern "C" {
@@ -51,6 +50,10 @@ int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rmidi);
 int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rmidi, struct pollfd *pfds, unsigned int space);
 int snd_rawmidi_nonblock(snd_rawmidi_t *rmidi, int nonblock);
 size_t snd_rawmidi_info_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_rawmidi_info_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_rawmidi_info_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_info_t *) alloca(snd_rawmidi_info_sizeof()); memset(*ptr, 0, snd_rawmidi_info_sizeof()); } while (0)
 int snd_rawmidi_info_malloc(snd_rawmidi_info_t **ptr);
 void snd_rawmidi_info_free(snd_rawmidi_info_t *obj);
@@ -70,6 +73,10 @@ void snd_rawmidi_info_set_subdevice(snd_rawmidi_info_t *obj, unsigned int val);
 void snd_rawmidi_info_set_stream(snd_rawmidi_info_t *obj, snd_rawmidi_stream_t val);
 int snd_rawmidi_info(snd_rawmidi_t *rmidi, snd_rawmidi_info_t * info);
 size_t snd_rawmidi_params_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_rawmidi_params_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_rawmidi_params_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_params_t *) alloca(snd_rawmidi_params_sizeof()); memset(*ptr, 0, snd_rawmidi_params_sizeof()); } while (0)
 int snd_rawmidi_params_malloc(snd_rawmidi_params_t **ptr);
 void snd_rawmidi_params_free(snd_rawmidi_params_t *obj);
@@ -83,6 +90,10 @@ int snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t *params)
 int snd_rawmidi_params(snd_rawmidi_t *rmidi, snd_rawmidi_params_t * params);
 int snd_rawmidi_params_current(snd_rawmidi_t *rmidi, snd_rawmidi_params_t *params);
 size_t snd_rawmidi_status_sizeof();
+/** \hideinitializer
+ * \brief allocate an invalid #snd_rawmidi_status_t using standard alloca
+ * \param ptr returned pointer
+ */
 #define snd_rawmidi_status_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_status_t *) alloca(snd_rawmidi_status_sizeof()); memset(*ptr, 0, snd_rawmidi_status_sizeof()); } while (0)
 int snd_rawmidi_status_malloc(snd_rawmidi_status_t **ptr);
 void snd_rawmidi_status_free(snd_rawmidi_status_t *obj);