On Wed, Sep 18, 2013 at 3:30 PM, Luca Barbato <[email protected]> wrote:
> Provide some information for every function and add a group.
Maybe the function documentation and group addition could be split in two?
> ---
>
> Please send updated patches instead of reviews.
> Note:
> @see is immediately after the body on purpose, do not move it down,
> looks much worse on the html output otherwise.
>
> libavutil/avutil.h | 6 ++++
> libavutil/log.h | 98
> ++++++++++++++++++++++++++++++++++++++++++++++++++----
> 2 files changed, 98 insertions(+), 6 deletions(-)
>
> diff --git a/libavutil/avutil.h b/libavutil/avutil.h
> index ddb34a1..6bb5510 100644
> --- a/libavutil/avutil.h
> +++ b/libavutil/avutil.h
> @@ -127,6 +127,12 @@
> *
> * @}
> *
> + * @defgroup lavu_log Logging Facility
> + *
> + * @{
> + *
> + * @}
> + *
> * @defgroup lavu_misc Other
> *
> * @{
> diff --git a/libavutil/log.h b/libavutil/log.h
> index 7b17330..5692bd5 100644
> --- a/libavutil/log.h
> +++ b/libavutil/log.h
> @@ -89,8 +89,19 @@ typedef struct AVClass {
> const struct AVClass* (*child_class_next)(const struct AVClass *prev);
> } AVClass;
>
> -/* av_log API */
> +/**
> + * @addtogroup lavu_log
> + *
> + * @{
> + *
> + * @defgroup lavu_log_constants Logging Constants
> + *
> + * @{
> + */
>
> +/**
> + * No output.
> + */
> #define AV_LOG_QUIET -8
>
> /**
> @@ -117,7 +128,14 @@ typedef struct AVClass {
> */
> #define AV_LOG_WARNING 24
>
> +/**
> + * Standard information
> + */
> #define AV_LOG_INFO 32
> +
> +/**
> + * Detailed information, usually not interesting.
> + */
> #define AV_LOG_VERBOSE 40
>
> /**
> @@ -126,10 +144,15 @@ typedef struct AVClass {
> #define AV_LOG_DEBUG 48
>
> /**
> + * @}
> + */
> +
> +/**
> * Send the specified message to the log if the level is less than or equal
> * to the current av_log_level. By default, all logging messages are sent to
> - * stderr. This behavior can be altered by setting a different av_vlog
> callback
> + * stderr. This behavior can be altered by setting a different logging
> callback
> * function.
> + * @see av_log_set_callback
> *
> * @param avcl A pointer to an arbitrary struct of which the first field is a
> * pointer to an AVClass struct.
> @@ -137,15 +160,74 @@ typedef struct AVClass {
> * higher importance.
> * @param fmt The format string (printf-compatible) that specifies how
> * subsequent arguments are converted to output.
> - * @see av_vlog
> */
> void av_log(void *avcl, int level, const char *fmt, ...) av_printf_format(3,
> 4);
>
> -void av_vlog(void *avcl, int level, const char *fmt, va_list);
> +
> +/**
> + * Send the specified message to the log if the level is less than or equal
> + * to the current av_log_level. By default, all logging messages are sent to
> + * stderr. This behavior can be altered by setting a different logging
> callback
> + * function.
May I propose "Log the specified message if the log level is less than ..."
> + * @see av_log_set_callback
> + *
> + * @param avcl A pointer to an arbitrary struct of which the first field is a
> + * pointer to an AVClass struct.
How about "A pointer to an arbitrary struct whose first field is a
pointer to an AVClass struct"
> + * @param level The importance level of the message, lower values signifying
> + * higher importance.
> + * @param fmt The format string (printf-compatible) that specifies how
> + * subsequent arguments are converted to output.
> + * @param vl The arguments referenced by the format string.
> + */
> +void av_vlog(void *avcl, int level, const char *fmt, va_list vl);
> +
> +/**
> + * Get the current log level
> + * @see lavu_log_constants
> + *
> + * @return Current log level
> + */
> int av_log_get_level(void);
> -void av_log_set_level(int);
> -void av_log_set_callback(void (*)(void*, int, const char*, va_list));
> +
> +/**
> + * Set the log level
> + * @see lavu_log_constants
> + *
> + * @param level Logging level
> + */
> +void av_log_set_level(int level);
> +
> +/**
> + * Set the logging callback
> + *
> + * @see av_log_default_callback
> + *
> + * @param callback A logging function with a signature compatible.
> + */
> +void av_log_set_callback(void (*callback)(void*, int, const char*, va_list));
> +
> +/**
> + * Default logging callback
> + *
> + * It prints to stderr the message, optionally colorizing them.
This function prints the message to stderr, optionally colorizing it.
> + *
> + * @param avcl A pointer to an arbitrary struct of which the first field is a
> + * pointer to an AVClass struct.
A pointer to an arbitrary struct of which whose first field is a
pointer to an AVClass struct
> + * @param level The importance level of the message, lower values signifying
> + * higher importance.
> + * @param fmt The format string (printf-compatible) that specifies how
> + * subsequent arguments are converted to output.
> + * @param ap The arguments referenced by the format string.
> + */
> void av_log_default_callback(void* ptr, int level, const char* fmt, va_list
> vl);
> +
> +/**
> + * Return the context name
> + *
> + * @param ctx The AVClass context
> + *
> + * @return The AVClass class_name
> + */
> const char* av_default_item_name(void* ctx);
>
> /**
> @@ -170,4 +252,8 @@ const char* av_default_item_name(void* ctx);
> #define AV_LOG_SKIP_REPEATED 1
> void av_log_set_flags(int arg);
>
> +/**
> + * @}
> + */
> +
> #endif /* AVUTIL_LOG_H */
Ok for the rest I think.
Vittorio
_______________________________________________
libav-devel mailing list
[email protected]
https://lists.libav.org/mailman/listinfo/libav-devel
