[U-Boot] KernelDoc

[Tom Rini]

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