[U-Boot] KernelDoc
Marek Vasut
marex at denx.de
Fri Sep 28 02:28:28 CEST 2012
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
More information about the U-Boot
mailing list