More documentation updates.

include/header.h

@@ -1,5 +1,6 @@
 /**
  * \file asoundlib.h
+ * \brief Application interface library for the ALSA driver
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Takashi Iwai <tiwai@suse.de>

src/async.c

@@ -1,5 +1,6 @@
 /**
  * \file async.c
+ * \brief Async notification helpers
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2001
  */

src/conf.c

@@ -1,3 +1,12 @@
+/**
+ * \file conf.c
+ * \brief Configuration helper functions
+ * \author Abramo Bagnara <abramo@alsa-project.org>
+ * \author Jaroslav Kysela <perex@suse.cz>
+ * \date 2000-2001
+ *
+ * Generic stdio-like input interface
+ */
 /*
  *  Configuration helper functions
  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>,
@@ -474,7 +483,7 @@ static int parse_value(snd_config_t **_n, snd_config_t *father, input_t *input,
 		free(s);
 		return 0;
 	}
-	if ((s[0] >= '0' && s[0] <= '9') || s[0] == '-') {
+	if (err == 0 && (s[0] >= '0' && s[0] <= '9') || s[0] == '-') {
 		long i;
 		errno = 0;
 		err = safe_strtol(s, &i);
@@ -948,8 +957,9 @@ static int _snd_config_save_leaves(snd_config_t *config, snd_output_t *out, unsi
 
 /**
  * \brief Substitute one node to another
- * \brief dst Destination node
+ * \param dst Destination node
- * \brief src Source node (invalid after call)
+ * \param src Source node (invalid after call)
+ * \return zero if success, otherwise a negative error code
  */
 int snd_config_substitute(snd_config_t *dst, snd_config_t *src)
 {
@@ -1457,6 +1467,8 @@ int snd_config_save(snd_config_t *config, snd_output_t *out)
  *  *** search macros ***
  */
 
+#ifndef DOC_HIDDEN
+
 #define SND_CONFIG_SEARCH(config, key, result, extra_code) \
 { \
 	snd_config_t *n; \
@@ -1573,6 +1585,7 @@ int snd_config_save(snd_config_t *config, snd_output_t *out)
 	return 0; \
 }
 
+#endif /* DOC_HIDDEN */
 
 /**
  * \brief Search a node inside a config tree
@@ -1856,6 +1869,14 @@ static int snd_config_hooks(snd_config_t *config, void *private_data)
 	return err;
 }
 
+/**
+ * \brief Load configuration from specified files
+ * \param root Configuration root node
+ * \param config Configuration node
+ * \param dst Destination node
+ * \param private_data Private data
+ * \return zero if success, otherwise a negative error code
+ */
 int snd_config_hook_load(snd_config_t *root, snd_config_t *config, snd_config_t **dst, void *private_data)
 {
 	snd_config_t *n, *res = NULL;
@@ -1978,8 +1999,18 @@ int snd_config_hook_load(snd_config_t *root, snd_config_t *config, snd_config_t
 	return err;
 }
 
+#ifndef DOC_HIDDEN
 int snd_determine_driver(int card, char **driver);
+#endif
 
+/**
+ * \brief Load configuration for all present cards
+ * \param root Configuration root node
+ * \param config Configuration node
+ * \param dst Destination node
+ * \param private_data Private data
+ * \return zero if success, otherwise a negative error code
+ */
 int snd_config_hook_load_for_all_cards(snd_config_t *root, snd_config_t *config, snd_config_t **dst, void *private_data ATTRIBUTE_UNUSED)
 {
 	int card = -1, err;
@@ -2201,20 +2232,23 @@ snd_config_t *snd_config_iterator_entry(snd_config_iterator_t iterator)
 	return list_entry(iterator, snd_config_t, list);
 }
 
+#ifndef DOC_HIDDEN
 typedef enum _snd_config_walk_pass {
 	SND_CONFIG_WALK_PASS_PRE,
 	SND_CONFIG_WALK_PASS_POST,
 	SND_CONFIG_WALK_PASS_LEAF,
 } snd_config_walk_pass_t;
-
+#endif
 
 /* Return 1 if node needs to be attached to father */
 /* Return 2 if compound is replaced with standard node */
+#ifndef DOC_HIDDEN
 typedef int (*snd_config_walk_callback_t)(snd_config_t *src,
 					  snd_config_t *root,
 					  snd_config_t **dst,
 					  snd_config_walk_pass_t pass,
 					  void *private_data);
+#endif
 
 static int snd_config_walk(snd_config_t *src,
 			   snd_config_t *root,

src/control/cards.c

@@ -1,10 +1,11 @@
 /**
  * \file control/cards.c
+ * \brief Basic Soundcard Operations
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 1998-2001
  */
 /*
- *  Control Interface - main file
+ *  Soundcard Operations - main file
  *  Copyright (c) 1998 by Jaroslav Kysela <perex@suse.cz>
  *
  *

src/control/control.c

@@ -1,5 +1,6 @@
 /**
  * \file control/control.c
+ * \brief CTL interface - primitive controls
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000
  *

src/control/hcontrol.c

@@ -1,5 +1,6 @@
 /**
  * \file control/hcontrol.c
+ * \brief HCTL Interface - High Level CTL
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000

src/control/setup.c

@@ -1,5 +1,6 @@
 /**
  * \file control/setup.c
+ * \brief Routines to setup control primitives from configuration
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 2001

src/error.c

@@ -1,5 +1,9 @@
 /**
  * \file error.c
+ * \brief Error code handling routines
+ * \author Jaroslav Kysela <perex@suse.cz>
+ * \date 1998-2001
+ *
  * Error code handling routines.
  */
 /*

src/hwdep/hwdep.c

@@ -1,5 +1,6 @@
 /*
  * \file hwdep/hwdep.c
+ * \brief HwDep Interface (hardware dependent)
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 2000-2001
  *

src/input.c

@@ -1,5 +1,6 @@
 /**
  * \file input.c
+ * \brief Generic stdio-like input interface
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000
  *

src/instr/fm.c

@@ -1,5 +1,6 @@
 /**
  * \file src/instr/fm.c
+ * \brief FM (OPL2/3) Instrument Format Support
  * \author Uros Bizjak <uros@kss-loka.si>
  * \date 2000-2001
  */

src/instr/iwffff.c

@@ -1,5 +1,6 @@
 /**
  * \file src/instr/iwffff.c
+ * \brief InterWave FFFF Format Support
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 1999-2001
  */

src/instr/simple.c

@@ -1,5 +1,6 @@
 /**
  * \file src/instr/simple.c
+ * \brief Simple Wave Format Support
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 1999-2001
  */

src/mixer/mixer.c

@@ -1,5 +1,6 @@
 /**
  * \file mixer/mixer.c
+ * \brief Mixer Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2001

src/mixer/simple.c

@@ -1,10 +1,11 @@
 /*
  * \file mixer/simple.c
+ * \brief Mixer Simple Element Class Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2001
  *
- * Mixer simple elements class interface.
+ * Mixer simple element class interface.
  */
 /*
  *  Mixer Interface - simple controls

src/output.c

@@ -1,5 +1,6 @@
 /**
  * \file output.c
+ * \brief Generic stdio-like output interface
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000
  *

src/pcm/pcm.c

@@ -1,5 +1,6 @@
 /**
  * \file pcm/pcm.c
+ * \brief PCM Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000-2001

src/pcm/pcm_meter.c

@@ -1,5 +1,6 @@
 /**
  * \file pcm/pcm_meter.c
+ * \brief Helper functions for #SND_PCM_TYPE_METER PCM scopes
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2001
  *

src/rawmidi/rawmidi.c

@@ -1,5 +1,6 @@
 /**
  * \file rawmidi/rawmidi.c
+ * \brief RawMidi Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \date 2000-2001

src/seq/seq.c

@@ -1,5 +1,6 @@
 /**
  * \file seq/seq.c
+ * \brief Sequencer Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \author Abramo Bagnara <abramo@alsa-project.org>
  * \author Takashi Iwai <tiwai@suse.de>

src/seq/seq_event.c

@@ -1,5 +1,6 @@
 /**
  * \file seq/seq_event.c
+ * \brief Sequencer Event Types
  * \author Takashi Iwai <tiwai@suse.de>
  * \date 2001
  */

src/seq/seq_midi_event.c

@@ -1,5 +1,6 @@
 /**
  * \file seq/seq_midi_event.c
+ * \brief MIDI byte <-> sequencer event coder
  * \author Takashi Iwai <tiwai@suse.de>
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 2000-2001

src/timer/timer.c

@@ -1,5 +1,6 @@
 /*
  * \file timer/timer.c
+ * \brief Timer Interface
  * \author Jaroslav Kysela <perex@suse.cz>
  * \date 1998-2001
  *