Dear Marek, In message <201209252246.10322.ma...@denx.de> you wrote: > > I've had a discussion with Wolfgang just now about U-Boot coding style. I > tried > using KernelDoc in a patch, which is not part of the U-Boot Coding Style now, > thus it was rejected. > > I really like the idea of annotating functions with proper description, thus > I > would like to ask, can we reach a general agreement and start using kerneldoc > in > U-Boot to annotate functions and possibly generate documentation? Or shall we > use anything else? > > Or any other annotation stuff? Doxygen style? Shall it be optional or > mandatory?
Unfortunately the important (to me) part of our discussion is presented here only in the last half sentence... The points I was trying to make was this: - If we introdue any documentation system, we should do this "officially", not sneak it in with some patch here and there. - The first thing we should define is what we want to use it for, i. e. the purpose. - When introducing something, we should also agree on a policy and guidelines how we want to see it used. Questions that need to be answered include: - What is the goal we want to acchieve? Complete documentation of all U-Boot code? Documentation of some sub-system? ... ? - Will we make this mandatory? So that we will reject all new code that is not documented according to kernel-doc rules? - If so, what does that mean for patches that touch existing code? If I change the major part of an existing function (without changing it's calling interface), am I obligued to add kernel-doc comments? If I change the calling interface, must I add documentation then? - What sort of documentation do we generate? How can we make clear that for a long, long time it will cover only a small fraction of the actual code, eventually even parts of some source files? - Who will be responsible for maintaining the documentation? For making sure it gives a usable result, it looks more or less consistent? - What about internationalization? Who will do the translations? ;-) Best regards, Wolfgang Denk -- DENX Software Engineering GmbH, MD: Wolfgang Denk & Detlev Zundel HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: w...@denx.de When you die, the first thing you lose is your life. The next thing is the illusions. - Terry Pratchett, _Pyramids_ _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot
