diff --git a/libcelt/bands.h b/libcelt/bands.h
index 07712ea5ea2d1795720aae74c01f8cbd6a488640..01a9da200c6876e1f667eaba2917f9c6fb49c75d 100644
--- a/libcelt/bands.h
+++ b/libcelt/bands.h
@@ -78,6 +78,7 @@ void pitch_quant_bands(const CELTMode *m, float *X, float *P, float *gains);
  * @param X Residual (normalised)
  * @param P Pitch vector (normalised)
  * @param W Perceptual weighting
+ * @param total_bits Total number of bits that can be used for the frame (including the ones already spent)
  * @param enc Entropy encoder
  */
 void quant_bands(const CELTMode *m, float *X, float *P, float *W, int total_bits, ec_enc *enc);
@@ -86,6 +87,7 @@ void quant_bands(const CELTMode *m, float *X, float *P, float *W, int total_bits
  * @param m Mode data 
  * @param X Residual (normalised)
  * @param P Pitch vector (normalised)
+ * @param total_bits Total number of bits that can be used for the frame (including the ones already spent)
  * @param dec Entropy decoder
 */
 void unquant_bands(const CELTMode *m, float *X, float *P, int total_bits, ec_dec *dec);
diff --git a/libcelt/celt.c b/libcelt/celt.c
index ae7e54c8daef466d4b0a436884b43d3ebc880299..ee1a88c4dd30b1a30769edb10a51b6d069a217c7 100644
--- a/libcelt/celt.c
+++ b/libcelt/celt.c
@@ -53,8 +53,11 @@
 #define M_PI 3.14159263
 #endif
 
+/** Encoder state 
+ @brief Encoder state
+ */
 struct CELTEncoder {
-   const CELTMode *mode;
+   const CELTMode *mode;     /**< Mode used by the encoder */
    int frame_size;
    int block_size;
    int nb_blocks;
@@ -417,7 +420,9 @@ int celt_encode(CELTEncoder *st, celt_int16_t *pcm, unsigned char *compressed, i
 /****************************************************************************/
 
 
-
+/** Decoder state 
+ @brief Decoder state
+ */
 struct CELTDecoder {
    const CELTMode *mode;
    int frame_size;
diff --git a/libcelt/celt.h b/libcelt/celt.h
index fde4521fd09878705edded1f02ff5dcb607f835e..f5e36ff3912ad6e5ae106b0f51ef32cb7c57a575 100644
--- a/libcelt/celt.h
+++ b/libcelt/celt.h
@@ -56,8 +56,11 @@ extern "C" {
 #define CELT_CORRUPTED_DATA   -4
 
 /* Requests */
+/** GET the frame size used in the current mode */
 #define CELT_GET_FRAME_SIZE   1000
+/** GET the lookahead used in the current mode */
 #define CELT_GET_LOOKAHEAD    1001
+/** GET the number of channels used in the current mode */
 #define CELT_GET_NB_CHANNELS  1002
 
 
diff --git a/libcelt/modes.h b/libcelt/modes.h
index 1a20496dd81904f65317c7ff6c0ced7c6cc73962..a047822676a20dfef70aa4818dd32b8f3f9c2187 100644
--- a/libcelt/modes.h
+++ b/libcelt/modes.h
@@ -35,6 +35,9 @@
 #include "celt_types.h"
 #include "celt.h"
 
+/** Mode definition (opaque)
+ @brief Mode definition 
+ */
 struct CELTMode {
    int          overlap;
    int          mdctSize;
@@ -45,15 +48,15 @@ struct CELTMode {
    int          nbPBands;
    int          pitchEnd;
    
-   const int   *eBands;
-   const int   *pBands;
+   const int   *eBands;   /**< Definition for each "pseudo-critical band" */
+   const int   *pBands;   /**< Definition of the bands used for the pitch */
    
-   float        ePredCoef;
+   float        ePredCoef;/**< Prediction coefficient for the energy encoding */
    
-   int          nbAllocVectors;
-   const int   *allocVectors;
+   int          nbAllocVectors; /**< Number of lines in the matrix below */
+   const int   *allocVectors;   /**< Number of bits in each band for several rates */
    
-   const int * const *bits;
+   const int * const *bits; /**< Cache for pulses->bits mapping in each band */
 
 };
 
diff --git a/libcelt/vq.h b/libcelt/vq.h
index a249b3e87988d106927148aaf8255cf12c4c60c4..be66e72f07367a286c3b470fc75755f71d1aa033 100644
--- a/libcelt/vq.h
+++ b/libcelt/vq.h
@@ -1,5 +1,9 @@
 /* (C) 2007 Jean-Marc Valin, CSIRO
 */
+/**
+   @file vq.h
+   @brief Vector quantisation of the residual
+ */
 /*
    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions
@@ -66,7 +70,7 @@ void alg_unquant(float *x, int N, int K, float *p, float alpha, ec_dec *dec);
  * @param N Number of samples to encode
  * @param K Number of pulses to use
  * @param Y Lower frequency spectrum to use, normalised to the same standard deviation
- * @param p Pitch vector (it is assumed that p+x is a unit vector)
+ * @param P Pitch vector (it is assumed that p+x is a unit vector)
  * @param B Stride (number of channels multiplied by the number of MDCTs per frame)
  * @param N0 Number of valid offsets
  * @param enc Entropy encoder state