[U-Boot] KernelDoc

[Marek Vasut]

Dear Marek Vasut,

> Hi all!
> 
> I've had a discussion with Wolfgang just now about U-Boot coding style. I
> tried using KernelDoc in a patch, which is not part of the U-Boot Coding
> Style now, thus it was rejected.
> 
> I really like the idea of annotating functions with proper description,
> thus I would like to ask, can we reach a general agreement and start using
> kerneldoc in U-Boot to annotate functions and possibly generate
> documentation? Or shall we use anything else?
> 
> Or any other annotation stuff? Doxygen style? Shall it be optional or
> mandatory?
> 
> See [1] in Linux kernel tree for what I mean.
> 
> [1] Documentation/kernel-doc-nano-HOWTO.txt

So I've been hacking on it for a bit, see the first stab at [1]. As for the 
ruleset, I propose this addition for the Wiki [2]:

-->8--

U-Boot code documentation
=========================

U-Boot adopted the kernel-doc annotation style, this is the only exception from 
multi-line comment rule of Coding Style. While not mandatory, adding 
documentation is strongly advised. The Linux kernel kernel-doc document [3] 
appliest with no changes.

--8<--

[1] http://twilight.ponies.cz/kerneldoc/
[2] http://www.denx.de/wiki/U-Boot/CodingStyle
[3] 
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kernel-
doc-nano-HOWTO.txt

Best regards,
Marek Vasut