[MPlayer-dev-eng] important: doxygen - documenting the source - change of code policy

[Michael Niedermayer]

Hi

On Sunday 08 August 2004 04:19, Attila Kinali wrote:
> Moin,
>
> As you all know MPlayer has a quite complex code where the dependencies
> are not always visible. Beside that the code is barely documented.
> This makes it quite hard for new people to get used to our code base.
>
> To make it easier for those (and also for us) i propose the usage
> of doxygen (doxygen.sf.net) from now on. The attached patch adds a file
> DOCS/tech/Doxyfile which is used to generate the documentation in
> DOCS/tech/doxygen. Additinaly i added two make targets into the main
> Makefile: doxygen and doxygen_clean.
>
> The Doxyfile is more or less the one generated by using doxygen -g,
> with a few options changed to add more information or to adjust to
> our specific case. I deliberatly disabled latex generation as currently
> with no function documented in a style that doxygen can make use of it,
> it doesnt makes much sense. I also disabled the call graph generation
> as i currently have not the needed software installed. I'll try it later
> and if it makes sense i'll activate it.
>
> The change in libmpdvdkit/libdvdcss.c is necessary to disable the
> mainpage directive of libdvdcss.
>
> **** IMPORTANT *****
> As with the inclusion of this patch, i also want to make a change in
> code policy, namely that every function/variable/whatever should be
> documented in a way that doxygen can make use of it.
> I know that it will take time until all already written code is
> documented (if ever), but all newly written code should follow this
> rule.
>
> Please vote here whether you agree/disagree with this change
> of policy:
>
> ---8<------
> [X] Yes, i agree with the change, all code should be documented.
> [ ] No, i don't agree, because:
>
> [ ] I don't have an opinion.
> --->8------
allthough the 'all' needs some clarification, we probably wont document most 
local variables ...

[...]
-- 
Michael
level[i]= get_vlc(); i+=get_vlc();		(violates patent EP0266049)
median(mv[y-1][x], mv[y][x-1], mv[y+1][x+1]);	(violates patent #5,905,535)
buf[i]= qp - buf[i-1];				(violates patent #?)
for more examples, see http://mplayerhq.hu/~michael/patent.html
stop it, see http://petition.eurolinux.org & http://petition.ffii.org/eubsa/en