[U-Boot] [PATCH] WIP: cbfs: Add docbook template
Marek Vasut
marex at denx.de
Fri Nov 2 04:39:11 CET 2012
Dear Simon Glass,
> Hi Marek,
>
> On Wed, Oct 31, 2012 at 4:39 PM, Marek Vasut <marex at denx.de> wrote:
> > Dear Simon Glass,
> >
> >> This adds a docbook template for fs, and makes CBFS use it.
> >>
> >> Problems (advise please as I have enough 500pp books in my bookshelf):
> >
> >> 1. It requires the function names to be repeated. I would like to do this:
> > Repeating function names is good, you can be sure what the comment is
> > associated with.
>
> Hmmm, well I already know that, since the comment appears immediately
> above the function...
At the time of writing, yes. But some adjustment of code might mess that up.
> > [...]
> >
> >> 2. It will not accept the doxygen @param style for parameters:
> > It's not doxygen, sorry. Read [1].
>
> Yes, I was rather hoping there was an easy way to fix these two
> things. Never mind.
I'd say there is, but let's fix it in Linux kernel too. Actually, I have a pile
of patches for Linux kernel's documentation, but it's hard to get any
documentation patches in :-C
> > btw. I'd like some kind of @return, but maybe describing the return value
> > in comment is enough.
>
> Maybe, but it's nice to be explicit. The return value is at least as
> important as the parameters, and they are called out.
I agree (!).
> Anyway I will rev the patch with the above in mind.
[...]
btw. It'd be nice to be able to patch the upstream (linux's) kerneldoc :-(
Best regards,
Marek Vasut
More information about the U-Boot
mailing list