-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 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. - -- Tom -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://www.enigmail.net/ iQIbBAEBAgAGBQJQY15CAAoJENk4IS6UOR1WrsYP90xS8QZg94tOEAwZ+RsCDZMC 2/eiFDwFo9UySK+5FnzKl2uARfLTje0Dn46cUleKgaEpO9yFx72g5V83/uZt/wrF J9IYp4Mp4W3RLvBpX+Rl59lT7ZxDzI6798KM7ydT+UCQ99nTY9qhfQ8ZWy7SN2ho KnJYJ1gRPBegK95eVEeOlq5GTg6DMJ28ln1P4xFvxRzuwJ6zTZu+bwMiFrHyyEbD 0RxubSuyk+puVEOlGxiwR33Sgc/lTX0H960tuZoIUrHXPp5jL6BZnDx6MFIYPNAz r5200q32qXeAtWD31oYWDmDqFb8Ftzenx4yYPfNFk/sJ4fhCVFaetoRc/RXQQi4o fx3h4xQYzJd/n7IydSHJqyp8EMj+FI3Eaqp/2HPOJggV81Hls73fVGGrWIa1Q+ue tddQOXjrqRAbqyzAeQo9tQYiheeV7GZi2YQ7pIh9y6Ta+R/epLfBbEoX2Jik/FuK EHDNoxvhPC0D+Z7uTXmoX9POaSbYRKfLnzXde6Q9Od/6MkIwd6TuF1SyDo/fNtix +cGfvvHog0KkepqH0QdGb5n1w7YFaavbfdKDa3j3lvYST70kI+r+ljEBq37QG8GE sSNUOiOlz9xtUpx8BorX4TvrH5xlfJNPE1IrOVH0BZ1xpLU4LoMjO6LlMsP4xIId UDNJ8cIXHmePaME6hXE= =Yf9e -----END PGP SIGNATURE----- _______________________________________________ U-Boot mailing list U-Boot@lists.denx.de http://lists.denx.de/mailman/listinfo/u-boot