[U-Boot] KernelDoc

[Marek Vasut]

Dear Scott Wood,

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

Ok, you overvoted me here completely. My point was so that in order to have 
really useful documentation, we should make sure people don't slack on creating 
it.

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

I believe everything shall eventually be documented. If it is not to be 
enforced, ok.

> We already have too many arbitrary rules with inconsistent
> enforcement.

True. We need to make a proper list of these rules.

> 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

:-D

> -Scott

Best regards,
Marek Vasut