Dear Wolfgang Denk, > Dear Marek, > > In message <201209261726.55611.ma...@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 _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot
