From 465f84546f810776ea6c4bd06fec34ff8452e933 Mon Sep 17 00:00:00 2001
From: Andre Noll <maan@systemlinux.org>
Date: Sat, 8 Mar 2014 13:34:54 +0100
Subject: [PATCH] bitstream: Improve documentation.

Mention that the bitstream API is only used for the WMA decoder,
avoid overlong descriptions of function parameters and add some
doxygen \ref commands.
---
 bitstream.c | 29 +++++++++++------------------
 bitstream.h | 11 ++++++-----
 2 files changed, 17 insertions(+), 23 deletions(-)

diff --git a/bitstream.c b/bitstream.c
index 492b407d..fb638d0a 100644
--- a/bitstream.c
+++ b/bitstream.c
@@ -11,9 +11,7 @@
  * For licencing details see COPYING.LIB.
  */
 
-/**
- * \file bitstream.c Bitstream API.
- */
+/** \file bitstream.c Bitstream API for the wma decoder. */
 
 #include <stdlib.h>
 #include <inttypes.h>
@@ -128,19 +126,15 @@ static int build_table(struct vlc *vlc, int table_nb_bits, int nb_codes,
  * Build VLC decoding tables suitable for use with get_vlc().
  *
  * \param vlc The structure to be initialized.
- *
- * \param nb_bits Set the decoding table size (2^nb_bits) entries. The bigger
- * it is, the faster is the decoding. But it should not be too big to save
- * memory and L1 cache. '9' is a good compromise.
- *
- * \param nb_codes Number of vlcs codes.
- *
+ * \param nb_bits Set the decoding table size (2^nb_bits) entries.
+ * \param nb_codes Number of vlc codes.
  * \param bits Table which gives the size (in bits) of each vlc code.
- *
  * \param codes Table which gives the bit pattern of of each vlc code.
- *
  * \param codes_size The number of bytes of each entry of the \a codes tables.
  *
+ * The bigger \a nb_bits is, the faster is the decoding. But it should not be
+ * too big to save memory and L1 cache. '9' is a good compromise.
+ *
  * The wrap and size parameters allow to use any memory configuration and
  * types (byte/word/long) to store the bits and codes tables.
  */
@@ -172,15 +166,14 @@ void free_vlc(struct vlc *vlc)
  * Parse a vlc code.
  *
  * \param gbc The getbit context structure.
- *
  * \param table The vlc tables to use.
- *
- * \param bits The number of bits which will be read at once, must be
- * identical to nb_bits in init_vlc().
- *
- * \param max_depth The number of times bits bits must be read to completely
+ * \param bits The number of bits which will be read at once.
+ * \param max_depth The number of times \a bits bits must be read to completely
  * read the longest vlc code = (max_vlc_length + bits - 1) / bits.
  *
+ * The \a bits parameter must be identical to the \a nb_bits value supplied to
+ * \ref init_vlc().
+ *
  * \return The vlc code.
  */
 int get_vlc(struct getbit_context *gbc, VLC_TYPE(*table)[2], int bits,
diff --git a/bitstream.h b/bitstream.h
index a3393380..5890d08c 100644
--- a/bitstream.h
+++ b/bitstream.h
@@ -69,11 +69,13 @@ static inline unsigned int get_bit(struct getbit_context *gbc)
 /**
  * Initialize a getbit_context structure.
  *
- * \param buffer The bitstream buffer. It must be 4 bytes larger then the
- * actual read bits because the bitstream reader might read 32 bits at once and
- * could read over the end.
+ * \param gbc The structure to initialize.
+ * \param buffer The bitstream buffer.
+ * \param size The size of the buffer in bytes.
  *
- * \param bit_size The size of the buffer in bytes.
+ * The bitstream buffer must be 4 bytes larger then the actual read bits
+ * because the bitstream reader might read 32 bits at once and could read over
+ * the end.
  */
 static inline void init_get_bits(struct getbit_context *gbc,
 		const uint8_t *buffer, int size)
@@ -88,4 +90,3 @@ void init_vlc(struct vlc *vlc, int nb_bits, int nb_codes, const void *bits,
 void free_vlc(struct vlc *vlc);
 int get_vlc(struct getbit_context *gbc, VLC_TYPE(*table)[2], int bits,
 		int max_depth);
-
-- 
2.39.5