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? And what do
we do if it doesn't work? Or if you want to get your critical bug fix
in now, but the custodian promises a doc patch for half a year later?
> > 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.
> > - 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?
> > - 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?
Can such checking (all functions have a kernel-doc comment, which
covers the return value and all arguments) be done automatically, say
throuch checkpatch?
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
Intuition, however illogical, is recognized as a command prerogative.
-- Kirk, "Obsession", stardate 3620.7
_______________________________________________
U-Boot mailing list
U-Boot@lists.denx.de
http://lists.denx.de/mailman/listinfo/u-boot
