From mboxrd@z Thu Jan 1 00:00:00 1970 From: Marek Vasut Date: Wed, 26 Sep 2012 21:10:18 +0200 Subject: [U-Boot] KernelDoc In-Reply-To: <20120926190556.GB7257@bill-the-cat> References: <201209252246.10322.marex@denx.de> <20120926190556.GB7257@bill-the-cat> Message-ID: <201209262110.18172.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 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. > That said, we can > somewhat deal with this when we add the tmpl file that makes the actual > output. Uh, can you elaborate please? > 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. > 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. Best regards, Marek Vasut