[U-Boot] KernelDoc

Scott Wood
2012-09-28T00:28:06Z

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