[U-Boot] KernelDoc

[Marek Vasut <marex@denx.de>]

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