From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S964822AbWGTNCl (ORCPT ); Thu, 20 Jul 2006 09:02:41 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S964839AbWGTNCl (ORCPT ); Thu, 20 Jul 2006 09:02:41 -0400 Received: from mail.sf-mail.de ([62.27.20.61]:36065 "EHLO mail.sf-mail.de") by vger.kernel.org with ESMTP id S964822AbWGTNCk (ORCPT ); Thu, 20 Jul 2006 09:02:40 -0400 From: Rolf Eike Beer To: "Randy.Dunlap" Subject: Re: [PATCH][kernel-doc] Add DocBook documentation for workqueue functions Date: Thu, 20 Jul 2006 15:03:54 +0200 User-Agent: KMail/1.9.3 Cc: Martin Waitz , Andrew Morton , linux-kernel@vger.kernel.org References: <200607201145.19147.eike-kernel@sf-tec.de> In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200607201503.55036.eike-kernel@sf-tec.de> Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org Randy Dunlap wrote: > On Thu, 20 Jul 2006, Rolf Eike Beer wrote: > > kernel/workqueue.c was omitted from generating kernel documentation. This > > adds a new section "Workqueues and Kevents" and adds documentation for > > some of the functions. > > > > Some functions in this file already had DocBook-style comments, now they > > finally become visible > > Cool, thanks much. > > Did you test it? At least two of them. > There should not be an empty ("*" only) line > between the function name + short description and the function > parameter line(s). If you generate output for these functions, > the Description section will be there 2 times (i.e., repeated), > so please just delete those lines and it will be Good. Yes, I saw that. That's a very common problem all over the kernel. Now I see that the nano-howto says it's this way, but I've seen the other way for years. One example is vmalloc_32_user that I touched on monday. I'll submit a version 3 of this soon. In the meantime "make mandocs" should either warn of those or handle them the right way (aka ignore the newline). If it would also warn on duplicate descriptions, at least in the same file, this would have catched my copy&waste bug in the first version also. Eike