Dear Wolfgang Denk,
Dear Marek,
In message 201209261726.55611.marex@denx.de you wrote:
Will we make this mandatory? So that we will reject all new code
that is not documented according to kernel-doc rules?
Yes please, make it mandatory. Otherwise people won't obey and the documentation will suffer ... and all this would be meaningless.
- If so, what does that mean for patches that touch existing code?
Ask the current custodian to annotate their code.
Judge from previous experience: how well will this work?
I would hate to make anyone unhappy by commenting on this ;-)
And what do we do if it doesn't work?
Is there anything we can do? It's a community project, the project is only as good as the community.
Or if you want to get your critical bug fix in now, but the custodian promises a doc patch for half a year later?
I cannot parse this. I agree the critical fix has a high-prio.
If I change the major part of an existing function (without changing it's calling interface), am I obligued to add kernel-doc comments?
Yes. Even though major vs. minor change seems pretty vague, common sense shall be applied here.
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.
Of course. But if someone fixes the calling interface, how are we supposed to know what does new parameter do? It must be documented.
- What sort of documentation do we generate?
None for starters, since it will be incomplete. I would postpone the generation as a stage 2 here.
Don't, that will fire back later, then.
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?
Pardon me, but I don't follow here. It will certainly for a while cover only small parts of U-Boot code. We need something like "kernel-janitors" here :-)
I agree. We could need all kind of help for at least a dozen of tasks. Where do we find these? And for free?
This is a problem we have for a while.
- 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?
Yes.
Can such checking (all functions have a kernel-doc comment, which covers the return value and all arguments) be done automatically, say throuch checkpatch?
I would love to see this.
Best regards,
Wolfgang Denk
Best regards, Marek Vasut