Dear Tom Rini,
On 09/26/12 12:10, Marek Vasut wrote:
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.
Which will in turn make a mess for further re-syncs. This should probably just be dealt with in the tmpl file for whatever reads the drivers/mtd/nand files.
That said, we can somewhat deal with this when we add the tmpl file that makes the actual output.
Uh, can you elaborate please?
How familiar with kerneldoc are you? Yes, you put specially formatted comments into source files. But you also write a tmpl file (see Documentation/DocBook/kgdb.tmpl for example) that references the code and further elaborates on things and so on.
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.
Yes, I'm just using this as an example.
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.
No. In order for everyone who isn't on your team to understand what you're doing, documentation is needed. And I know you already agree here. What I'm saying is that instead of for example a static doc/driver-model/UDM-serial.txt we would move to having doc/DocBook/UDM-serial.tmpl which would cover the same content as the current file, reference the code in question and if A and B get out of sync, well, this is something you and your team should check before posting. Making sure you document what you code AND code what you document is important.
Yes, I agree. We will need a code documentation anyway, so I might as well invest time into this.
Best regards, Marek Vasut