new_docs.diff

diff --git a/libavcodec/bitstream.h b/libavcodec/bitstream.h
index ab4fe70..76ad89b 100644
--- a/libavcodec/bitstream.h
+++ b/libavcodec/bitstream.h
@@ -44,8 +44,8 @@ typedef struct BitstreamContext {
 } BitstreamContext;
 
 /**
- * Return number of bits already read.
- */
+ * @param s BitstreamContext
+ * @return number of bits already read */
 static inline int bitstream_tell(const BitstreamContext *s)
 {
     return (s->ptr - s->buffer) * 8 - s->bits_left;
@@ -82,9 +82,9 @@ static inline uint64_t get_val(BitstreamContext *s, unsigned n)
 }
 
 /**
- * Return one bit from the buffer.
- */
-static inline unsigned int bitstream_read_bit(BitstreamContext *s)
+ * @param s BitstreamContext
+ * @return one bit from the buffer */
+static inline unsigned bitstream_read_bit(BitstreamContext *s)
 {
     if (av_unlikely(!s->bits_left))
         refill_64(s);
@@ -93,9 +93,9 @@ static inline unsigned int bitstream_read_bit(BitstreamContext *s)
 }
 
 /**
- * Return n bits from the buffer.
- * n has to be in the 0-63 range.
- */
+ * @param s BitstreamConteVxt
+ * @param n number from the 0-63 range
+ * @return n bits from the buffer */
 static inline uint64_t bitstream_read_63(BitstreamContext *s, unsigned n)
 {
     uint64_t ret = 0;
@@ -139,9 +139,9 @@ static inline void refill_32(BitstreamContext *s)
 }
 
 /**
- * Return n bits from the buffer.
- * n has to be in the 0-32 range.
- */
+ * @param s BitstreamContext
+ * @param n number from the 0-32 range
+ * @return n bits from the buffer */
 static inline uint32_t bitstream_read(BitstreamContext *s, unsigned n)
 {
     if (av_unlikely(!n))
@@ -156,7 +156,7 @@ static inline uint32_t bitstream_read(BitstreamContext *s, unsigned n)
     return get_val(s, n);
 }
 
-static inline unsigned int show_val(BitstreamContext *s, unsigned n)
+static inline unsigned show_val(BitstreamContext *s, unsigned n)
 {
     int ret;
 
@@ -170,10 +170,10 @@ static inline unsigned int show_val(BitstreamContext *s, unsigned n)
 }
 
 /**
- * Return n bits from the buffer, but do not change the buffer state.
- * n has to be in the 0-32 range.
- */
-static inline unsigned int bitstream_peek(BitstreamContext *s, unsigned n)
+ * @param s BitstreamContext
+ * @param n number from the 0-32 range
+ * @return n bits from the buffer, but do not change the buffer state */
+static inline unsigned bitstream_peek(BitstreamContext *s, unsigned n)
 {
     if (av_unlikely(n > s->bits_left))
         refill_32(s);
@@ -192,8 +192,8 @@ static inline void skip_remaining(BitstreamContext *s, unsigned n)
 }
 
 /**
- * Skip n bits in the buffer.
- */
+ * @param s BitstreamContext
+ * @param n number of bits to skip in the buffer */
 static inline void bitstream_skip(BitstreamContext *s, unsigned n)
 {
     if (n <= s->bits_left)
@@ -216,8 +216,7 @@ static inline void bitstream_skip(BitstreamContext *s, unsigned n)
 /**
  * Read MPEG-1 dc-style VLC (sign bit + mantissa with no MSB).
  * If MSB not set it is negative.
- * @param n length in bits
- */
+ * @param n length in bits */
 static inline int bitstream_read_xbits(BitstreamContext *s, unsigned n)
 {
     int sign;
@@ -231,27 +230,27 @@ static inline int bitstream_read_xbits(BitstreamContext *s, unsigned n)
 }
 
 /**
- * Return n bits from the buffer as a signed integer.
- * n has to be in the 0-32 range.
- */
+ * @param s BitstreamContext
+ * @param n number from the 0-32 range
+ * @return n bits from the buffer as a signed integer */
 static inline int32_t bitstream_read_signed(BitstreamContext *s, unsigned n)
 {
     return sign_extend(bitstream_read(s, n), n);
 }
 
 /**
- * Return n bits from the buffer as a signed integer whithout changing the buffer state.
- * n has to be in the 0-32 range.
- */
+ * @param s BitstreamContext
+ * @param n number from the 0-32 range
+ * @return n bits from the buffer as a signed integer whithout changing the buffer state */
 static inline int bitstream_peek_signed(BitstreamContext *s, unsigned n)
 {
     return sign_extend(bitstream_peek(s, n), n);
 }
 
 /**
- * Return marker bit.
- * Print a message msg if it is missing.
- */
+ * @param s BitstreamContext
+ * @param msg a message to print if it is missing
+ * @return marker bit */
 static inline int bitstream_check_marker(BitstreamContext *s, const char *msg)
 {
     int bit = bitstream_read_bit(s);
@@ -262,8 +261,8 @@ static inline int bitstream_check_marker(BitstreamContext *s, const char *msg)
 }
 
 /**
- * Seek to the given bit position.
- */
+ * @param s BitstreamContext
+ * Seek to the given bit position. */
 static inline void bitstream_seek(BitstreamContext *s, unsigned pos)
 {
     s->ptr       = s->buffer;
@@ -279,9 +278,8 @@ static inline void bitstream_seek(BitstreamContext *s, unsigned pos)
  *        larger than the actual read bits because some optimized bitstream
  *        readers read 32 or 64 bits at once and could read over the end
  * @param bit_size the size of the buffer in bits
- * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow.
- */
-static inline int bitstream_init(BitstreamContext *s, const uint8_t *buffer, int bit_size)
+ * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow */
+static inline int bitstream_init(BitstreamContext *s, const uint8_t *buffer, unsigned bit_size)
 {
     int buffer_size;
     int ret = 0;
@@ -292,7 +290,7 @@ static inline int bitstream_init(BitstreamContext *s, const uint8_t *buffer, int
         return AVERROR_INVALIDDATA;
     }
 
-    buffer_size = (bit_size + 7) >> 3;
+    buffer_size     = (bit_size + 7) >> 3;
 
     s->buffer       = buffer;
     s->buffer_end   = buffer + buffer_size;
@@ -307,8 +305,8 @@ static inline int bitstream_init(BitstreamContext *s, const uint8_t *buffer, int
 }
 
 /**
- * Return buffer size in bits.
- */
+ * @param s BitstreamContext
+ * @return buffer size in bits */
 static inline int bitstream_tell_size(BitstreamContext *s)
 {
     return s->size_in_bits;
@@ -320,8 +318,7 @@ static inline int bitstream_tell_size(BitstreamContext *s)
  *        larger than the actual read bits because some optimized bitstream
  *        readers read 32 or 64 bits at once and could read over the end
  * @param byte_size the size of the buffer in bytes
- * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow.
- */
+ * @return 0 on success, AVERROR_INVALIDDATA if the buffer_size would overflow */
 static inline int bitstream_init8(BitstreamContext *s, const uint8_t *buffer,
                                   int byte_size)
 {
@@ -330,7 +327,9 @@ static inline int bitstream_init8(BitstreamContext *s, const uint8_t *buffer,
     return bitstream_init(s, buffer, byte_size * 8);
 }
 
-/* Skip bits to a byte boundary */
+/**
+ * @param s BitstreamContext
+ * Skip bits to a byte boundary. */
 static inline const uint8_t *bitstream_align(BitstreamContext *s)
 {
     unsigned n = -bitstream_tell(s) & 7;
@@ -340,11 +339,16 @@ static inline const uint8_t *bitstream_align(BitstreamContext *s)
 }
 
 /**
- * Return the LUT element for the given bitstream configuration.
- */
-static inline int set_idx(BitstreamContext *s, int code, int *n, int *nb_bits, VLC_TYPE (*table)[2])
+ * @param s BitstreamContext
+ * @param code an offset to the sub-table of LUT
+ * @param n number of bits to examine
+ * @param nb_bits used to look-up the code
+ * @param table Xine table
+ * @return the LUT element for the given bitstream configuration */
+static inline int set_idx(BitstreamContext *s, int code, int *n, int *nb_bits,
+                          VLC_TYPE (*table)[2])
 {
-    unsigned int idx;
+    unsigned idx;
 
     *nb_bits = -*n;
     idx = bitstream_peek(s, *nb_bits) + code;
@@ -362,20 +366,16 @@ static inline int set_idx(BitstreamContext *s, int code, int *n, int *nb_bits, V
  *                  = (max_vlc_length + bits - 1) / bits
  * If the vlc code is invalid and max_depth=1, then no bits will be removed.
  * If the vlc code is invalid and max_depth>1, then the number of bits removed
- * is undefined.
- */
+ * is undefined. */
 static av_always_inline int bitstream_read_vlc(BitstreamContext *s, VLC_TYPE (*table)[2],
                                                int bits, int max_depth)
 {
-    int code, n, nb_bits;
-    unsigned int idx;
-
-    idx = bitstream_peek(s, bits);
-    code = table[idx][0];
-    n = table[idx][1];
+    int nb_bits;
+    unsigned idx = bitstream_peek(s, bits);
+    int code         = table[idx][0];
+    int              = table[idx][1];
 
     if (max_depth > 1 && n < 0) {
-
         bitstream_skip(s, bits);
         code = set_idx(s, code, &n, &nb_bits, table);
         if (max_depth > 2 && n < 0) {
@@ -391,7 +391,7 @@ static av_always_inline int bitstream_read_vlc(BitstreamContext *s, VLC_TYPE (*t
 #define BITSTREAM_RL_VLC(level, run, bb, table, bits, max_depth) \
     do {                                                         \
         int n, nb_bits;                                          \
-        unsigned int index;                                      \
+        unsigned index;                                          \
                                                                  \
         index = bitstream_peek(bb, bits);                        \
         level = table[index].level;                              \
@@ -419,20 +419,20 @@ static av_always_inline int bitstream_read_vlc(BitstreamContext *s, VLC_TYPE (*t
     } while (0)
 
 /**
- * Return decoded truncated unary code for the values 0, 1, 2.
+ * @param bb BitstreamContext
+ * @return decoded truncated unary code for the values 0, 1, 2.
  */
 static inline int bitstream_decode012(BitstreamContext *bb)
 {
-    unsigned n;
-    n = bitstream_read_bit(bb);
-    if (n == 0)
+    if (!bitstream_read_bit(bb))
         return 0;
     else
         return bitstream_read_bit(bb) + 1;
 }
 
 /**
- * Return decoded truncated unary code for the values 2, 1, 0.
+ * @param bb BitstreamContext
+ * @return decoded truncated unary code for the values 2, 1, 0.
  */
 static inline int bitstream_decode210(BitstreamContext *bb)
 {
@@ -443,7 +443,8 @@ static inline int bitstream_decode210(BitstreamContext *bb)
 }
 
 /**
- * Return the number of the bits left in a buffer.
+ * @param bb BitstreamContext
+ * @return the number of the bits left in a buffer.
  */
 static inline int bitstream_bits_left(BitstreamContext *bb)
 {