[U-Boot] KernelDoc

[Tom Rini]

On Tue, Sep 25, 2012 at 10:46:10PM +0200, Marek Vasut wrote:

> 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?

The biggest problem I see with re-using kernel-style doc is that for the
subsytems we sync with the kernel we've probably got incorrect
documentation due to what we stub out and so forth.  That said, we can
somewhat deal with this when we add the tmpl file that makes the actual
output.

I think the first and most important step is to document the code that
comes in and isn't trivial.  If DM is going to do kernel-doc style
comments, good.  But we need to borrow the Documentation/DocBook
Makefile and logic and so on from the kernel first.  And add template
files for the DM sections so something can be spit out.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20120926/ea1bac65/attachment.pgp>