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 _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot