From mboxrd@z Thu Jan  1 00:00:00 1970
From: Stefan Roese <sr@denx.de>
Date: Thu, 27 Sep 2012 08:19:17 +0200
Subject: [U-Boot] KernelDoc
In-Reply-To: <20120926195412.AC7B32031A9@gemini.denx.de>
References: <201209252246.10322.marex@denx.de>
	<20120926071743.238A42031A9@gemini.denx.de>
	<201209261726.55611.marex@denx.de>
	<20120926195412.AC7B32031A9@gemini.denx.de>
Message-ID: <5063EFE5.4010601@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

On 09/26/2012 09:54 PM, Wolfgang Denk wrote:

<snip>

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

Full ACK.

<snip>

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

Please don't. As you mentioned above, we (in U-Boot) already have very
strict rules making it not easy for especially new developers to push
their changes upstream. I fear that with such a new requirement, more
users / developers will abandon pushing their patches at some time.

BTW: I've done quite some Linux kernel work and never used this
kernel-doc style so far. Its not mandatory in the Linux kernel. Not that
this really matters in regards to U-Boot. But my personal feeling is,
that we shouldn't make it much harder to push patches in U-Boot than in
Linux.

Just my 0.02$.

Thanks,
Stefan