[FFmpeg-devel] [PATCH 1/2] doc/Makefile: scan all files, including .c files, for Doxygen
timothygu99 at gmail.com
Sun Nov 3 16:53:48 CET 2013
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
> > > > the current form (with the other patch in the patch set which fixes
> > > > of course).
> > > > 2b. An alternative solution to 2a is to change the section name on
> > > > website from "API doc" to "Doxygen doc for FFmpeg developers", but
> > > > 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
> > 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:
> Arithmetic / Range coding
> Linear transforms (DCT, FFT, Wavelets)
> Motion Compensation
> Motion Estimation
> Rate control
> Quantization / Dequantization
> 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).
More information about the ffmpeg-devel