Re: [PATCH][kernel-doc] Add DocBook documentation for workqueue functions

[Rolf Eike Beer <eike-kernel@sf-tec.de>]

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