[FFmpeg-devel] [PATCH 02/12 v2] doc: Explain the various logevel settings

[Stefano Sabatini]

On date Sunday 2013-03-31 19:17:29 +0200, Michael Niedermayer encoded:
> On Sun, Mar 31, 2013 at 01:04:20PM -0400, Derek Buitenhuis wrote:
> > Signed-off-by: Derek Buitenhuis <derek.buitenhuis at gmail.com>
> > ---
> >  doc/avtools-common-opts.texi |   13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> > 
> > diff --git a/doc/avtools-common-opts.texi b/doc/avtools-common-opts.texi
> > index 111812d..b131f89 100644
> > --- a/doc/avtools-common-opts.texi
> > +++ b/doc/avtools-common-opts.texi
> > @@ -120,13 +120,26 @@ Set the logging level used by the library.
> >  @var{loglevel} is a number or a string containing one of the following values:
> >  @table @samp
> >  @item quiet
> > +Show nothing at all; be silent.

> >  @item panic
> > +Only show errors which could affect the state of a user's system. This is
> > +not actually used for anything currently.

"errors which could affect the state of a user's system"

uhmmm, this is very vague. Also, from a technical point of view even a
bit change is affecting the state of the user's system. I still
suggest to mirror the log.h docs, and say something like:

Only show fatal errors which would lead to the process crash. This is
not actually used for anything currently.

> >  @item fatal
> > +Only show fatal errors. These are errors after which the process absolutely
> > +cannot continue after.

> >  @item error
> > +Show all errors and panics, including ones which can be recovered from. 

Nit: Show all errors, including...

"panics" sounds weird and scary, since you don't define what "panics"
are.

> >  @item warning
> > +Show all warnings and errors. Any message related to possibly
> > +incorrect or unexpected events will be shown.

> >  @item info
> > +Show information from libavcodec, libavformat, and other libraries during
> > +processing, if they provide it. This is in addition to warnings and errors.
> > +This is the default value.

After re-reading, it's weird to mention the libraries here, this
implicitly assumes that the other log levels don't deal with
libraries. I suggest this simplification:

Show informative messages during processing. This is in addition to
warnings and errors. This is the default value.

> >  @item verbose
> > +Same as @code{info}, except more verbose.
> >  @item debug
> > +Show everything, including debugging information.
> >  @end table

LGTM otherwise, thanks.
-- 
FFmpeg = Formidable and Faithful Merciful Pitiful Emblematic Gargoyle