From mboxrd@z Thu Jan 1 00:00:00 1970 From: Marek Vasut Date: Fri, 28 Sep 2012 02:28:28 +0200 Subject: [U-Boot] KernelDoc In-Reply-To: References: <201209252246.10322.marex@denx.de> <5063EFE5.4010601@denx.de> Message-ID: <201209280228.29039.marex@denx.de> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de Dear Graeme Russ, > Hi All, > > A bit late on the bandwagon, but for what it is worth I have thought > any form of officially sanctioned (and encouraged) in-line > documentation would be 'A Good Thing'(tm) +1 > I had a quick look at kerneldoc and doxygen and while doxygen is far > more powerful, it's also a lot less 'natural' as a commenting style. > Besides, we really only have C to worry about, so we don't need to > drag in the overhead of a documentation format that supports every > language under the sun :) +1 > One point I agree on is that we must not make the barrier to entry for > new developers any higher than strictly necessary. For me, I would not > expect to be forced to document anything that was not already > documented - i.e. if I change a function (adding a parameter, changing > it's return value, etc) that was not already kerneldoc'd, I would have > a dummy spit if I was asked to resubmit with complete documentation. WFM > I'm thinking that someone with Super Saiyan levels of script-fu could > probably automate the addition of kerneldoc stubs with 'undocumented' > text I wonder ... you still need to reference the files in the templates anyway. > I really don't mind what the documentation rules are, but the MUST be > on the wiki. One this note, I think we should merge the 'Coding Style' > and 'Patches' pages of the wiki and rename them to something more > obvious like, for example, 'Rules for submitting U-Boot patches'. > Also, I think a regular reminder (say every two weeks) on the mailing > list pointing out the 'developer rules' on the wiki would be good - we > tend to get quite a number of on-off patches from new developers that > don't meet the submission criteria simply because they a blissfully > ignorant of them. +1 > Slightly OT - what is happening with the proposed patch tracker? no :-C > Regards, > > Graeme Best regards, Marek Vasut