Improved Doxygen comments

git-svn-id: http://svn.xiph.org/trunk/speex@9873 0101bb08-14d6-0310-b084-bc0e0c8e3800

30 files changed, 248 insertions, 137 deletions

diff --git a/libspeex/arch.h b/libspeex/arch.h
index 65ceb22..b476244 100644
--- a/libspeex/arch.h
+++ b/libspeex/arch.h
@@ -37,10 +37,10 @@
 
 #include "speex/speex_types.h"
 
-#define ABS(x) ((x) < 0 ? (-(x)) : (x))
-#define ABS16(x) ((x) < 0 ? (-(x)) : (x))
-#define MAX16(a,b) ((a) > (b) ? (a) : (b))
-#define ABS32(x) ((x) < 0 ? (-(x)) : (x))
+#define ABS(x) ((x) < 0 ? (-(x)) : (x))      /**< Absolute integer value. */
+#define ABS16(x) ((x) < 0 ? (-(x)) : (x))    /**< Absolute 16-bit value.  */
+#define MAX16(a,b) ((a) > (b) ? (a) : (b))   /**< Maximum 16-bit value.   */
+#define ABS32(x) ((x) < 0 ? (-(x)) : (x))    /**< Absolute 32-bit value.  */
 
 #ifdef FIXED_POINT
 
diff --git a/libspeex/cb_search.h b/libspeex/cb_search.h
index 107d5ef..38ac077 100644
--- a/libspeex/cb_search.h
+++ b/libspeex/cb_search.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin & David Rowe
-   File: cb_search.h
-   Overlapped codebook search
-
+/* Copyright (C) 2002 Jean-Marc Valin & David Rowe */
+/**
+   @file cb_search.h
+   @brief Overlapped codebook search
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -36,6 +38,7 @@
 #include <speex/speex_bits.h>
 #include "misc.h"
 
+/** Split codebook parameters. */
 typedef struct split_cb_params {
    int     subvect_size;
    int     nb_subvect;
@@ -46,11 +49,11 @@ typedef struct split_cb_params {
 
 
 void split_cb_search_shape_sign(
-spx_sig_t target[],			/* target vector */
-spx_coef_t ak[],			/* LPCs for this subframe */
-spx_coef_t awk1[],			/* Weighted LPCs for this subframe */
-spx_coef_t awk2[],			/* Weighted LPCs for this subframe */
-const void *par,                      /* Codebook/search parameters*/
+spx_sig_t target[],             /* target vector */
+spx_coef_t ak[],                /* LPCs for this subframe */
+spx_coef_t awk1[],              /* Weighted LPCs for this subframe */
+spx_coef_t awk2[],              /* Weighted LPCs for this subframe */
+const void *par,                /* Codebook/search parameters */
 int   p,                        /* number of LPC coeffs */
 int   nsf,                      /* number of samples in subframe */
 spx_sig_t *exc,
@@ -63,7 +66,7 @@ int   update_target
 
 void split_cb_shape_sign_unquant(
 spx_sig_t *exc,
-const void *par,                      /* non-overlapping codebook */
+const void *par,                /* non-overlapping codebook */
 int   nsf,                      /* number of samples in subframe */
 SpeexBits *bits,
 char *stack
@@ -71,11 +74,11 @@ char *stack
 
 
 void noise_codebook_quant(
-spx_sig_t target[],			/* target vector */
-spx_coef_t ak[],			/* LPCs for this subframe */
-spx_coef_t awk1[],			/* Weighted LPCs for this subframe */
-spx_coef_t awk2[],			/* Weighted LPCs for this subframe */
-const void *par,                      /* Codebook/search parameters*/
+spx_sig_t target[],             /* target vector */
+spx_coef_t ak[],                /* LPCs for this subframe */
+spx_coef_t awk1[],              /* Weighted LPCs for this subframe */
+spx_coef_t awk2[],              /* Weighted LPCs for this subframe */
+const void *par,                /* Codebook/search parameters */
 int   p,                        /* number of LPC coeffs */
 int   nsf,                      /* number of samples in subframe */
 spx_sig_t *exc,
@@ -89,7 +92,7 @@ int   update_target
 
 void noise_codebook_unquant(
 spx_sig_t *exc,
-const void *par,                      /* non-overlapping codebook */
+const void *par,                /* non-overlapping codebook */
 int   nsf,                      /* number of samples in subframe */
 SpeexBits *bits,
 char *stack
diff --git a/libspeex/cb_search_arm4.h b/libspeex/cb_search_arm4.h
index 56cbb19..71318ba 100644
--- a/libspeex/cb_search_arm4.h
+++ b/libspeex/cb_search_arm4.h
@@ -1,6 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: cb_search.c (ARM4 version)
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file cb_search_arm4.h
+   @brief Fixed codebook functions (ARM4 version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/cb_search_bfin.h b/libspeex/cb_search_bfin.h
index 8412b4b..7d476a3 100644
--- a/libspeex/cb_search_bfin.h
+++ b/libspeex/cb_search_bfin.h
@@ -1,8 +1,10 @@
-/* Copyright (C) 2005 Analog Devices
-   Author: Jean-Marc Valin 
-   File: cb_search_bfin.h
-   Fixed codebook functions (Blackfin version)
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @author Jean-Marc Valin 
+   @file cb_search_bfin.h
+   @brief Fixed codebook functions (Blackfin version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/cb_search_sse.h b/libspeex/cb_search_sse.h
index 2ca3c7c..8b03968 100644
--- a/libspeex/cb_search_sse.h
+++ b/libspeex/cb_search_sse.h
@@ -1,6 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: cb_search.c (SSE version)
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file cb_search_sse.h
+   @brief Fixed codebook functions (SSE version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/filters.h b/libspeex/filters.h
index de0b284..c86d189 100644
--- a/libspeex/filters.h
+++ b/libspeex/filters.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: filters.h
-   Various analysis/synthesis filters
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file filters.h
+   @brief Various analysis/synthesis filters
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -45,7 +47,8 @@ int normalize16(const spx_sig_t *x, spx_word16_t *y, spx_sig_t max_scale, int le
 
 #endif
 
-typedef struct CombFilterMem {
+/** Combined filter memory. */
+typedef struct {
    int   last_pitch;
    spx_word16_t last_pitch_gain[3];
    spx_word16_t smooth_gain;
diff --git a/libspeex/filters_arm4.h b/libspeex/filters_arm4.h
index 7cdb25a..b250364 100644
--- a/libspeex/filters_arm4.h
+++ b/libspeex/filters_arm4.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: filters_arm4.h
-   ARM4-optimized filtering routines
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file filters_arm4.h
+   @brief Various analysis/synthesis filters (ARM4 version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/filters_bfin.h b/libspeex/filters_bfin.h
index 4604d71..f968722 100644
--- a/libspeex/filters_bfin.h
+++ b/libspeex/filters_bfin.h
@@ -1,8 +1,9 @@
-/* Copyright (C) 2005 Analog Devices
-   Author: Jean-Marc Valin 
-   File: filters_bfin.h
-   Various analysis/synthesis filters (Blackfin version)
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @file filters_bfin.h
+   @brief Various analysis/synthesis filters (Blackfin version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/filters_sse.h b/libspeex/filters_sse.h
index 1a9896c..82cde0d 100644
--- a/libspeex/filters_sse.h
+++ b/libspeex/filters_sse.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: filters.c
-   Various analysis/synthesis filters
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file filters_sse.h
+   @brief Various analysis/synthesis filters (SSE version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/fixed_arm5e.h b/libspeex/fixed_arm5e.h
index a060b58..9b4861c 100644
--- a/libspeex/fixed_arm5e.h
+++ b/libspeex/fixed_arm5e.h
@@ -1,6 +1,6 @@
 /* Copyright (C) 2003 Jean-Marc Valin */
 /**
-   @file fixed_generic.h
+   @file fixed_arm5e.h
    @brief ARM-tuned fixed-point operations
 */
 /*
diff --git a/libspeex/lpc.h b/libspeex/lpc.h
index 6050447..d64df96 100644
--- a/libspeex/lpc.h
+++ b/libspeex/lpc.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: lpc.h
-   Functions for LPC (Linear Prediction Coefficients) analysis
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file lpc.h
+   @brief Functions for LPC (Linear Prediction Coefficients) analysis
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/lpc_bfin.h b/libspeex/lpc_bfin.h
index cfd5fe5..19c7313 100644
--- a/libspeex/lpc_bfin.h
+++ b/libspeex/lpc_bfin.h
@@ -1,8 +1,10 @@
-/* Copyright (C) 2005 Analog Devices
-   Author: Jean-Marc Valin 
-   File: lpc_bfin.h
-   LPC stuff (Blackfin version)
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @file lpc_bfin.h
+   @author Jean-Marc Valin 
+   @brief Functions for LPC (Linear Prediction Coefficients) analysis (Blackfin version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/lsp.h b/libspeex/lsp.h
index 5e7b02a..9d0345f 100644
--- a/libspeex/lsp.h
+++ b/libspeex/lsp.h
@@ -14,6 +14,10 @@ Modified by Jean-Marc Valin
     unit circle.

 

 \*---------------------------------------------------------------------------*/

+/**

+   @file lsp.h

+   @brief Line Spectral Pair (LSP) functions.

+*/

 /* Speex License:

 

    Redistribution and use in source and binary forms, with or without

diff --git a/libspeex/ltp.h b/libspeex/ltp.h
index 9895356..36debbd 100644
--- a/libspeex/ltp.h
+++ b/libspeex/ltp.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: ltp.h
-   Long-Term Prediction functions
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file ltp.h
+   @brief Long-Term Prediction functions
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -33,7 +35,8 @@
 #include <speex/speex_bits.h>
 #include "misc.h"
 
-typedef struct ltp_params {
+/** LTP parameters. */
+typedef struct {
    const signed char *gain_cdbk;
    int     gain_bits;
    int     pitch_bits;
diff --git a/libspeex/ltp_arm4.h b/libspeex/ltp_arm4.h
index 6f458ea..a5a0bee 100644
--- a/libspeex/ltp_arm4.h
+++ b/libspeex/ltp_arm4.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: ltp.c
-   Lont-Term Prediction functions (SSE version)
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file ltp_arm4.h
+   @brief Long-Term Prediction functions (ARM4 version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/ltp_bfin.h b/libspeex/ltp_bfin.h
index a800503..70bff7e 100644
--- a/libspeex/ltp_bfin.h
+++ b/libspeex/ltp_bfin.h
@@ -1,8 +1,10 @@
-/* Copyright (C) 2005 Analog Devices
-   Author: Jean-Marc Valin 
-   File: ltp_bfin.h
-   Long-Term Prediction functions (Blackfin version)
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @file ltp_bfin.h
+   @author Jean-Marc Valin
+   @brief Long-Term Prediction functions (Blackfin version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/ltp_sse.h b/libspeex/ltp_sse.h
index 0267883..94c0012 100644
--- a/libspeex/ltp_sse.h
+++ b/libspeex/ltp_sse.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: ltp.c
-   Lont-Term Prediction functions (SSE version)
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file ltp_sse.h
+   @brief Long-Term Prediction functions (SSE version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/math_approx.h b/libspeex/math_approx.h
index 1c84f5c..e489d09 100644
--- a/libspeex/math_approx.h
+++ b/libspeex/math_approx.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: math_approx.c
-   Various math approximation functions for Speex
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file math_approx.h
+   @brief Various math approximation functions for Speex
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/medfilter.h b/libspeex/medfilter.h
index e34065b..718869c 100644
--- a/libspeex/medfilter.h
+++ b/libspeex/medfilter.h
@@ -1,8 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin
-   File medfilter.h
-   Median filter
-
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file medfilter.h
+   @brief Median filter
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -35,6 +36,7 @@
 #ifndef MEDFILTER_H
 #define MEDFILTER_H
 
+/** Median filter. */
 typedef struct {
    int N;
    int filled;
diff --git a/libspeex/misc.c b/libspeex/misc.c
index 4b0223b..fd78d0b 100644
--- a/libspeex/misc.c
+++ b/libspeex/misc.c
@@ -1,5 +1,5 @@
 /* Copyright (C) 2002-2005 Jean-Marc Valin 
-   File: mics.c
+   File: misc.c
    Various utility routines for Speex
 
    Redistribution and use in source and binary forms, with or without
diff --git a/libspeex/misc.h b/libspeex/misc.h
index 8232ebd..8e83d21 100644
--- a/libspeex/misc.h
+++ b/libspeex/misc.h
@@ -36,20 +36,23 @@
 #define MISC_H
 
 #ifndef SPEEX_VERSION
-#define SPEEX_MAJOR_VERSION 1
-#define SPEEX_MINOR_VERSION 1
-#define SPEEX_MICRO_VERSION 10
-#define SPEEX_EXTRA_VERSION ""
-#define SPEEX_VERSION "speex-1.1.10"
+#define SPEEX_MAJOR_VERSION 1         /**< Major Speex version. */
+#define SPEEX_MINOR_VERSION 1         /**< Minor Speex version. */
+#define SPEEX_MICRO_VERSION 10        /**< Micro Speex version. */
+#define SPEEX_EXTRA_VERSION ""        /**< Extra Speex version. */
+#define SPEEX_VERSION "speex-1.1.10"  /**< Speex version string. */
 #endif
 
 #include "arch.h"
 
 #ifndef RELEASE
+/** Print a named vector to stdout */
 void print_vec(float *vec, int len, char *name);
 #endif
 
+/** Convert big endian */
 spx_uint32_t be_int(spx_uint32_t i);
+/** Convert little endian */
 spx_uint32_t le_int(spx_uint32_t i);
 
 /** Speex wrapper for calloc. To do your own dynamic allocation, all you need to do is replace this function, speex_realloc and speex_free */
@@ -70,19 +73,28 @@ void speex_free_scratch (void *ptr);
 /** Speex wrapper for mem_move */
 void *speex_move (void *dest, void *src, int n);
 
+/** Speex wrapper for memcpy */
 void speex_memcpy_bytes(char *dst, char *src, int nbytes);
+
+/** Speex wrapper for memset */
 void speex_memset_bytes(char *dst, char src, int nbytes);
 
+/** Print error message to stderr */
 void speex_error(const char *str);
 
+/** Print warning message to stderr */
 void speex_warning(const char *str);
 
+/** Print warning message with integer argument to stderr */
 void speex_warning_int(const char *str, int val);
 
+/** Generate a vector of random numbers */
 void speex_rand_vec(float std, spx_sig_t *data, int len);
 
+/** Generate a random number */
 spx_word32_t speex_rand(spx_word16_t std, spx_int32_t *seed);
 
+/** Speex wrapper for putc */
 void _speex_putc(int ch, void *file);
 
 #endif
diff --git a/libspeex/misc_bfin.h b/libspeex/misc_bfin.h
index f0a08dd..77b082c 100644
--- a/libspeex/misc_bfin.h
+++ b/libspeex/misc_bfin.h
@@ -1,8 +1,10 @@
-/* Copyright (C) 2005 Analog Devices
-   Author:  Jean-Marc Valin 
-   File: mics_bfin.h
-   Various utility routines for Speex
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @file misc_bfin.h
+   @author Jean-Marc Valin 
+   @brief Various compatibility routines for Speex (Blackfin version)
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/quant_lsp.h b/libspeex/quant_lsp.h
index dc2828e..c6d5bb3 100644
--- a/libspeex/quant_lsp.h
+++ b/libspeex/quant_lsp.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: quant_lsp.h
-   LSP vector quantization
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file quant_lsp.h
+   @brief LSP vector quantization
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/smallft.h b/libspeex/smallft.h
index c87389c..446e2f6 100644
--- a/libspeex/smallft.h
+++ b/libspeex/smallft.h
@@ -14,16 +14,20 @@
  last mod: $Id: smallft.h,v 1.3 2003/09/16 18:35:45 jm Exp $
 
  ********************************************************************/
+/**
+   @file smallft.h
+   @brief Discrete Rotational Fourier Transform (DRFT)
+*/
 
 #ifndef _V_SMFT_H_
 #define _V_SMFT_H_
 
-/*#include "vorbis/codec.h"*/
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/** Discrete Rotational Fourier Transform lookup */
 struct drft_lookup{
   int n;
   float *trigcache;
diff --git a/libspeex/stack_alloc.h b/libspeex/stack_alloc.h
index 9d18468..39f5611 100644
--- a/libspeex/stack_alloc.h
+++ b/libspeex/stack_alloc.h
@@ -1,8 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: stack_alloc.h
-   
-   Temporary memory allocation on stack
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file stack_alloc.h
+   @brief Temporary memory allocation on stack
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -38,28 +39,68 @@
 #include <alloca.h>
 #endif
 
+/**
+ * @def ALIGN(stack, size)
+ *
+ * Aligns the stack to a 'size' boundary
+ *
+ * @param stack Stack
+ * @param size  New size boundary
+ */
+
+/**
+ * @def PUSH(stack, size, type)
+ *
+ * Allocates 'size' elements of type 'type' on the stack
+ *
+ * @param stack Stack
+ * @param size  Number of elements
+ * @param type  Type of element
+ */
+
+/**
+ * @def PUSHS(stack, type)
+ *
+ * Allocates a struct stack 
+ *
+ * @param stack Stack
+ * @param type  Struct type
+ */
+
+/**
+ * @def VARDECL(var)
+ *
+ * Declare variable on stack
+ *
+ * @param var Variable to declare
+ */
+
+/**
+ * @def ALLOC(var, size, type)
+ *
+ * Allocate 'size' elements of 'type' on stack
+ *
+ * @param var  Name of variable to allocate
+ * @param size Number of elements
+ * @param type Type of element
+ */
+
 #ifdef ENABLE_VALGRIND
 
 #include <valgrind/memcheck.h>
-/*Aligns the stack to a 'size' boundary */
+
 #define ALIGN(stack, size) ((stack) += ((size) - (long)(stack)) & ((size) - 1))
 
-/* Allocates 'size' elements of type 'type' on the stack */
 #define PUSH(stack, size, type) (VALGRIND_MAKE_NOACCESS(stack, 1000),ALIGN((stack),sizeof(type)),VALGRIND_MAKE_WRITABLE(stack, ((size)*sizeof(type))),(stack)+=((size)*sizeof(type)),(type*)((stack)-((size)*sizeof(type))))
 
-/* Allocates a struct stack */
 #define PUSHS(stack, type) (VALGRIND_MAKE_NOACCESS(stack, 1000),ALIGN((stack),sizeof(long)),VALGRIND_MAKE_WRITABLE(stack, (sizeof(type))),(stack)+=(sizeof(type)),(type*)((stack)-(sizeof(type))))
 
 #else
 
-
-/*Aligns the stack to a 'size' boundary */
 #define ALIGN(stack, size) ((stack) += ((size) - (long)(stack)) & ((size) - 1))
 
-/* Allocates 'size' elements of type 'type' on the stack */
 #define PUSH(stack, size, type) (ALIGN((stack),sizeof(type)),(stack)+=((size)*sizeof(type)),(type*)((stack)-((size)*sizeof(type))))
 
-/* Allocates a struct stack */
 #define PUSHS(stack, type) (ALIGN((stack),sizeof(long)),(stack)+=(sizeof(type)),(type*)((stack)-(sizeof(type))))
 
 #endif
diff --git a/libspeex/vbr.h b/libspeex/vbr.h
index 7a6abef..34e1d4c 100644
--- a/libspeex/vbr.h
+++ b/libspeex/vbr.h
@@ -1,8 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin 
-   File: vbr.h
-
-   VBR-related routines
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file vbr.h
+   @brief Variable Bit-Rate (VBR) related routines
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -44,6 +45,7 @@ extern const float vbr_nb_thresh[9][11];
 extern const float vbr_hb_thresh[5][11];
 extern const float vbr_uhb_thresh[2][11];
 
+/** VBR state. */
 typedef struct VBRState {
    float energy_alpha;
    float average_energy;
diff --git a/libspeex/vq.h b/libspeex/vq.h
index 79bd9e9..7ca8197 100644
--- a/libspeex/vq.h
+++ b/libspeex/vq.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2002 Jean-Marc Valin
-   File: vq.h
-   Vector quantization
-
+/* Copyright (C) 2002 Jean-Marc Valin */
+/**
+   @file vq.h
+   @brief Vector quantization
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/vq_arm4.h b/libspeex/vq_arm4.h
index 3b11665..585b861 100644
--- a/libspeex/vq_arm4.h
+++ b/libspeex/vq_arm4.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: vq_arm4.h
-   ARM4-optimized vq routine
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file vq_arm4.h
+   @brief ARM4-optimized vq routine
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
@@ -110,4 +112,4 @@ dist1=dist2=dist3=dist4=0;
       }
       codebook += 3*len;
    }
-}
\ No newline at end of file
+}
diff --git a/libspeex/vq_bfin.h b/libspeex/vq_bfin.h
index 739062a..2cc9ea5 100644
--- a/libspeex/vq_bfin.h
+++ b/libspeex/vq_bfin.h
@@ -1,8 +1,10 @@
-/* Copyright (C) 2005 Analog Devices
-   Author:  Jean-Marc Valin 
-   File: vq_arm4.h
-   Blackfin-optimized vq routine
-
+/* Copyright (C) 2005 Analog Devices */
+/**
+   @file vq_bfin.h
+   @author Jean-Marc Valin 
+   @brief Blackfin-optimized vq routine
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met:
diff --git a/libspeex/vq_sse.h b/libspeex/vq_sse.h
index 61b5806..00a42ce 100644
--- a/libspeex/vq_sse.h
+++ b/libspeex/vq_sse.h
@@ -1,7 +1,9 @@
-/* Copyright (C) 2004 Jean-Marc Valin 
-   File: vq_arm4.h
-   ARM4-optimized vq routine
-
+/* Copyright (C) 2004 Jean-Marc Valin */
+/**
+   @file vq_sse.h
+   @brief SSE-optimized vq routine
+*/
+/*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
    are met: