linux-kernel - Re: [PATCH] Add kerneldoc for flush_scheduled

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 for Android: free password hash cracker in your pocket

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

Date:	Wed, 19 Aug 2009 16:27:37 -0700
From:	Randy Dunlap <randy.dunlap@...cle.com>
To:	Randy Dunlap <randy.dunlap@...cle.com>
CC:	Johannes Weiner <hannes@...xchg.org>,
	James Bottomley <James.Bottomley@...senPartnership.com>,
	stern@...land.harvard.edu, akpm@...ux-foundation.org,
	apw@...onical.com, mingo@...e.hu, linux-kernel@...r.kernel.org,
	peterz@...radead.org
Subject: Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Randy Dunlap wrote:
> Johannes Weiner wrote:
>>> Yeah, it's the terminating **/ which matches $doc_cont.  I will try to
>>> send an updated version this evening.
>> I got completely rid of the extra re.  Just parse a non-empty content
>> line following the declaration purpose immediately as continuation.
>>
>> It survives make htmldocs, the scsi_exit_devinfo() doc looks okay and
>> for stuff that had continuation lines before, it does what's expected
>> - e.g. for the doc of kernel/sched.c::init_sd_power_savings_stats().
>>
>> It behaves differently for broken docs
>> (mm/page_alloc.c::calculate_zone_inactive_ratio e.g.), but that
>> shouldn't matter.
> 
> Right, no problem on that one (for which I sent Andrew a patch some
> time ago).
> 
>> I didn't find any other misbehaviour when checking random samples.
> 
> It's very close.  I only checked/compared one docbook: mac80211.
> There is some kind of paragraph end handling difference.
> 
> In processing include/net/mac80211.h, struct ieee80211_tx_info,
> without the patch, it ends with:
> 
> This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened
> 
> The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
> 
> and with the patch, those 2 paragraphs are run together:
> 
> This structure is placed in skb->cb for three uses: (1) mac80211 TX control - mac80211 tells the driver what to do (2) driver internal use (if applicable) (3) TX status information - driver tells mac80211 what happened The TX control's sta pointer is only valid during the ->tx call, it may be NULL.
> 
> 
> 
> I don't think that this will be difficult to find/fix...
> 
> Thanks.

Bah.  There are  lots of kernel-doc problems in mac80211.h.
I will be sending  a patch for those...

>> ---
>> From: Johannes Weiner <hannes@...xchg.org>
>> Subject: kernel-doc: allow multi-line declaration purpose descriptions
>>
>> Allow the short description after symbol name and dash in a kernel-doc
>> comment to span multiple lines, e.g. like this:
>>
>> 	/**
>> 	 * unmap_mapping_range - unmap the portion of all mmaps in the
>> 	 *	specified address_space corresponding to the specified
>> 	 *	page range in the underlying file.
>> 	 * @mapping: the address space containing mmaps to be unmapped.
>> 	 * ...
>> 	 */
>>
>> The short description ends with a parameter description, an empty line
>> or the end of the comment block.
>>
>> Signed-off-by: Johannes Weiner <hannes@...xchg.org>
>> ---
>>  Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
>>  scripts/kernel-doc                      |   19 ++++++++++++++-----
>>  2 files changed, 17 insertions(+), 6 deletions(-)

--
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/