[FFmpeg-devel] avcodec/vorbisenc: Improve documentation

diff --git a/libavcodec/vorbis_enc_data.h b/libavcodec/vorbis_enc_data.h
index 32750da803..cf94700350 100644
--- a/libavcodec/vorbis_enc_data.h
+++ b/libavcodec/vorbis_enc_data.h
@@ -27,14 +27,14 @@ 
 #define RES_MAX_CLASSIF 10
 
 typedef const struct {
-    int dim;
-    int len;
-    int real_len;
-    const uint8_t *clens;
-    int lookup;
-    float min;
-    float delta;
-    const uint8_t *quant;
+    int dim;              ///< The number of elements per coded vector
+    int len;              ///< The number of filled entries in the book
+    int real_len;         ///< The expected number of entries, padded with 0 if len < real_len
+    const uint8_t *clens; ///< List of codeword lengths in bits
+    int lookup;           ///< Flag if vector lookup is available with this book
+    float min;            ///< The minimum value encoded by this book
+    float delta;          ///< The distance between encoded points
+    const uint8_t *quant; ///< Pointer to a (entries)^(1/dim) column map if lookup is set
 } codebook_setup;
 
 typedef const struct {
@@ -817,8 +817,8 @@  static codebook_setup res_mono_config[] = {
 };
 
 static const struct {
-    int dim;
-    int subclass;
+    int dim;        ///< Dimensions of the class master book
+    int subclass;   ///< Integer log base 2 of the number of subclass books
     int masterbook;
     const int nbooks[4];
 } floor_classes[2][5] = {
diff --git a/libavcodec/vorbisenc.c b/libavcodec/vorbisenc.c
index f4af2f4071..78b41b2b49 100644
--- a/libavcodec/vorbisenc.c
+++ b/libavcodec/vorbisenc.c
@@ -414,7 +414,7 @@  static void put_codebook_header(PutBitContext *pb, vorbis_enc_codebook *cb)
     int i;
     int ordered = 0;
 
-    put_bits(pb, 24, 0x564342); //magic
+    put_bits(pb, 24, 0x564342); // Signal the start of a codebook
     put_bits(pb, 16, cb->ndimensions);
     put_bits(pb, 24, cb->nentries);
 
@@ -520,6 +520,7 @@  static void put_residue_header(PutBitContext *pb, vorbis_enc_residue *rc,
     put_bits(pb, 6, rc->classifications - 1);
     put_bits(pb, 8, book_offset + rc->classbook);
 
+    /* We must specify which partition classes are used in each pass */
     for (i = 0; i < rc->classifications; i++) {
         int j, tmp = 0;
         for (j = 0; j < 8; j++)
@@ -540,6 +541,13 @@  static void put_residue_header(PutBitContext *pb, vorbis_enc_residue *rc,
     }
 }
 
+/**
+ * Output necessary information for all primary headers.
+ *
+ * @see       Vorbis I spec "4.2. Header decode and decode setup"
+ * @param out Empty buffer on input, encoded headers on output
+ * @return    Number of bits written to the buffer or error value
+ */
 static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
 {
     int i;
@@ -552,15 +560,15 @@  static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
 
     // identification header
     init_put_bits(&pb, p, buffer_len);
-    put_bits(&pb, 8, 1); //magic
+    put_bits(&pb, 8, 1); // Signal an ID header
     for (i = 0; "vorbis"[i]; i++)
         put_bits(&pb, 8, "vorbis"[i]);
     put_bits32(&pb, 0); // version
     put_bits(&pb,  8, venc->channels);
     put_bits32(&pb, venc->sample_rate);
-    put_bits32(&pb, 0); // bitrate
-    put_bits32(&pb, 0); // bitrate
-    put_bits32(&pb, 0); // bitrate
+    put_bits32(&pb, 0); // Maximum bitrate
+    put_bits32(&pb, 0); // Nominal bitrate
+    put_bits32(&pb, 0); // Minimum bitrate
     put_bits(&pb,  4, venc->log2_blocksize[0]);
     put_bits(&pb,  4, venc->log2_blocksize[1]);
     put_bits(&pb,  1, 1); // framing
@@ -572,11 +580,11 @@  static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
 
     // comment header
     init_put_bits(&pb, p, buffer_len);
-    put_bits(&pb, 8, 3); //magic
+    put_bits(&pb, 8, 3); // Signal a comment header
     for (i = 0; "vorbis"[i]; i++)
         put_bits(&pb, 8, "vorbis"[i]);
     put_bits32(&pb, 0); // vendor length TODO
-    put_bits32(&pb, 0); // amount of comments
+    put_bits32(&pb, 0); // amount of comments TODO
     put_bits(&pb,  1, 1); // framing
 
     flush_put_bits(&pb);
@@ -586,7 +594,7 @@  static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
 
     // setup header
     init_put_bits(&pb, p, buffer_len);
-    put_bits(&pb, 8, 5); //magic
+    put_bits(&pb, 8, 5); // Signal a setup header
     for (i = 0; "vorbis"[i]; i++)
         put_bits(&pb, 8, "vorbis"[i]);
 
@@ -623,7 +631,7 @@  static int put_main_header(vorbis_enc_context *venc, uint8_t **out)
         if (mc->submaps > 1)
             put_bits(&pb, 4, mc->submaps - 1);
 
-        put_bits(&pb, 1, !!mc->coupling_steps);
+        put_bits(&pb, 1, !!mc->coupling_steps); // Signal if square polar channel mapping is used
         if (mc->coupling_steps) {
             put_bits(&pb, 8, mc->coupling_steps - 1);
             for (j = 0; j < mc->coupling_steps; j++) {
@@ -937,7 +945,13 @@  static int residue_encode(vorbis_enc_context *venc, vorbis_enc_residue *rc,
 
 /**
  * Overlap windowed samples based on the suggested sequence from psy model.
+ *
  * See Vorbis I spec Fig. 2, 3 for examples.
+ *
+ * @param blockflags  Determines the window size to use for previous, current, and next frame
+ * @param out         Pointer to windowed samples suitable for correct overlapping
+ * @param in          Pointer to unmodified samples from the input stream
+ * @param clip_factor Scalar coefficient used to avoid clipping, especially for short windows
  */
 static void apply_window(vorbis_enc_context *venc, const int *blockflags,
                          float *out, float* in, const float clip_factor)
@@ -975,6 +989,11 @@  static void apply_window(vorbis_enc_context *venc, const int *blockflags,
     fdsp->vector_fmul_scalar(out, out, scale, 2 * curr_size);
 }
 
+/**
+ * Window input samples and apply the correct MDCT
+ *
+ * @param next_type Flag that specifies the length type of the next frame, exhibits a full block delay.
+ */
 static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
 {
     int channel, transient_offset, curr_len, curr_type;
@@ -993,6 +1012,7 @@  static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
     if (!curr_type)
         venc->transient++;
 
+    /* A short window must always treat the windows before and after as short as well. */
     blockflags[0] = curr_type ? blockflags[1] : 0;
     blockflags[1] = curr_type;
     blockflags[2] = curr_type ? next_type : 0;
@@ -1008,6 +1028,7 @@  static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
                                         venc->coeffs + channel * curr_len, out);
     }
 
+    /* We must also check to see if we are leaving the series of transients */
     if (venc->transient < 0 || venc->transient >= venc->num_transient - 1) {
         blockflags[2] = next_type;
         venc->transient = -1;
@@ -1015,7 +1036,9 @@  static int apply_window_and_mdct(vorbis_enc_context *venc, int next_type)
     return 1;
 }
 
-/* Used for padding the last encoded packet */
+/**
+ * Create a padding frame with zeroed samples so that a full block of samples is available.
+ */
 static AVFrame *spawn_empty_frame(AVCodecContext *avctx, int channels)
 {
     AVFrame *f = av_frame_alloc();
diff --git a/libavcodec/vorbisenc.h b/libavcodec/vorbisenc.h
index 15ee02dfa6..dc1ff06db8 100644
--- a/libavcodec/vorbisenc.h
+++ b/libavcodec/vorbisenc.h
@@ -67,15 +67,15 @@  typedef struct vorbis_enc_floor {
     int nclasses;
     vorbis_enc_floor_class *classes;
     int multiplier;
-    int rangebits;
+    int rangebits; ///< Number of bits required to represent the max window size
     int values;
     vorbis_floor1_entry *list;
 } vorbis_enc_floor;
 
 typedef struct vorbis_enc_residue {
     int type;
-    int begin;
-    int end;
+    int begin; ///< Index of the actual start of coded residue values
+    int end;   ///< Final index of coded residue values
     int partition_size;
     int classifications;
     int classbook;
@@ -89,8 +89,8 @@  typedef struct vorbis_enc_mapping {
     int *floor;
     int *residue;
     int coupling_steps;
-    int *magnitude;
-    int *angle;
+    int *magnitude; ///< Index offsetting for the magnitude vector used in coupling
+    int *angle;     ///< Index offsetting for the angle vector used in coupling
 } vorbis_enc_mapping;
 
 typedef struct vorbis_enc_mode {
@@ -108,12 +108,12 @@  typedef struct vorbis_enc_context {
     FFTContext mdct[2];
     const float *win[2];
     int have_saved;
-    float *saved;
+    float *saved;      ///< Old samples for window application between frames
     float *samples;
-    float *floor;  // also used for tmp values for mdct
-    float *coeffs; // also used for residue after floor
-    float *scratch; //< Used for temp values for psy model and window application
-    float quality;
+    float *floor;      ///< Calculated floor values removed from mdct output
+    float *coeffs;     ///< MDCT output used as the input for residue encoding
+    float *scratch;    ///< Used for temp values for psy model and window application
+    float quality;     ///< Controls the resolution for floor construction
 
     AudioFrameQueue afq;
     struct FFBufQueue bufqueue;