[U-Boot] KernelDoc

[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)

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 :)

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.

I'm thinking that someone with  Super Saiyan levels of script-fu could
probably automate the addition of kerneldoc stubs with 'undocumented'
text

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.

Slightly OT - what is happening with the proposed patch tracker?

Regards,

Graeme