doxy: provide a start page and document libavutil

Introduce a basic layout, the subpages are currently left empty.

Split libavutil in multiple groups as example of the structure

19 files changed, 377 insertions, 16 deletions

diff --git a/libavutil/adler32.h b/libavutil/adler32.h
index 913db2d0b6..a8ff6f9d41 100644
--- a/libavutil/adler32.h
+++ b/libavutil/adler32.h
@@ -25,6 +25,7 @@
 #include "attributes.h"
 
 /**
+ * @ingroup lavu_crypto
  * Calculate the Adler32 checksum of a buffer.
  *
  * Passing the return value to a subsequent av_adler32_update() call
diff --git a/libavutil/aes.h b/libavutil/aes.h
index 6e5d320487..cf7b462092 100644
--- a/libavutil/aes.h
+++ b/libavutil/aes.h
@@ -23,6 +23,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup lavu_aes AES
+ * @ingroup lavu_crypto
+ * @{
+ */
+
 extern const int av_aes_size;
 
 struct AVAES;
@@ -44,4 +50,8 @@ int av_aes_init(struct AVAES *a, const uint8_t *key, int key_bits, int decrypt);
  */
 void av_aes_crypt(struct AVAES *a, uint8_t *dst, const uint8_t *src, int count, uint8_t *iv, int decrypt);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_AES_H */
diff --git a/libavutil/audioconvert.h b/libavutil/audioconvert.h
index e37a2e84c1..1c5cfa0a8e 100644
--- a/libavutil/audioconvert.h
+++ b/libavutil/audioconvert.h
@@ -29,7 +29,15 @@
  * audio conversion routines
  */
 
-/* Audio channel masks */
+/**
+ * @addtogroup lavu_audio
+ * @{
+ */
+
+/**
+ * @defgroup channel_masks Audio channel masks
+ * @{
+ */
 #define AV_CH_FRONT_LEFT             0x00000001
 #define AV_CH_FRONT_RIGHT            0x00000002
 #define AV_CH_FRONT_CENTER           0x00000004
@@ -56,7 +64,11 @@
     to be the native codec channel order. */
 #define AV_CH_LAYOUT_NATIVE          0x8000000000000000LL
 
-/* Audio channel convenience macros */
+/**
+ * @}
+ * @defgroup channel_mask_c Audio channel convenience macros
+ * @{
+ * */
 #define AV_CH_LAYOUT_MONO              (AV_CH_FRONT_CENTER)
 #define AV_CH_LAYOUT_STEREO            (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT)
 #define AV_CH_LAYOUT_2_1               (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER)
@@ -74,6 +86,10 @@
 #define AV_CH_LAYOUT_STEREO_DOWNMIX    (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT)
 
 /**
+ * @}
+ */
+
+/**
  * Return a channel layout id that matches name, 0 if no match.
  */
 int64_t av_get_channel_layout(const char *name);
@@ -92,4 +108,8 @@ void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, int6
  */
 int av_get_channel_layout_nb_channels(int64_t channel_layout);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_AUDIOCONVERT_H */
diff --git a/libavutil/avstring.h b/libavutil/avstring.h
index 6988f0e3e8..35b3d46c03 100644
--- a/libavutil/avstring.h
+++ b/libavutil/avstring.h
@@ -25,6 +25,11 @@
 #include "attributes.h"
 
 /**
+ * @addtogroup lavu_string
+ * @{
+ */
+
+/**
  * Return non-zero if pfx is a prefix of str. If it is, *ptr is set to
  * the address of the first character in str after the prefix.
  *
@@ -72,7 +77,7 @@ char *av_stristr(const char *haystack, const char *needle);
  * @param size size of destination buffer
  * @return the length of src
  *
- * WARNING: since the return value is the length of src, src absolutely
+ * @warning since the return value is the length of src, src absolutely
  * _must_ be a properly 0-terminated string, otherwise this will read beyond
  * the end of the buffer and possibly crash.
  */
@@ -90,9 +95,9 @@ size_t av_strlcpy(char *dst, const char *src, size_t size);
  * @param size size of destination buffer
  * @return the total length of src and dst
  *
- * WARNING: since the return value use the length of src and dst, these absolutely
- * _must_ be a properly 0-terminated strings, otherwise this will read beyond
- * the end of the buffer and possibly crash.
+ * @warning since the return value use the length of src and dst, these
+ * absolutely _must_ be a properly 0-terminated strings, otherwise this
+ * will read beyond the end of the buffer and possibly crash.
  */
 size_t av_strlcat(char *dst, const char *src, size_t size);
 
@@ -153,14 +158,18 @@ static inline int av_tolower(int c)
 
 /*
  * Locale independent case-insensitive compare.
- * Note: This means only ASCII-range characters are case-insensitive
+ * @note This means only ASCII-range characters are case-insensitive
  */
 int av_strcasecmp(const char *a, const char *b);
 
 /**
  * Locale independent case-insensitive compare.
- * Note: This means only ASCII-range characters are case-insensitive
+ * @note This means only ASCII-range characters are case-insensitive
  */
 int av_strncasecmp(const char *a, const char *b, size_t n);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_AVSTRING_H */
diff --git a/libavutil/avutil.h b/libavutil/avutil.h
index 436f79b82d..659a10f070 100644
--- a/libavutil/avutil.h
+++ b/libavutil/avutil.h
@@ -26,6 +26,95 @@
  * external API header
  */
 
+/**
+ * @mainpage
+ *
+ * @section libav_intro Introduction
+ *
+ * This document describe the usage of the different libraries
+ * provided by Libav.
+ *
+ * @li @subpage libavcodec  encoding/decoding library
+ * @li @subpage libavfilter graph based frame editing library
+ * @li @subpage libavformat I/O and muxing/demuxing library
+ * @li @ref lavu "libavutil" common utility library
+ * @li @subpage libpostproc post processing library
+ * @li @subpage libswscale  color conversion and scaling library
+ *
+ */
+
+/**
+ * @defgroup lavu Common utility functions
+ *
+ * @brief
+ * libavutil contains the code shared across all the other Libav
+ * libraries
+ *
+ * @note In order to use the functions provided by avutil you must include
+ * the specific header.
+ *
+ * @{
+ *
+ * @defgroup lavu_crypto Crypto and Hashing
+ *
+ * @{
+ * @}
+ *
+ * @defgroup lavu_math Maths
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_string String Manipulation
+ *
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_mem Memory Management
+ *
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_data Data Structures
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_audio Audio related
+ *
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_error Error Codes
+ *
+ * @{
+ *
+ * @}
+ *
+ * @defgroup lavu_misc Other
+ *
+ * @{
+ *
+ * @defgroup lavu_internal Internal
+ *
+ * Not exported functions, for internal usage only
+ *
+ * @{
+ *
+ * @}
+ */
+
+
+/**
+ * @defgroup preproc_misc Preprocessor String Macros
+ *
+ * String manipulation macros
+ *
+ * @{
+ */
 
 #define AV_STRINGIFY(s)         AV_TOSTRING(s)
 #define AV_TOSTRING(s) #s
@@ -35,10 +124,34 @@
 
 #define AV_PRAGMA(s) _Pragma(#s)
 
+/**
+ * @}
+ */
+
+/**
+ * @defgroup version_utils Library Version Macros
+ *
+ * Useful to check and match library version in order to maintain
+ * backward compatibility.
+ *
+ * @{
+ */
+
 #define AV_VERSION_INT(a, b, c) (a<<16 | b<<8 | c)
 #define AV_VERSION_DOT(a, b, c) a ##.## b ##.## c
 #define AV_VERSION(a, b, c) AV_VERSION_DOT(a, b, c)
 
+/**
+ * @}
+ *
+ * @defgroup lavu_ver Version and Build diagnostics
+ *
+ * Macros and function useful to check at compiletime and at runtime
+ * which version of libavutil is in use.
+ *
+ * @{
+ */
+
 #define LIBAVUTIL_VERSION_MAJOR 51
 #define LIBAVUTIL_VERSION_MINOR 16
 #define LIBAVUTIL_VERSION_MICRO  0
@@ -54,8 +167,16 @@
 #define LIBAVUTIL_IDENT         "Lavu" AV_STRINGIFY(LIBAVUTIL_VERSION)
 
 /**
+ * @}
+ *
+ * @defgroup depr_guards Deprecation guards
  * Those FF_API_* defines are not part of public API.
  * They may change, break or disappear at any time.
+ *
+ * They are used mostly internally to mark code that will be removed
+ * on the next major version.
+ *
+ * @{
  */
 #ifndef FF_API_GET_BITS_PER_SAMPLE_FMT
 #define FF_API_GET_BITS_PER_SAMPLE_FMT (LIBAVUTIL_VERSION_MAJOR < 52)
@@ -71,6 +192,15 @@
 #endif
 
 /**
+ * @}
+ */
+
+/**
+ * @addtogroup lavu_ver
+ * @{
+ */
+
+/**
  * Return the LIBAVUTIL_VERSION_INT constant.
  */
 unsigned avutil_version(void);
@@ -85,16 +215,35 @@ const char *avutil_configuration(void);
  */
 const char *avutil_license(void);
 
+/**
+ * @}
+ */
+
+/**
+ * @addtogroup lavu_media Media Type
+ * @brief Media Type
+ */
+
 enum AVMediaType {
-    AVMEDIA_TYPE_UNKNOWN = -1,
+    AVMEDIA_TYPE_UNKNOWN = -1,  ///< Usually treated as AVMEDIA_TYPE_DATA
     AVMEDIA_TYPE_VIDEO,
     AVMEDIA_TYPE_AUDIO,
-    AVMEDIA_TYPE_DATA,
+    AVMEDIA_TYPE_DATA,          ///< Opaque data information usually continuous
     AVMEDIA_TYPE_SUBTITLE,
-    AVMEDIA_TYPE_ATTACHMENT,
+    AVMEDIA_TYPE_ATTACHMENT,    ///< Opaque data information usually sparse
     AVMEDIA_TYPE_NB
 };
 
+/**
+ * @defgroup lavu_const Constants
+ * @{
+ *
+ * @defgroup lavu_enc Encoding specific
+ *
+ * @note those definition should move to avcodec
+ * @{
+ */
+
 #define FF_LAMBDA_SHIFT 7
 #define FF_LAMBDA_SCALE (1<<FF_LAMBDA_SHIFT)
 #define FF_QP2LAMBDA 118 ///< factor to convert from H.263 QP to lambda
@@ -102,10 +251,46 @@ enum AVMediaType {
 
 #define FF_QUALITY_SCALE FF_LAMBDA_SCALE //FIXME maybe remove
 
+/**
+ * @}
+ * @defgroup lavu_time Timestamp specific
+ *
+ * Libav internal timebase and timestamp definitions
+ *
+ * @{
+ */
+
+/**
+ * @brief Undefined timestamp value
+ *
+ * Usually reported by demuxer that work on containers that do not provide
+ * either pts or dts.
+ */
+
 #define AV_NOPTS_VALUE          INT64_C(0x8000000000000000)
+
+/**
+ * Internal time base represented as integer
+ */
+
 #define AV_TIME_BASE            1000000
+
+/**
+ * Internal time base represented as fractional value
+ */
+
 #define AV_TIME_BASE_Q          (AVRational){1, AV_TIME_BASE}
 
+/**
+ * @}
+ * @}
+ * @defgroup lavu_picture Image related
+ *
+ * AVPicture types, pixel formats and basic image planes manipulation.
+ *
+ * @{
+ */
+
 enum AVPictureType {
     AV_PICTURE_TYPE_I = 1, ///< Intra
     AV_PICTURE_TYPE_P,     ///< Predicted
@@ -125,7 +310,16 @@ enum AVPictureType {
  */
 char av_get_picture_type_char(enum AVPictureType pict_type);
 
+/**
+ * @}
+ */
+
 #include "common.h"
 #include "error.h"
 
+/**
+ * @}
+ * @}
+ */
+
 #endif /* AVUTIL_AVUTIL_H */
diff --git a/libavutil/base64.h b/libavutil/base64.h
index 96c0a4a41e..4750cf5c72 100644
--- a/libavutil/base64.h
+++ b/libavutil/base64.h
@@ -24,6 +24,13 @@
 #include <stdint.h>
 
 /**
+ * @defgroup lavu_base64 Base64
+ * @ingroup lavu_crypto
+ * @{
+ */
+
+
+/**
  * Decode a base64-encoded string.
  *
  * @param out      buffer for decoded data
@@ -51,4 +58,8 @@ char *av_base64_encode(char *out, int out_size, const uint8_t *in, int in_size);
  */
 #define AV_BASE64_SIZE(x)  (((x)+2) / 3 * 4 + 1)
 
+ /**
+  * @}
+  */
+
 #endif /* AVUTIL_BASE64_H */
diff --git a/libavutil/dict.h b/libavutil/dict.h
index b0061c8475..6e28b61406 100644
--- a/libavutil/dict.h
+++ b/libavutil/dict.h
@@ -26,7 +26,11 @@
 #define AVUTIL_DICT_H
 
 /**
- * @defgroup dict_api Public Dictionary API
+ * @addtogroup lavu_dict AVDictionary
+ * @ingroup lavu_data
+ *
+ * @brief Simple key:value store
+ *
  * @{
  * Dictionaries are used for storing key:value pairs. To create
  * an AVDictionary, simply pass an address of a NULL pointer to
@@ -52,7 +56,6 @@
  * av_dict_free(&d);
  * @endcode
  *
- * @}
  */
 
 #define AV_DICT_MATCH_CASE      1
@@ -111,4 +114,8 @@ void av_dict_copy(AVDictionary **dst, AVDictionary *src, int flags);
  */
 void av_dict_free(AVDictionary **m);
 
+/**
+ * @}
+ */
+
 #endif // AVUTIL_DICT_H
diff --git a/libavutil/error.h b/libavutil/error.h
index ba12d2bfae..8ed77342ef 100644
--- a/libavutil/error.h
+++ b/libavutil/error.h
@@ -27,6 +27,13 @@
 #include <errno.h>
 #include "avutil.h"
 
+/**
+ * @addtogroup lavu_error
+ *
+ * @{
+ */
+
+
 /* error handling */
 #if EDOM > 0
 #define AVERROR(e) (-(e))   ///< Returns a negative error code from a POSIX error code, to return from library functions.
@@ -65,4 +72,8 @@
  */
 int av_strerror(int errnum, char *errbuf, size_t errbuf_size);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_ERROR_H */
diff --git a/libavutil/imgutils.h b/libavutil/imgutils.h
index 6017a70f71..3815a49ae4 100644
--- a/libavutil/imgutils.h
+++ b/libavutil/imgutils.h
@@ -22,6 +22,9 @@
 /**
  * @file
  * misc image utilities
+ *
+ * @addtogroup lavu_picture
+ * @{
  */
 
 #include "avutil.h"
@@ -127,4 +130,9 @@ int av_image_check_size(unsigned int w, unsigned int h, int log_offset, void *lo
 
 int ff_set_systematic_pal2(uint32_t pal[256], enum PixelFormat pix_fmt);
 
+/**
+ * @}
+ */
+
+
 #endif /* AVUTIL_IMGUTILS_H */
diff --git a/libavutil/intmath.h b/libavutil/intmath.h
index 3325975556..e6a2e102c4 100644
--- a/libavutil/intmath.h
+++ b/libavutil/intmath.h
@@ -25,6 +25,11 @@
 #include "config.h"
 #include "attributes.h"
 
+/**
+ * @addtogroup lavu_internal
+ * @{
+ */
+
 extern const uint32_t ff_inverse[257];
 
 #if   ARCH_ARM
@@ -76,4 +81,7 @@ static inline av_const unsigned int ff_sqrt(unsigned int a)
     return b - (a < b * b);
 }
 
+/**
+ * @}
+ */
 #endif /* AVUTIL_INTMATH_H */
diff --git a/libavutil/lzo.h b/libavutil/lzo.h
index be86bba6bc..b4c71c0933 100644
--- a/libavutil/lzo.h
+++ b/libavutil/lzo.h
@@ -22,6 +22,13 @@
 #ifndef AVUTIL_LZO_H
 #define AVUTIL_LZO_H
 
+/**
+ * @defgroup lavu_lzo LZO
+ * @ingroup lavu_crypto
+ *
+ * @{
+ */
+
 #include <stdint.h>
 
 /** @name Error flags returned by av_lzo1x_decode
@@ -63,4 +70,8 @@ int av_lzo1x_decode(void *out, int *outlen, const void *in, int *inlen);
  */
 void av_memcpy_backptr(uint8_t *dst, int back, int cnt);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_LZO_H */
diff --git a/libavutil/mathematics.h b/libavutil/mathematics.h
index 35494bb391..0b072ebe63 100644
--- a/libavutil/mathematics.h
+++ b/libavutil/mathematics.h
@@ -57,6 +57,12 @@
 #define INFINITY       (1.0/0.0)
 #endif
 
+/**
+ * @addtogroup lavu_math
+ * @{
+ */
+
+
 enum AVRounding {
     AV_ROUND_ZERO     = 0, ///< Round toward zero.
     AV_ROUND_INF      = 1, ///< Round away from zero.
@@ -109,4 +115,8 @@ int av_compare_ts(int64_t ts_a, AVRational tb_a, int64_t ts_b, AVRational tb_b);
  */
 int64_t av_compare_mod(uint64_t a, uint64_t b, uint64_t mod);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_MATHEMATICS_H */
diff --git a/libavutil/md5.h b/libavutil/md5.h
index c178bbb4d5..1412ee2401 100644
--- a/libavutil/md5.h
+++ b/libavutil/md5.h
@@ -23,6 +23,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup lavu_md5 MD5
+ * @ingroup lavu_crypto
+ * @{
+ */
+
 extern const int av_md5_size;
 
 struct AVMD5;
@@ -32,5 +38,9 @@ void av_md5_update(struct AVMD5 *ctx, const uint8_t *src, const int len);
 void av_md5_final(struct AVMD5 *ctx, uint8_t *dst);
 void av_md5_sum(uint8_t *dst, const uint8_t *src, const int len);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_MD5_H */
 
diff --git a/libavutil/mem.h b/libavutil/mem.h
index e14e8d038c..cd8490b2da 100644
--- a/libavutil/mem.h
+++ b/libavutil/mem.h
@@ -29,6 +29,12 @@
 #include "attributes.h"
 #include "avutil.h"
 
+/**
+ * @addtogroup lavu_mem
+ * @{
+ */
+
+
 #if defined(__ICC) && _ICC < 1200 || defined(__SUNPRO_C)
     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (n))) v
     #define DECLARE_ASM_CONST(n,t,v)    const t __attribute__ ((aligned (n))) v
@@ -123,4 +129,8 @@ char *av_strdup(const char *s) av_malloc_attrib;
  */
 void av_freep(void *ptr);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_MEM_H */
diff --git a/libavutil/opt.h b/libavutil/opt.h
index 6182326af2..19549408e2 100644
--- a/libavutil/opt.h
+++ b/libavutil/opt.h
@@ -34,6 +34,7 @@
 
 /**
  * @defgroup avoptions AVOptions
+ * @ingroup lavu_data
  * @{
  * AVOptions provide a generic system to declare options on arbitrary structs
  * ("objects"). An option can have a help text, a type and a range of possible
@@ -212,7 +213,6 @@
  * filled with option as a parameter. This allows to set some options
  * that cannot be set otherwise, since e.g. the input file format is not known
  * before the file is actually opened.
- * @}
  */
 
 enum AVOptionType{
@@ -585,6 +585,7 @@ int av_opt_get_double(void *obj, const char *name, int search_flags, double
 int av_opt_get_q     (void *obj, const char *name, int search_flags, AVRational *out_val);
 /**
  * @}
+ * @}
  */
 
 #endif /* AVUTIL_OPT_H */
diff --git a/libavutil/random_seed.h b/libavutil/random_seed.h
index 5bfeb8b835..b1fad13d07 100644
--- a/libavutil/random_seed.h
+++ b/libavutil/random_seed.h
@@ -22,6 +22,10 @@
 #define AVUTIL_RANDOM_SEED_H
 
 #include <stdint.h>
+/**
+ * @addtogroup lavu_crypto
+ * @{
+ */
 
 /**
  * Get random data.
@@ -33,4 +37,8 @@
  */
 uint32_t av_get_random_seed(void);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_RANDOM_SEED_H */
diff --git a/libavutil/rational.h b/libavutil/rational.h
index a4871148bd..0ec18ec969 100644
--- a/libavutil/rational.h
+++ b/libavutil/rational.h
@@ -33,6 +33,11 @@
 #include "attributes.h"
 
 /**
+ * @addtogroup lavu_math
+ * @{
+ */
+
+/**
  * rational number numerator/denominator
  */
 typedef struct AVRational{
@@ -132,4 +137,8 @@ int av_nearer_q(AVRational q, AVRational q1, AVRational q2);
  */
 int av_find_nearest_q_idx(AVRational q, const AVRational* q_list);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_RATIONAL_H */
diff --git a/libavutil/sha.h b/libavutil/sha.h
index df261fa4b5..8350954c4b 100644
--- a/libavutil/sha.h
+++ b/libavutil/sha.h
@@ -23,6 +23,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup lavu_sha SHA
+ * @ingroup lavu_crypto
+ * @{
+ */
+
 extern const int av_sha_size;
 
 struct AVSHA;
@@ -53,4 +59,8 @@ void av_sha_update(struct AVSHA* context, const uint8_t* data, unsigned int len)
  */
 void av_sha_final(struct AVSHA* context, uint8_t *digest);
 
+/**
+ * @}
+ */
+
 #endif /* AVUTIL_SHA_H */
diff --git a/libavutil/tree.h b/libavutil/tree.h
index 9115e2fec1..59ea01dbdb 100644
--- a/libavutil/tree.h
+++ b/libavutil/tree.h
@@ -21,14 +21,24 @@
 /**
  * @file
  * A tree container.
- * Insertion, removal, finding equal, largest which is smaller than and
- * smallest which is larger than, all have O(log n) worst case complexity.
  * @author Michael Niedermayer <michaelni@gmx.at>
  */
 
 #ifndef AVUTIL_TREE_H
 #define AVUTIL_TREE_H
 
+/**
+ * @addtogroup lavu_tree AVTree
+ * @ingroup lavu_data
+ *
+ * Low complexity tree container
+ *
+ * Insertion, removal, finding equal, largest which is smaller than and
+ * smallest which is larger than, all have O(log n) worst case complexity.
+ * @{
+ */
+
+
 struct AVTreeNode;
 extern const int av_tree_node_size;
 
@@ -91,5 +101,8 @@ void av_tree_destroy(struct AVTreeNode *t);
  */
 void av_tree_enumerate(struct AVTreeNode *t, void *opaque, int (*cmp)(void *opaque, void *elem), int (*enu)(void *opaque, void *elem));
 
+/**
+ * @}
+ */
 
 #endif /* AVUTIL_TREE_H */