[PATCH] doc: Add more workqueue functions to the documentation

[PATCH] doc: Add more workqueue functions to the documentation

[Tim Bird]

There are some workqueue functions declared in workqueue.h, so include
that in the workqueue section of the DocBook docs.

Signed-off-by: Tim Bird <tim.bird@sonymobile.com>
---
 Documentation/DocBook/device-drivers.tmpl | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index faf09d4..bbc1d7e 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -66,6 +66,7 @@
 !Ekernel/time/hrtimer.c
      </sect1>
      <sect1><title>Workqueues and Kevents</title>
+!Iinclude/linux/workqueue.h
 !Ekernel/workqueue.c
      </sect1>
      <sect1><title>Internal Functions</title>
-- 
1.8.2.2

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Randy Dunlap]

On 08/10/15 15:16, Tim Bird wrote:
> There are some workqueue functions declared in workqueue.h, so include
> that in the workqueue section of the DocBook docs.
> 
> Signed-off-by: Tim Bird <tim.bird@sonymobile.com>

Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/DocBook/device-drivers.tmpl | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
> index faf09d4..bbc1d7e 100644
> --- a/Documentation/DocBook/device-drivers.tmpl
> +++ b/Documentation/DocBook/device-drivers.tmpl
> @@ -66,6 +66,7 @@
>  !Ekernel/time/hrtimer.c
>       </sect1>
>       <sect1><title>Workqueues and Kevents</title>
> +!Iinclude/linux/workqueue.h
>  !Ekernel/workqueue.c
>       </sect1>
>       <sect1><title>Internal Functions</title>
> 


-- 
~Randy

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Jonathan Corbet]

On Mon, 10 Aug 2015 15:16:16 -0700
Tim Bird <tim.bird@sonymobile.com> wrote:

> There are some workqueue functions declared in workqueue.h, so include
> that in the workqueue section of the DocBook docs.

Applied to the docs tree, thanks.

It sure would be nice if changes like this were accompanied by a patch
fixing the additional warnings it drags in ... :)  In this case I've put
something together for workqueue.h and will send it off shortly.

jon

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Tim Bird]

On 08/13/2015 04:45 PM, Jonathan Corbet wrote:
> On Mon, 10 Aug 2015 15:16:16 -0700
> Tim Bird <tim.bird@sonymobile.com> wrote:
> 
>> There are some workqueue functions declared in workqueue.h, so include
>> that in the workqueue section of the DocBook docs.
> 
> Applied to the docs tree, thanks.
> 
> It sure would be nice if changes like this were accompanied by a patch
> fixing the additional warnings it drags in ... :)  In this case I've put
> something together for workqueue.h and will send it off shortly.

My apologies.  

When I do 'make mandocs', the only messages from workqueue.h that I noticed
were like the following:

Warn: meta author : no refentry/info/author                        queue_delayed_work
Note: meta author : see http://docbook.sf.net/el/author            queue_delayed_work
Warn: meta author : no author data, so inserted a fixme            queue_delayed_work
Note: Writing queue_delayed_work.9

But there are over 4000 of these messages when I make mandocs, so I assumed
ignoring them was OK.

Are these what you saw or was it something else?

Do you know how to get rid of these messages?  

It's a bit of a pain rebuilding.  When I make a change, it rebuilds everything.
My build of mandocs takes 27 minutes and generates over 9000 messages.
Somewhere in the middle of that must have been some other messages related to
workqueue.h that I missed.

However, I'll try to fix build errors in the future.

Thanks,
 -- Tim

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Randy Dunlap]

On 08/14/15 15:46, Tim Bird wrote:
> 
> 
> On 08/13/2015 04:45 PM, Jonathan Corbet wrote:
>> On Mon, 10 Aug 2015 15:16:16 -0700
>> Tim Bird <tim.bird@sonymobile.com> wrote:
>>
>>> There are some workqueue functions declared in workqueue.h, so include
>>> that in the workqueue section of the DocBook docs.
>>
>> Applied to the docs tree, thanks.
>>
>> It sure would be nice if changes like this were accompanied by a patch
>> fixing the additional warnings it drags in ... :)  In this case I've put
>> something together for workqueue.h and will send it off shortly.
> 
> My apologies.  
> 
> When I do 'make mandocs', the only messages from workqueue.h that I noticed
> were like the following:
> 
> Warn: meta author : no refentry/info/author                        queue_delayed_work
> Note: meta author : see http://docbook.sf.net/el/author            queue_delayed_work
> Warn: meta author : no author data, so inserted a fixme            queue_delayed_work
> Note: Writing queue_delayed_work.9
> 
> But there are over 4000 of these messages when I make mandocs, so I assumed
> ignoring them was OK.
> 
> Are these what you saw or was it something else?

These are the new warnings that I saw:

Warning(..//include/linux/workqueue.h:271): No description found for parameter 'w'
Warning(..//include/linux/workqueue.h:271): Excess function parameter 'work' description in 'delayed_work_pending'
Warning(..//include/linux/workqueue.h:390): Excess function parameter 'args' description in 'alloc_workqueue'
Warning(..//include/linux/workqueue.h:411): Excess function parameter 'args' description in 'alloc_ordered_workqueue'

and Jon has already posted a patch for these.

> Do you know how to get rid of these messages?  
> 
> It's a bit of a pain rebuilding.  When I make a change, it rebuilds everything.
> My build of mandocs takes 27 minutes and generates over 9000 messages.
> Somewhere in the middle of that must have been some other messages related to
> workqueue.h that I missed.
> 
> However, I'll try to fix build errors in the future.


-- 
~Randy

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Jonathan Corbet]

On Fri, 14 Aug 2015 15:46:52 -0700
Tim Bird <tim.bird@sonymobile.com> wrote:

> > It sure would be nice if changes like this were accompanied by a patch
> > fixing the additional warnings it drags in ... :)  In this case I've put
> > something together for workqueue.h and will send it off shortly.  
> 
> My apologies.  

Sorry, hope I didn't sound grumpier than I really was.  As you note, the
docs builds are a morass of warnings; it would be nice to avoid making it
worse when possible.  Especially warnings that actually mean something -
like the docbook comments being wrong.  It was easily fixed, anyway, no
worries.

jon

Re: [PATCH] doc: Add more workqueue functions to the documentation

[Tim Bird]

On 08/15/2015 06:27 AM, Jonathan Corbet wrote:
> On Fri, 14 Aug 2015 15:46:52 -0700
> Tim Bird <tim.bird@sonymobile.com> wrote:
> 
>>> It sure would be nice if changes like this were accompanied by a patch
>>> fixing the additional warnings it drags in ... :)  In this case I've put
>>> something together for workqueue.h and will send it off shortly.  
>>
>> My apologies.  
> 
> Sorry, hope I didn't sound grumpier than I really was.  As you note, the
> docs builds are a morass of warnings; it would be nice to avoid making it
> worse when possible.  Especially warnings that actually mean something -
> like the docbook comments being wrong.  It was easily fixed, anyway, no
> worries.

You didn't sound grumpy, but I probably came off as overly
sensitive. I was embarrassed to have missed the warnings.

I would like to lend a hand to clean up the warnings.  And
I'm interested in following up on the discussion from the
ksummit list, about a possible conversion to markdown or
asciidoc.  I started experimenting with this by converting
one of the text files in Documentation to both markdown
and asciidoc, to see:
1) what additional tools needed to be installed, if any,
2) what it took to convert from plain text to the different
markup languages, and
3) and what the resulting output looked like.

However, I didn't quite finish.  If this gets on the agenda
for the kernel summit, then I'll definitely finish up this
work (and maybe try it on some other files), so that there's
a data point for discussing a conversion from DocBook to
something else.

I had the idea of maybe just doing something for the API
docs completely in parallel, as a test, to determine the
difficulty of conversion.  But it probably would turn into
one of those 80/80 things.  (The first 80 percent of the
project takes 80 percent of the time, and the last 20 percent
takes the other 80 percent. :-)
 -- Tim