[FFmpeg-devel] [PATCH 1/2] doc/Makefile: scan all files, including .c files, for Doxygen
michaelni at gmx.at
Sun Nov 3 15:22:01 CET 2013
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
> What's the supposed use of modules, what's the supposed use of
> 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.
> 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:
> I can only see the version.h file.
> As I see it, "modules" as currently defined are an arbitrary
> schizofrenic half-baked attempt to provide some form of
that would probably be an accurate definition of the current state
> For example in case of libavutil:
> Crypto and Hashing
> String Manipulation
> Memory Management
> Data Structures
Generic Data Structures
> Audio related
> Error Codes
> Logging Facility
> 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:
> 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).
Arithmetic / Range coding
Linear transforms (DCT, FFT, Wavelets)
Quantization / Dequantization
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:
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.
Michael GnuPG fingerprint: 9FF2128B147EF6730BADF133611EC787040B0FAB
No great genius has ever existed without some touch of madness. -- Aristotle
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Size: 198 bytes
Desc: Digital signature
More information about the ffmpeg-devel