[U-Boot] KernelDoc

[Marek Vasut <marex@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