[U-Boot] KernelDoc
Marek Vasut
marex at denx.de
Wed Sep 26 21:05:15 CEST 2012
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
More information about the U-Boot
mailing list