Dear Marek,
In message 201209252246.10322.marex@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