[U-Boot] KernelDoc

Marek Vasut
2012-09-26T19:05:15Z

Dear Joe Hershberger,

[..]

> > Yes please, make it mandatory. Otherwise people won't obey and the
> > documentation will suffer ... and all this would be meaningless.
>
> I think mandatory should only be for newly added functions.

Pardon my wording, this is what I had in mind.

> There is
> already enough burden on touching existing code wrt checkpatch. The
> reviewer can feel free to recommend documentation if appropriate...
> possibly even drafting the docs.

+1

> >> - If so, what does that mean for patches that touch existing code?
> >
> > Ask the current custodian to annotate their code.
>
> This seems like a nice approach to get pretty good coverage for areas
> that have maintainers... it won't help for most of the common things
> (unless you are suggesting that WD has an awful lot to document).

With the DM, I slowly started to claim this role :-(

> >> 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 hence should not be mandatory to make the requirement criteria clear.
>
> >> If I change the calling interface, must I add documentation then?
> >
> > Of course, yes.
>
> Agreed.
>
> [...]
>
> -Joe