[U-Boot] KernelDoc

[Marek Vasut <marex@denx.de>]

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