On 09/26/2012 09:54 PM, Wolfgang Denk wrote:
<snip>
If I change the calling interface, must I add documentation then?
Of course, yes.
Didn't we agree that we want to make it easier for people to contribute code? If somebody who just wants to improve a small detail in the code is now not only enforced to fix the coding style, but _also_ document the whole file, this will probably not exactly attract new contributors.
Full ACK.
<snip>
- Who will be responsible for maintaining the documentation?
I believe for now we should only focus on using this as a standardized method of anotating functions. The reviewer of the patch shall check if the patch is correct incl. the documentation, as usual.
And missing or incorrect documentation would cause the patch to be rejected?
Please don't. As you mentioned above, we (in U-Boot) already have very strict rules making it not easy for especially new developers to push their changes upstream. I fear that with such a new requirement, more users / developers will abandon pushing their patches at some time.
BTW: I've done quite some Linux kernel work and never used this kernel-doc style so far. Its not mandatory in the Linux kernel. Not that this really matters in regards to U-Boot. But my personal feeling is, that we shouldn't make it much harder to push patches in U-Boot than in Linux.
Just my 0.02$.
Thanks, Stefan