[U-Boot] KernelDoc

[Marek Vasut <marex@denx.de>]

Dear 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.

+1, but then the creator of the patch is responsible for keeping the docs 
inline.

> That said, we can
> somewhat deal with this when we add the tmpl file that makes the actual
> output.

Uh, can you elaborate please?

> I think the first and most important step is to document the code that
> comes in and isn't trivial.

+1

> If DM is going to do kernel-doc style
> comments, good.

Not only DM please.

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

I'd leave that for step 2 (documentation generation) and don't bother with this 
right away.

Best regards,
Marek Vasut