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

[Stefano Sabatini]

On date Sunday 2013-11-03 15:22:01 +0100, Michael Niedermayer encoded:
> On Sun, Nov 03, 2013 at 12:19:01PM +0100, Stefano Sabatini wrote:
[...]
> 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.

I don't think it's realistic, given the resistance of most developers
to even document the public API.

Also having the signature documented is not the same that having it
grouped in doxygen, and I don't think there is a single well defined
taxonomy, so we should rather rely on the "natural" taxonomy induced
by the file structure.

In case it is too much coarse-grained (e.g. avcodec.h), then we should
consider to split the file.
-- 
FFmpeg = Forgiving and Fiendish Mere Prodigious Ecletic Gem