[U-Boot] KernelDoc

[Wolfgang Denk]

Dear Marek,

In message <201209262158.48495.marex at denx.de> you wrote:
> 
> > 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.

You suggested that including kernel-doc comments was mandatory for
patches to be accepted.  And that the respective maintainer should be
asked to fix the documentation for his code if needed. So we have to
wait for this maintainer before the patch goes in?

Ah, you say the fix has "high-prio".  So we are defining exceptions
from the rules?  We should document these.


> > 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.

How do we do such today?

I think is kind of unfair to expect such efforts for some basicly
unrelated changes.  If I were in such a situation, I'd feel tempted to
throw the towel.


> > > 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.

Still looking for ideas, sugestions, volunteers...

> > And missing or incorrect documentation would cause the patch to be
> > rejected?
> 
> Yes.

OK, then such new policy needs to be clearly communicated and
documented.

> > 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.

Is anything like this available anywhere?

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: wd at denx.de
"At least they're __________EXPERIENCED incompetents"