[MPlayer-dev-eng] Funny things with Doxygen

[Ivo]

Hi all,

With my last patch I tried to conform with the new code documentation rules 
and hence started to play around a bit with doxygen. I noticed some 
peculiar behaviour. My main focus is on the libvo directory and its 
contents, so I my examples will be based on that, but I'm quite sure the 
same problems will occur in libaf, libmpcodecs, et cetera.

I did make doxygen and viewed the resulting HTML code.

I noticed a lot of functions within certain vo_* drivers had the SDL 
comments for all of their standard functions, like preinit, config, et 
cetera. But, and that's really weird, not all vo_*.c files had. Some had no 
comments at all, while others _did_ had the SDL remarks, while making no 
sense at all ofcourse.

It got worse. I added a test comment to config() in vo_jpeg.c and for some 
vo_*.c files doxygen copied the SDL comments, for others it copied my test 
comment and for some it still had no comments at all.

Now what? How can we fix this? Should we do one big patch that adds empty 
descriptions to _all_ functions, in order to be sure doxygen doesn't mix up 
functions that happen to have the same name? Or should we just leave it? 
(bad idea IMHO). Or is there another option I haven't thought of yet? 
(maybe a change in the way doxygen behaves?)

--Ivo