Re: [PATCH] Add kerneldoc for flush_scheduled_work()

Randy Dunlap
2009-08-19T23:28:13Z

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(-)