[U-Boot] KernelDoc

[Marek Vasut]

Dear Wolfgang Denk,

> Dear Marek,
> 
> In message <201209261726.55611.marex at 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