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.