[U-Boot] KernelDoc

[Scott Wood <scottwood@freescale.com>]

On 09/26/2012 10:26:55 AM, Marek Vasut wrote:
> Dear Wolfgang Denk,
> 
> > Dear Marek,
> > - 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.

-1

The project you're copying from doesn't make it mandatory.  Why should  
U-Boot?  What would it be mandatory for?  Major public APIs?   
Semi-private functions shared between a few related files?  Every  
little static function?

We already have too many arbitrary rules with inconsistent  
enforcement.  What's wrong with just encouraging it where appropriate,  
and insisting only if the maintainer deems it important enough in  
context?

OTOH, I don't think patches should be rejected for having that extra  
asterisk, regardless of whether we encourage kerneldoc in U-Boot  
(unless we adopt a different tool with different requirements).   
Kerneldoc-style headers are still useful documentation even if we don't  
use the actual kerneldoc tool, code can be shared between Linux and  
U-Boot, people can maintain their existing Linux habits, etc.  It's a  
weak argument to point to the CodingStyle document as forbidding it  
when it's clear that the project that CodingStyle comes from uses this  
all over the place.

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

And then someone's going to complain that the commenting should be a  
separate patch... more red tape. :-P

-Scott