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

[Michael Niedermayer]

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
> "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.
> 
> 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:
> http://ffmpeg.org/doxygen/trunk/group__lavu.html
> 
> 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
> 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.

[...]

-- 
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
Type: application/pgp-signature
Size: 198 bytes
Desc: Digital signature
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20131103/882d1f0f/attachment.asc>