Re: [PATCH] Add kerneldoc for flush_scheduled_work()

[Randy Dunlap <randy.dunlap@oracle.com>]

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@cmpxchg.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@cmpxchg.org>
>> ---
>>  Documentation/kernel-doc-nano-HOWTO.txt |    4 +++-
>>  scripts/kernel-doc                      |   19 ++++++++++++++-----
>>  2 files changed, 17 insertions(+), 6 deletions(-)