From mboxrd@z Thu Jan  1 00:00:00 1970
From: Marek Vasut <marex@denx.de>
Date: Thu, 27 Sep 2012 01:38:12 +0200
Subject: [U-Boot] KernelDoc
In-Reply-To: <20120926205721.0580820032E@gemini.denx.de>
References: <201209252246.10322.marex@denx.de>
	<201209262158.48495.marex@denx.de>
	<20120926205721.0580820032E@gemini.denx.de>
Message-ID: <201209270138.12860.marex@denx.de>
List-Id: <u-boot.lists.denx.de>
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
To: u-boot@lists.denx.de

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