From mboxrd@z Thu Jan  1 00:00:00 1970
From: Marek Vasut <marex@denx.de>
Date: Wed, 26 Sep 2012 21:05:15 +0200
Subject: [U-Boot] KernelDoc
In-Reply-To: <CANr=Z=bZu_QSGYn+ye6ZRqQRPZ3ZB_UX2p5wu_=0LQnZP8eWSQ@mail.gmail.com>
References: <201209252246.10322.marex@denx.de>
	<201209261726.55611.marex@denx.de>
	<CANr=Z=bZu_QSGYn+ye6ZRqQRPZ3ZB_UX2p5wu_=0LQnZP8eWSQ@mail.gmail.com>
Message-ID: <201209262105.16132.marex@denx.de>
List-Id: <u-boot.lists.denx.de>
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
To: u-boot@lists.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