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.
> >> - 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.
More information about the U-Boot