[FFmpeg-devel] [PATCH 1/2] doc/Makefile: scan all files, including .c files, for Doxygen

[Timothy Gu]

On Nov 3, 2013 6:22 AM, "Michael Niedermayer" <michaelni at gmx.at> wrote:
>
> On Sun, Nov 03, 2013 at 12:19:01PM +0100, Stefano Sabatini wrote:
> > On date Saturday 2013-11-02 21:12:45 +0100, Michael Niedermayer encoded:
> > > On Sat, Nov 02, 2013 at 12:54:31PM -0700, Timothy Gu wrote:
> > [...]
> > > > 1. The 2 types of Doxygen should be clearly documented on
> > > > website/documentation and also how to generate them.
> > >
> > > yes
> > >
> > >
> > > >
> > > > 2a. The Doxygen on the website should be generated by `make
apidoc`, not
> > > > the current form (with the other patch in the patch set which fixes
style
> > > > of course).
> > > > 2b. An alternative solution to 2a is to change the section name on
the
> > > > website from "API doc" to "Doxygen doc for FFmpeg developers", but
this
> > > > method should not be used as not many FFmpeg devs use Doxygen AFAIK.
> > >
> > > 2c. build both variants on the server (though i dont volunteer
> > > setting that up)
> > >
> > >
> > > >
> > > > 3. Optionally add another build rule in Makefile.
> > >
> > > this could make sense, anyone else has oppinons about that or what
> > > exact command the 2nd rule should have ?
> >
> > I'd say that our currently generated Doxygen is confused at best.
>
> thats the result of it being practically unmaintained

And the lack of Doxygen users/developers in our community.

>
>
> > What's the supposed use of modules, what's the supposed use of
> > "namespace"?
> >
> > Also, but unrelated, library definitions are a bit funny, for example
> > I didn't know libavfilter was a "graph-based frame editing library",
> > which is a pretty wild interpretation of what I though libavfilter was
> > all about.

Well, the definition IMO is accurate enough, but I think it would make more
sense to just say "libavfilter A/V filtering library".

> >
> > We should probably get rid of namespace altogethers, and try to give a

Yeah

> > reasonable definition of "module". For a C project each "module"
> > comprises a file, but for example here:

Not exactly. For example, libopus.c, libopus.h, libopusenc.c libopusdec.c
are all IMO in the same "Module".

> > http://ffmpeg.org/doxygen/trunk/group__lavu.html
> >
> > I can only see the version.h file.

version.h should be in lavu/versioning & diagnostic, and a bulk of the file
is already in there. That's the freak thing about Doxygen: it has two kinds
of modules: @file module and function (or in this case, macro) modules.
Here, the macro modules are already good, but the @file module messed up
the whole thing.

> >
>
> > As I see it, "modules" as currently defined are an arbitrary
> > schizofrenic half-baked attempt to provide some form of
> > classification/grouping.
>
> that would probably be an accurate definition of the current state
>
>
> >
> > For example in case of libavutil:
> >
> >       Crypto and Hashing
> >       Maths
> >       String Manipulation
> >       Memory Management
>
> >       Data Structures
>
> Generic Data Structures
>
>
> >       Audio related
> >       Error Codes
> >       Logging Facility
> >       Other
> >
> > Audio related comprises several C files and seems too much
> > coarse-grained, same for Data Structures, not to talk about "Other".

> >
> > Things are much worse in the case of libavcodec:
> >       Decoding
> >       Encoding
> >       Codecs
> >       Internal
> >       Core functions/structures.
> >       Basic definitions, functions for querying libavcodec
capabilities, allocating core structures, etc.
> >       Utility functions
> >       Miscellaneous utility functions related to both encoding and
decoding (or neither).
>
> random braindump:
>
> Bitstream
> Arithmetic / Range coding
> Linear transforms (DCT, FFT, Wavelets)
> Motion Compensation
> Motion Estimation
> Rate control
> Quantization / Dequantization
> Prediction
> Error concealment
> Individual codecs / codec specific code
>
>
> [...]
> > BTW we should be probably get rid of all the imported trash from other
> > projects and from the scripts, such as:
> > http://ffmpeg.org/doxygen/trunk/namespacenormalize.html
>
> that page is confusing
>
>
> >
> > ...
> >
> > Much to the point, about the API to generate. I don't think developers
> > will make any use of internal API, so we should focus instead on
> > giving a sane display of the public API.
> >
>
> > Indeed per-policy we don't require developers to document internal API
> > (and for a reason), but they are de-facto required to describe the
> > public API (and again for a reason).
>
> I think its very important to document internal API (not arguing about
> doxygen here but rather in general) because we need a reference too
> for all the ff_ & avpriv_ functions and to a lesser extend the
> static functions. Especially when looking at code from other developers
> or code that we wrote 5 years ago.

Yeah. Who knows what AVClass is used for (and this is C, not C++) and what
AV_RB32 means without checking the Doxygen (and that's the only purpose I
have for Doxygen: the search engine. It's better than grep).

However, I do think for this specific Doxygen case, we should focus on the
public API first (about which I know nothing).

Timothy