From mboxrd@z Thu Jan 1 00:00:00 1970 From: Marek Vasut Date: Fri, 2 Nov 2012 04:39:11 +0100 Subject: [U-Boot] [PATCH] WIP: cbfs: Add docbook template In-Reply-To: References: <1351722443-8281-1-git-send-email-sjg@chromium.org> <201211010039.48553.marex@denx.de> Message-ID: <201211020439.11993.marex@denx.de> List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de Dear Simon Glass, > Hi Marek, > > On Wed, Oct 31, 2012 at 4:39 PM, Marek Vasut 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