[U-Boot] KernelDoc

Marek Vasut
2012-09-26T23:39:47Z

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