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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:	Thu, 20 Jul 2006 15:03:54 +0200
From:	Rolf Eike Beer <eike-kernel@...tec.de>
To:	"Randy.Dunlap" <rdunlap@...otime.net>
Cc:	Martin Waitz <tali@...ingilde.org>, Andrew Morton <akpm@...l.org>,
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH][kernel-doc] Add DocBook documentation for workqueue functions

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
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/