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):
- 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.
[...]
- 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