[U-Boot] [PATCH] WIP: cbfs: Add docbook template

[Marek Vasut <marex@denx.de>]

Dear Simon Glass,

> Hi Marek,
> 
> On Wed, Oct 31, 2012 at 4:39 PM, Marek Vasut <marex@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