[U-Boot] KernelDoc

Marek Vasut
2012-09-26T23:38:12Z

Dear Wolfgang Denk,

> Dear Marek,
>
> In message <201209262158.48495.marex@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.

Agreed!

> > > 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 there's no rule for that.

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

Why would you do so ... you change interface, you document it.

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

+1

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

+1

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

Like Tom said, compile the docs and see if they are produced ok ... otherwise,
dunno.

> Best regards,
>
> Wolfgang Denk

Best regards,
Marek Vasut