* rcu kernel-doc issues (4.14-rc1)
@ 2017-09-17 1:26 Randy Dunlap
2017-09-17 4:41 ` Paul E. McKenney
2017-09-18 6:43 ` Markus Heiser
0 siblings, 2 replies; 20+ messages in thread
From: Randy Dunlap @ 2017-09-17 1:26 UTC (permalink / raw)
To: LKML, linux-doc, Paul E. McKenney; +Cc: Jonathan Corbet
On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
.. kernel-doc:: include/linux/rcupdate.h
:external:
./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rcupdate_wait.h
:external:
./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rcutree.h
:external:
./Documentation/core-api/kernel-api.rst:363: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/tree.c
:external:
./Documentation/core-api/kernel-api.rst:366: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/tree_plugin.h
:external:
./Documentation/core-api/kernel-api.rst:369: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/tree_exp.h
:external:
./Documentation/core-api/kernel-api.rst:372: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/update.c
:external:
./Documentation/core-api/kernel-api.rst:375: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/srcu.h
:external:
./Documentation/core-api/kernel-api.rst:378: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/srcutree.c
:external:
./Documentation/core-api/kernel-api.rst:381: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rculist_bl.h
:external:
./Documentation/core-api/kernel-api.rst:384: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rculist.h
:external:
./Documentation/core-api/kernel-api.rst:387: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rculist_nulls.h
:external:
./Documentation/core-api/kernel-api.rst:390: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: include/linux/rcu_sync.h
:external:
./Documentation/core-api/kernel-api.rst:393: ERROR: Error in "kernel-doc" directive:
unknown option: "external".
.. kernel-doc:: kernel/rcu/sync.c
:external:
../kernel/rcu/tree.c:3091: ERROR: Unexpected indentation.
../kernel/rcu/tree.c:3118: ERROR: Unexpected indentation.
../kernel/rcu/tree.c:3119: WARNING: Bullet list ends without a blank line; unexpected unindent.
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 1:26 rcu kernel-doc issues (4.14-rc1) Randy Dunlap
@ 2017-09-17 4:41 ` Paul E. McKenney
2017-09-17 17:47 ` Paul E. McKenney
2017-09-18 6:43 ` Markus Heiser
1 sibling, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-09-17 4:41 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>
> .. kernel-doc:: include/linux/rcupdate.h
> :external:
> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
$ grep external include/linux/rcupdate.h
* by a single external-to-structure RCU-protected pointer, then you may
* external-to-structure pointer -after- you have completely initialized
Do these comments somehow qualify as an "external" option? If so, how
do I tell kernel-doc to ignore them? Or must I reword them to avoid
the word "external"?
> .. kernel-doc:: include/linux/rcupdate_wait.h
> :external:
> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
$ grep external include/linux/rcupdate_wait.h
There is no occurrence of the string "external" in this file. So this
"external" option is unknown to me as well. So, any hints on how I
should interpret these error messages?
Thanx, Paul
> .. kernel-doc:: include/linux/rcutree.h
> :external:
> ./Documentation/core-api/kernel-api.rst:363: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/tree.c
> :external:
> ./Documentation/core-api/kernel-api.rst:366: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/tree_plugin.h
> :external:
> ./Documentation/core-api/kernel-api.rst:369: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/tree_exp.h
> :external:
> ./Documentation/core-api/kernel-api.rst:372: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/update.c
> :external:
> ./Documentation/core-api/kernel-api.rst:375: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: include/linux/srcu.h
> :external:
> ./Documentation/core-api/kernel-api.rst:378: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/srcutree.c
> :external:
> ./Documentation/core-api/kernel-api.rst:381: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: include/linux/rculist_bl.h
> :external:
> ./Documentation/core-api/kernel-api.rst:384: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: include/linux/rculist.h
> :external:
> ./Documentation/core-api/kernel-api.rst:387: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: include/linux/rculist_nulls.h
> :external:
> ./Documentation/core-api/kernel-api.rst:390: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: include/linux/rcu_sync.h
> :external:
> ./Documentation/core-api/kernel-api.rst:393: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
>
> .. kernel-doc:: kernel/rcu/sync.c
> :external:
>
> ../kernel/rcu/tree.c:3091: ERROR: Unexpected indentation.
> ../kernel/rcu/tree.c:3118: ERROR: Unexpected indentation.
> ../kernel/rcu/tree.c:3119: WARNING: Bullet list ends without a blank line; unexpected unindent.
>
>
> --
> ~Randy
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 4:41 ` Paul E. McKenney
@ 2017-09-17 17:47 ` Paul E. McKenney
2017-09-17 17:57 ` Randy Dunlap
0 siblings, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-09-17 17:47 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> > On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >
> > .. kernel-doc:: include/linux/rcupdate.h
> > :external:
> > ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> > unknown option: "external".
>
> $ grep external include/linux/rcupdate.h
> * by a single external-to-structure RCU-protected pointer, then you may
> * external-to-structure pointer -after- you have completely initialized
>
> Do these comments somehow qualify as an "external" option? If so, how
> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> the word "external"?
>
> > .. kernel-doc:: include/linux/rcupdate_wait.h
> > :external:
> > ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> > unknown option: "external".
>
> $ grep external include/linux/rcupdate_wait.h
>
> There is no occurrence of the string "external" in this file. So this
> "external" option is unknown to me as well. So, any hints on how I
> should interpret these error messages?
And thanks to Akira Yokosawa for pointing out my confusion in reading
these error messages. The line numbers of course apply to the file
Documentation/core-api/kernel-api.rst rather than the various RCU
C-language source files.
The patch below removes the error messages for me. Is this what you
had in mind? (Might need other options at some point, but somewhere
to start.)
Thanx, Paul
------------------------------------------------------------------------
diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 8282099e0cbf..30b2666bf494 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -352,44 +352,44 @@ Read-Copy Update (RCU)
----------------------
.. kernel-doc:: include/linux/rcupdate.h
- :external:
+ :export
.. kernel-doc:: include/linux/rcupdate_wait.h
- :external:
+ :export
.. kernel-doc:: include/linux/rcutree.h
- :external:
+ :export
.. kernel-doc:: kernel/rcu/tree.c
- :external:
+ :export
.. kernel-doc:: kernel/rcu/tree_plugin.h
- :external:
+ :export
.. kernel-doc:: kernel/rcu/tree_exp.h
- :external:
+ :export
.. kernel-doc:: kernel/rcu/update.c
- :external:
+ :export
.. kernel-doc:: include/linux/srcu.h
- :external:
+ :export
.. kernel-doc:: kernel/rcu/srcutree.c
- :external:
+ :export
.. kernel-doc:: include/linux/rculist_bl.h
- :external:
+ :export
.. kernel-doc:: include/linux/rculist.h
- :external:
+ :export
.. kernel-doc:: include/linux/rculist_nulls.h
- :external:
+ :export
.. kernel-doc:: include/linux/rcu_sync.h
- :external:
+ :export
.. kernel-doc:: kernel/rcu/sync.c
- :external:
+ :export
^ permalink raw reply related [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 17:47 ` Paul E. McKenney
@ 2017-09-17 17:57 ` Randy Dunlap
2017-09-17 19:49 ` Paul E. McKenney
0 siblings, 1 reply; 20+ messages in thread
From: Randy Dunlap @ 2017-09-17 17:57 UTC (permalink / raw)
To: paulmck; +Cc: LKML, linux-doc, Jonathan Corbet
On 09/17/17 10:47, Paul E. McKenney wrote:
> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>>>
>>> .. kernel-doc:: include/linux/rcupdate.h
>>> :external:
>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
>>> unknown option: "external".
>>
>> $ grep external include/linux/rcupdate.h
>> * by a single external-to-structure RCU-protected pointer, then you may
>> * external-to-structure pointer -after- you have completely initialized
>>
>> Do these comments somehow qualify as an "external" option? If so, how
>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
>> the word "external"?
>>
>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>> :external:
>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
>>> unknown option: "external".
>>
>> $ grep external include/linux/rcupdate_wait.h
>>
>> There is no occurrence of the string "external" in this file. So this
>> "external" option is unknown to me as well. So, any hints on how I
>> should interpret these error messages?
>
> And thanks to Akira Yokosawa for pointing out my confusion in reading
> these error messages. The line numbers of course apply to the file
> Documentation/core-api/kernel-api.rst rather than the various RCU
> C-language source files.
>
> The patch below removes the error messages for me. Is this what you
> had in mind? (Might need other options at some point, but somewhere
> to start.)
>
Yes, much better. Thanks.
Just some missing kernel-doc on parameters mostly remaining:
../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
../include/linux/rculist.h:317: warning: No description found for parameter 'type'
../include/linux/rculist.h:317: warning: No description found for parameter 'member'
../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
>
> ------------------------------------------------------------------------
>
> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> index 8282099e0cbf..30b2666bf494 100644
> --- a/Documentation/core-api/kernel-api.rst
> +++ b/Documentation/core-api/kernel-api.rst
> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> ----------------------
>
> .. kernel-doc:: include/linux/rcupdate.h
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rcupdate_wait.h
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rcutree.h
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/tree.c
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/tree_plugin.h
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/tree_exp.h
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/update.c
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/srcu.h
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/srcutree.c
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rculist_bl.h
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rculist.h
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rculist_nulls.h
> - :external:
> + :export
>
> .. kernel-doc:: include/linux/rcu_sync.h
> - :external:
> + :export
>
> .. kernel-doc:: kernel/rcu/sync.c
> - :external:
> + :export
>
>
> --
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 17:57 ` Randy Dunlap
@ 2017-09-17 19:49 ` Paul E. McKenney
2017-09-18 2:40 ` Paul E. McKenney
2017-10-16 19:58 ` Randy Dunlap
0 siblings, 2 replies; 20+ messages in thread
From: Paul E. McKenney @ 2017-09-17 19:49 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> On 09/17/17 10:47, Paul E. McKenney wrote:
> > On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>
> >>> .. kernel-doc:: include/linux/rcupdate.h
> >>> :external:
> >>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> >>> unknown option: "external".
> >>
> >> $ grep external include/linux/rcupdate.h
> >> * by a single external-to-structure RCU-protected pointer, then you may
> >> * external-to-structure pointer -after- you have completely initialized
> >>
> >> Do these comments somehow qualify as an "external" option? If so, how
> >> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> >> the word "external"?
> >>
> >>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>> :external:
> >>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> >>> unknown option: "external".
> >>
> >> $ grep external include/linux/rcupdate_wait.h
> >>
> >> There is no occurrence of the string "external" in this file. So this
> >> "external" option is unknown to me as well. So, any hints on how I
> >> should interpret these error messages?
> >
> > And thanks to Akira Yokosawa for pointing out my confusion in reading
> > these error messages. The line numbers of course apply to the file
> > Documentation/core-api/kernel-api.rst rather than the various RCU
> > C-language source files.
> >
> > The patch below removes the error messages for me. Is this what you
> > had in mind? (Might need other options at some point, but somewhere
> > to start.)
> >
>
> Yes, much better. Thanks.
>
> Just some missing kernel-doc on parameters mostly remaining:
I have now fixed a number of these, thank you.
Any hints for how to represent code samples within a "/**" comment?
/home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
/home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
Thanx, Paul
> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
>
> >
> > ------------------------------------------------------------------------
> >
> > diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> > index 8282099e0cbf..30b2666bf494 100644
> > --- a/Documentation/core-api/kernel-api.rst
> > +++ b/Documentation/core-api/kernel-api.rst
> > @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> > ----------------------
> >
> > .. kernel-doc:: include/linux/rcupdate.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rcupdate_wait.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rcutree.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/tree.c
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/tree_plugin.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/tree_exp.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/update.c
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/srcu.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/srcutree.c
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rculist_bl.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rculist.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rculist_nulls.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: include/linux/rcu_sync.h
> > - :external:
> > + :export
> >
> > .. kernel-doc:: kernel/rcu/sync.c
> > - :external:
> > + :export
> >
> >
> > --
>
>
> --
> ~Randy
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 19:49 ` Paul E. McKenney
@ 2017-09-18 2:40 ` Paul E. McKenney
2017-09-18 7:30 ` Markus Heiser
2017-10-16 19:58 ` Randy Dunlap
1 sibling, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-09-18 2:40 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Sun, Sep 17, 2017 at 12:49:10PM -0700, Paul E. McKenney wrote:
> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> > On 09/17/17 10:47, Paul E. McKenney wrote:
> > > On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> > >> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> > >>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> > >>>
> > >>> .. kernel-doc:: include/linux/rcupdate.h
> > >>> :external:
> > >>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> > >>> unknown option: "external".
> > >>
> > >> $ grep external include/linux/rcupdate.h
> > >> * by a single external-to-structure RCU-protected pointer, then you may
> > >> * external-to-structure pointer -after- you have completely initialized
> > >>
> > >> Do these comments somehow qualify as an "external" option? If so, how
> > >> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> > >> the word "external"?
> > >>
> > >>> .. kernel-doc:: include/linux/rcupdate_wait.h
> > >>> :external:
> > >>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> > >>> unknown option: "external".
> > >>
> > >> $ grep external include/linux/rcupdate_wait.h
> > >>
> > >> There is no occurrence of the string "external" in this file. So this
> > >> "external" option is unknown to me as well. So, any hints on how I
> > >> should interpret these error messages?
> > >
> > > And thanks to Akira Yokosawa for pointing out my confusion in reading
> > > these error messages. The line numbers of course apply to the file
> > > Documentation/core-api/kernel-api.rst rather than the various RCU
> > > C-language source files.
> > >
> > > The patch below removes the error messages for me. Is this what you
> > > had in mind? (Might need other options at some point, but somewhere
> > > to start.)
> > >
> >
> > Yes, much better. Thanks.
> >
> > Just some missing kernel-doc on parameters mostly remaining:
>
> I have now fixed a number of these, thank you.
>
> Any hints for how to represent code samples within a "/**" comment?
>
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
And after some playing around, I did get rid of the error messages.
The code-block output looks a bit strange though, hints? I preceded
the code block with "::", again at Akira's suggestion. It looks fine
except for the :c:func: and backquotes on the first and last lines.
Thanx, Paul
------------------------------------------------------------------------
:c:func:`rcu_read_lock()`;
p = rcu_dereference(gp);
long_lived = is_long_lived(p);
if (long_lived) {
if (!atomic_inc_not_zero(p->refcnt))
long_lived = false;
else
p = rcu_pointer_handoff(p);
}
:c:func:`rcu_read_unlock()`;
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 1:26 rcu kernel-doc issues (4.14-rc1) Randy Dunlap
2017-09-17 4:41 ` Paul E. McKenney
@ 2017-09-18 6:43 ` Markus Heiser
1 sibling, 0 replies; 20+ messages in thread
From: Markus Heiser @ 2017-09-18 6:43 UTC (permalink / raw)
To: Randy Dunlap
Cc: LKML, Linux Doc Mailing List, Paul E. McKenney, Jonathan Corbet
> Am 17.09.2017 um 03:26 schrieb Randy Dunlap <rdunlap@infradead.org>:
>
> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>
> .. kernel-doc:: include/linux/rcupdate.h
> :external:
> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> unknown option: "external".
FYI: about kernel-doc option (export) take a look at
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
-- Markus --
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-18 2:40 ` Paul E. McKenney
@ 2017-09-18 7:30 ` Markus Heiser
2017-09-18 14:21 ` Paul E. McKenney
0 siblings, 1 reply; 20+ messages in thread
From: Markus Heiser @ 2017-09-18 7:30 UTC (permalink / raw)
To: Paul E. McKenney, Jonathan Corbet
Cc: Randy Dunlap, LKML, Linux Doc Mailing List
> Am 18.09.2017 um 04:40 schrieb Paul E. McKenney <paulmck@linux.vnet.ibm.com>:
[...]
> And after some playing around, I did get rid of the error messages.
> The code-block output looks a bit strange though, hints? I preceded
> the code block with "::", again at Akira's suggestion. It looks fine
> except for the :c:func: and backquotes on the first and last lines.
>
> Thanx, Paul
>
> ------------------------------------------------------------------------
>
> :c:func:`rcu_read_lock()`;
> p = rcu_dereference(gp);
> long_lived = is_long_lived(p);
> if (long_lived) {
> if (!atomic_inc_not_zero(p->refcnt))
> long_lived = false;
> else
> p = rcu_pointer_handoff(p);
> }
> :c:func:`rcu_read_unlock()`;
FYI:
such replacements in code-blocks are comming from the "Highlights
and cross-references" see:
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references
and this is still a bug in the kernel-doc parser:
https://www.mail-archive.com/linux-doc@vger.kernel.org/msg14409.html
-- Markus --
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-18 7:30 ` Markus Heiser
@ 2017-09-18 14:21 ` Paul E. McKenney
0 siblings, 0 replies; 20+ messages in thread
From: Paul E. McKenney @ 2017-09-18 14:21 UTC (permalink / raw)
To: Markus Heiser; +Cc: Jonathan Corbet, Randy Dunlap, LKML, Linux Doc Mailing List
On Mon, Sep 18, 2017 at 09:30:01AM +0200, Markus Heiser wrote:
>
> > Am 18.09.2017 um 04:40 schrieb Paul E. McKenney <paulmck@linux.vnet.ibm.com>:
> [...]
> > And after some playing around, I did get rid of the error messages.
> > The code-block output looks a bit strange though, hints? I preceded
> > the code block with "::", again at Akira's suggestion. It looks fine
> > except for the :c:func: and backquotes on the first and last lines.
> >
> > Thanx, Paul
> >
> > ------------------------------------------------------------------------
> >
> > :c:func:`rcu_read_lock()`;
> > p = rcu_dereference(gp);
> > long_lived = is_long_lived(p);
> > if (long_lived) {
> > if (!atomic_inc_not_zero(p->refcnt))
> > long_lived = false;
> > else
> > p = rcu_pointer_handoff(p);
> > }
> > :c:func:`rcu_read_unlock()`;
>
> FYI:
>
> such replacements in code-blocks are comming from the "Highlights
> and cross-references" see:
>
> https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references
>
> and this is still a bug in the kernel-doc parser:
>
> https://www.mail-archive.com/linux-doc@vger.kernel.org/msg14409.html
Thank you for the pointer! I will try it out. Except that v4.14-rc1
apparently needs a later version of sphinx...
Thanx, Paul
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-09-17 19:49 ` Paul E. McKenney
2017-09-18 2:40 ` Paul E. McKenney
@ 2017-10-16 19:58 ` Randy Dunlap
2017-10-16 20:07 ` Paul E. McKenney
1 sibling, 1 reply; 20+ messages in thread
From: Randy Dunlap @ 2017-10-16 19:58 UTC (permalink / raw)
To: paulmck; +Cc: LKML, linux-doc, Jonathan Corbet
Hi Jonathan and Paul,
Please include these fixes before 4.14 final.
Thanks.
On 09/17/17 12:49, Paul E. McKenney wrote:
> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
>> On 09/17/17 10:47, Paul E. McKenney wrote:
>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>>>>>
>>>>> .. kernel-doc:: include/linux/rcupdate.h
>>>>> :external:
>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
>>>>> unknown option: "external".
>>>>
>>>> $ grep external include/linux/rcupdate.h
>>>> * by a single external-to-structure RCU-protected pointer, then you may
>>>> * external-to-structure pointer -after- you have completely initialized
>>>>
>>>> Do these comments somehow qualify as an "external" option? If so, how
>>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
>>>> the word "external"?
>>>>
>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>>>> :external:
>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
>>>>> unknown option: "external".
>>>>
>>>> $ grep external include/linux/rcupdate_wait.h
>>>>
>>>> There is no occurrence of the string "external" in this file. So this
>>>> "external" option is unknown to me as well. So, any hints on how I
>>>> should interpret these error messages?
>>>
>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
>>> these error messages. The line numbers of course apply to the file
>>> Documentation/core-api/kernel-api.rst rather than the various RCU
>>> C-language source files.
>>>
>>> The patch below removes the error messages for me. Is this what you
>>> had in mind? (Might need other options at some point, but somewhere
>>> to start.)
>>>
>>
>> Yes, much better. Thanks.
>>
>> Just some missing kernel-doc on parameters mostly remaining:
>
> I have now fixed a number of these, thank you.
>
> Any hints for how to represent code samples within a "/**" comment?
>
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> Thanx, Paul
>
>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
>> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
>> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
>> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
>> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
>> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
>> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
>> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
>> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
>> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
>> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
>>
>>>
>>> ------------------------------------------------------------------------
>>>
>>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
>>> index 8282099e0cbf..30b2666bf494 100644
>>> --- a/Documentation/core-api/kernel-api.rst
>>> +++ b/Documentation/core-api/kernel-api.rst
>>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
>>> ----------------------
>>>
>>> .. kernel-doc:: include/linux/rcupdate.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rcutree.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/tree.c
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/tree_plugin.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/tree_exp.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/update.c
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/srcu.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/srcutree.c
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rculist_bl.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rculist.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rculist_nulls.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: include/linux/rcu_sync.h
>>> - :external:
>>> + :export
>>>
>>> .. kernel-doc:: kernel/rcu/sync.c
>>> - :external:
>>> + :export
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 19:58 ` Randy Dunlap
@ 2017-10-16 20:07 ` Paul E. McKenney
2017-10-16 20:18 ` Randy Dunlap
0 siblings, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-10-16 20:07 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
> Hi Jonathan and Paul,
>
> Please include these fixes before 4.14 final.
Hello, Randy,
I currently have them queued up for the 4.15 merge window. Will that
work for you?
Thanx, Paul
> Thanks.
>
> On 09/17/17 12:49, Paul E. McKenney wrote:
> > On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> >> On 09/17/17 10:47, Paul E. McKenney wrote:
> >>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>> :external:
> >>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> >>>>> unknown option: "external".
> >>>>
> >>>> $ grep external include/linux/rcupdate.h
> >>>> * by a single external-to-structure RCU-protected pointer, then you may
> >>>> * external-to-structure pointer -after- you have completely initialized
> >>>>
> >>>> Do these comments somehow qualify as an "external" option? If so, how
> >>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> >>>> the word "external"?
> >>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>> :external:
> >>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> >>>>> unknown option: "external".
> >>>>
> >>>> $ grep external include/linux/rcupdate_wait.h
> >>>>
> >>>> There is no occurrence of the string "external" in this file. So this
> >>>> "external" option is unknown to me as well. So, any hints on how I
> >>>> should interpret these error messages?
> >>>
> >>> And thanks to Akira Yokosawa for pointing out my confusion in reading
> >>> these error messages. The line numbers of course apply to the file
> >>> Documentation/core-api/kernel-api.rst rather than the various RCU
> >>> C-language source files.
> >>>
> >>> The patch below removes the error messages for me. Is this what you
> >>> had in mind? (Might need other options at some point, but somewhere
> >>> to start.)
> >>>
> >>
> >> Yes, much better. Thanks.
> >>
> >> Just some missing kernel-doc on parameters mostly remaining:
> >
> > I have now fixed a number of these, thank you.
> >
> > Any hints for how to represent code samples within a "/**" comment?
> >
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
> > /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
> >
> > Thanx, Paul
> >
> >> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
> >> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
> >> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
> >> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
> >> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
> >> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
> >> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
> >> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
> >> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
> >> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
> >> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
> >> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
> >> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
> >> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
> >>
> >>>
> >>> ------------------------------------------------------------------------
> >>>
> >>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> >>> index 8282099e0cbf..30b2666bf494 100644
> >>> --- a/Documentation/core-api/kernel-api.rst
> >>> +++ b/Documentation/core-api/kernel-api.rst
> >>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> >>> ----------------------
> >>>
> >>> .. kernel-doc:: include/linux/rcupdate.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rcutree.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/tree.c
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/tree_plugin.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/tree_exp.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/update.c
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/srcu.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/srcutree.c
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rculist_bl.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rculist.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rculist_nulls.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: include/linux/rcu_sync.h
> >>> - :external:
> >>> + :export
> >>>
> >>> .. kernel-doc:: kernel/rcu/sync.c
> >>> - :external:
> >>> + :export
>
>
> --
> ~Randy
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 20:07 ` Paul E. McKenney
@ 2017-10-16 20:18 ` Randy Dunlap
2017-10-16 20:26 ` Paul E. McKenney
0 siblings, 1 reply; 20+ messages in thread
From: Randy Dunlap @ 2017-10-16 20:18 UTC (permalink / raw)
To: paulmck; +Cc: LKML, linux-doc, Jonathan Corbet
On 10/16/17 13:07, Paul E. McKenney wrote:
> On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
>> Hi Jonathan and Paul,
>>
>> Please include these fixes before 4.14 final.
>
> Hello, Randy,
>
> I currently have them queued up for the 4.15 merge window. Will that
> work for you?
They should be fixed in 4.14 final IMO.
> Thanx, Paul
>
>> Thanks.
>>
>> On 09/17/17 12:49, Paul E. McKenney wrote:
>>> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
>>>> On 09/17/17 10:47, Paul E. McKenney wrote:
>>>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
>>>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
>>>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcupdate.h
>>>>>>> :external:
>>>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
>>>>>>> unknown option: "external".
>>>>>>
>>>>>> $ grep external include/linux/rcupdate.h
>>>>>> * by a single external-to-structure RCU-protected pointer, then you may
>>>>>> * external-to-structure pointer -after- you have completely initialized
>>>>>>
>>>>>> Do these comments somehow qualify as an "external" option? If so, how
>>>>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
>>>>>> the word "external"?
>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>>>>>> :external:
>>>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
>>>>>>> unknown option: "external".
>>>>>>
>>>>>> $ grep external include/linux/rcupdate_wait.h
>>>>>>
>>>>>> There is no occurrence of the string "external" in this file. So this
>>>>>> "external" option is unknown to me as well. So, any hints on how I
>>>>>> should interpret these error messages?
>>>>>
>>>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
>>>>> these error messages. The line numbers of course apply to the file
>>>>> Documentation/core-api/kernel-api.rst rather than the various RCU
>>>>> C-language source files.
>>>>>
>>>>> The patch below removes the error messages for me. Is this what you
>>>>> had in mind? (Might need other options at some point, but somewhere
>>>>> to start.)
>>>>>
>>>>
>>>> Yes, much better. Thanks.
>>>>
>>>> Just some missing kernel-doc on parameters mostly remaining:
>>>
>>> I have now fixed a number of these, thank you.
>>>
>>> Any hints for how to represent code samples within a "/**" comment?
>>>
>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
>>>
>>> Thanx, Paul
>>>
>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
>>>> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
>>>> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
>>>> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
>>>> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
>>>> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
>>>> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
>>>> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
>>>>
>>>>>
>>>>> ------------------------------------------------------------------------
>>>>>
>>>>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
>>>>> index 8282099e0cbf..30b2666bf494 100644
>>>>> --- a/Documentation/core-api/kernel-api.rst
>>>>> +++ b/Documentation/core-api/kernel-api.rst
>>>>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
>>>>> ----------------------
>>>>>
>>>>> .. kernel-doc:: include/linux/rcupdate.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rcutree.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/tree.c
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/tree_plugin.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/tree_exp.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/update.c
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/srcu.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/srcutree.c
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rculist_bl.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rculist.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rculist_nulls.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: include/linux/rcu_sync.h
>>>>> - :external:
>>>>> + :export
>>>>>
>>>>> .. kernel-doc:: kernel/rcu/sync.c
>>>>> - :external:
>>>>> + :export
>>
>>
>> --
>> ~Randy
>>
>
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 20:18 ` Randy Dunlap
@ 2017-10-16 20:26 ` Paul E. McKenney
2017-10-16 21:46 ` Randy Dunlap
2017-10-18 16:03 ` Jonathan Corbet
0 siblings, 2 replies; 20+ messages in thread
From: Paul E. McKenney @ 2017-10-16 20:26 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Mon, Oct 16, 2017 at 01:18:14PM -0700, Randy Dunlap wrote:
> On 10/16/17 13:07, Paul E. McKenney wrote:
> > On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
> >> Hi Jonathan and Paul,
> >>
> >> Please include these fixes before 4.14 final.
> >
> > Hello, Randy,
> >
> > I currently have them queued up for the 4.15 merge window. Will that
> > work for you?
>
> They should be fixed in 4.14 final IMO.
OK, how about if I submit them to the 4.15 merge window, but add the
appropriate -stable tags to get them backported? Yes, these are bugs,
but I cannot in good conscience claim that they are v4.14 regressions.
But if Jon agrees with you, I will of course create a patch series,
pull request, or whatever and send it along to him.
Thanx, Paul
> >> Thanks.
> >>
> >> On 09/17/17 12:49, Paul E. McKenney wrote:
> >>> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> >>>> On 09/17/17 10:47, Paul E. McKenney wrote:
> >>>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >>>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>>>> :external:
> >>>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> >>>>>>> unknown option: "external".
> >>>>>>
> >>>>>> $ grep external include/linux/rcupdate.h
> >>>>>> * by a single external-to-structure RCU-protected pointer, then you may
> >>>>>> * external-to-structure pointer -after- you have completely initialized
> >>>>>>
> >>>>>> Do these comments somehow qualify as an "external" option? If so, how
> >>>>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> >>>>>> the word "external"?
> >>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>>>> :external:
> >>>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> >>>>>>> unknown option: "external".
> >>>>>>
> >>>>>> $ grep external include/linux/rcupdate_wait.h
> >>>>>>
> >>>>>> There is no occurrence of the string "external" in this file. So this
> >>>>>> "external" option is unknown to me as well. So, any hints on how I
> >>>>>> should interpret these error messages?
> >>>>>
> >>>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
> >>>>> these error messages. The line numbers of course apply to the file
> >>>>> Documentation/core-api/kernel-api.rst rather than the various RCU
> >>>>> C-language source files.
> >>>>>
> >>>>> The patch below removes the error messages for me. Is this what you
> >>>>> had in mind? (Might need other options at some point, but somewhere
> >>>>> to start.)
> >>>>>
> >>>>
> >>>> Yes, much better. Thanks.
> >>>>
> >>>> Just some missing kernel-doc on parameters mostly remaining:
> >>>
> >>> I have now fixed a number of these, thank you.
> >>>
> >>> Any hints for how to represent code samples within a "/**" comment?
> >>>
> >>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
> >>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
> >>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
> >>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
> >>>
> >>> Thanx, Paul
> >>>
> >>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
> >>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
> >>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
> >>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
> >>>> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
> >>>> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
> >>>> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
> >>>> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
> >>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
> >>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
> >>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
> >>>> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
> >>>> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
> >>>> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
> >>>>
> >>>>>
> >>>>> ------------------------------------------------------------------------
> >>>>>
> >>>>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> >>>>> index 8282099e0cbf..30b2666bf494 100644
> >>>>> --- a/Documentation/core-api/kernel-api.rst
> >>>>> +++ b/Documentation/core-api/kernel-api.rst
> >>>>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> >>>>> ----------------------
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcutree.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/tree.c
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/tree_plugin.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/tree_exp.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/update.c
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/srcu.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/srcutree.c
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rculist_bl.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rculist.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rculist_nulls.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: include/linux/rcu_sync.h
> >>>>> - :external:
> >>>>> + :export
> >>>>>
> >>>>> .. kernel-doc:: kernel/rcu/sync.c
> >>>>> - :external:
> >>>>> + :export
> >>
> >>
> >> --
> >> ~Randy
> >>
> >
>
>
> --
> ~Randy
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 20:26 ` Paul E. McKenney
@ 2017-10-16 21:46 ` Randy Dunlap
2017-10-16 23:35 ` Paul E. McKenney
2017-10-18 16:03 ` Jonathan Corbet
1 sibling, 1 reply; 20+ messages in thread
From: Randy Dunlap @ 2017-10-16 21:46 UTC (permalink / raw)
To: paulmck; +Cc: LKML, linux-doc, Jonathan Corbet
On 10/16/17 13:26, Paul E. McKenney wrote:
> On Mon, Oct 16, 2017 at 01:18:14PM -0700, Randy Dunlap wrote:
>> On 10/16/17 13:07, Paul E. McKenney wrote:
>>> On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
>>>> Hi Jonathan and Paul,
>>>>
>>>> Please include these fixes before 4.14 final.
>>>
>>> Hello, Randy,
>>>
>>> I currently have them queued up for the 4.15 merge window. Will that
>>> work for you?
>>
>> They should be fixed in 4.14 final IMO.
>
> OK, how about if I submit them to the 4.15 merge window, but add the
> appropriate -stable tags to get them backported? Yes, these are bugs,
> but I cannot in good conscience claim that they are v4.14 regressions.
>
> But if Jon agrees with you, I will of course create a patch series,
> pull request, or whatever and send it along to him.
You or Jon could just revert this commit then:
commit 764f80798b958f74dbf0c6e76a8294d183dd9c16
Author: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Date: Tue Jul 4 14:42:20 2017 -0700
doc: Add RCU files to docbook-generation files
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
But the current condition is bad.
> Thanx, Paul
>
>>>> Thanks.
>>>>
>>>> On 09/17/17 12:49, Paul E. McKenney wrote:
>>>>> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
>>>>>> On 09/17/17 10:47, Paul E. McKenney wrote:
>>>>>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
>>>>>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
>>>>>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
>>>>>>>>>
>>>>>>>>> .. kernel-doc:: include/linux/rcupdate.h
>>>>>>>>> :external:
>>>>>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
>>>>>>>>> unknown option: "external".
>>>>>>>>
>>>>>>>> $ grep external include/linux/rcupdate.h
>>>>>>>> * by a single external-to-structure RCU-protected pointer, then you may
>>>>>>>> * external-to-structure pointer -after- you have completely initialized
>>>>>>>>
>>>>>>>> Do these comments somehow qualify as an "external" option? If so, how
>>>>>>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
>>>>>>>> the word "external"?
>>>>>>>>
>>>>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>>>>>>>> :external:
>>>>>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
>>>>>>>>> unknown option: "external".
>>>>>>>>
>>>>>>>> $ grep external include/linux/rcupdate_wait.h
>>>>>>>>
>>>>>>>> There is no occurrence of the string "external" in this file. So this
>>>>>>>> "external" option is unknown to me as well. So, any hints on how I
>>>>>>>> should interpret these error messages?
>>>>>>>
>>>>>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
>>>>>>> these error messages. The line numbers of course apply to the file
>>>>>>> Documentation/core-api/kernel-api.rst rather than the various RCU
>>>>>>> C-language source files.
>>>>>>>
>>>>>>> The patch below removes the error messages for me. Is this what you
>>>>>>> had in mind? (Might need other options at some point, but somewhere
>>>>>>> to start.)
>>>>>>>
>>>>>>
>>>>>> Yes, much better. Thanks.
>>>>>>
>>>>>> Just some missing kernel-doc on parameters mostly remaining:
>>>>>
>>>>> I have now fixed a number of these, thank you.
>>>>>
>>>>> Any hints for how to represent code samples within a "/**" comment?
>>>>>
>>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
>>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
>>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
>>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
>>>>>
>>>>> Thanx, Paul
>>>>>
>>>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
>>>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
>>>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
>>>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
>>>>>> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
>>>>>> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
>>>>>> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
>>>>>> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
>>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
>>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
>>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
>>>>>> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
>>>>>> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
>>>>>> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
>>>>>>
>>>>>>>
>>>>>>> ------------------------------------------------------------------------
>>>>>>>
>>>>>>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
>>>>>>> index 8282099e0cbf..30b2666bf494 100644
>>>>>>> --- a/Documentation/core-api/kernel-api.rst
>>>>>>> +++ b/Documentation/core-api/kernel-api.rst
>>>>>>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
>>>>>>> ----------------------
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcupdate.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcutree.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/tree.c
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/tree_plugin.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/tree_exp.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/update.c
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/srcu.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/srcutree.c
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rculist_bl.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rculist.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rculist_nulls.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: include/linux/rcu_sync.h
>>>>>>> - :external:
>>>>>>> + :export
>>>>>>>
>>>>>>> .. kernel-doc:: kernel/rcu/sync.c
>>>>>>> - :external:
>>>>>>> + :export
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 21:46 ` Randy Dunlap
@ 2017-10-16 23:35 ` Paul E. McKenney
0 siblings, 0 replies; 20+ messages in thread
From: Paul E. McKenney @ 2017-10-16 23:35 UTC (permalink / raw)
To: Randy Dunlap; +Cc: LKML, linux-doc, Jonathan Corbet
On Mon, Oct 16, 2017 at 02:46:15PM -0700, Randy Dunlap wrote:
> On 10/16/17 13:26, Paul E. McKenney wrote:
> > On Mon, Oct 16, 2017 at 01:18:14PM -0700, Randy Dunlap wrote:
> >> On 10/16/17 13:07, Paul E. McKenney wrote:
> >>> On Mon, Oct 16, 2017 at 12:58:28PM -0700, Randy Dunlap wrote:
> >>>> Hi Jonathan and Paul,
> >>>>
> >>>> Please include these fixes before 4.14 final.
> >>>
> >>> Hello, Randy,
> >>>
> >>> I currently have them queued up for the 4.15 merge window. Will that
> >>> work for you?
> >>
> >> They should be fixed in 4.14 final IMO.
> >
> > OK, how about if I submit them to the 4.15 merge window, but add the
> > appropriate -stable tags to get them backported? Yes, these are bugs,
> > but I cannot in good conscience claim that they are v4.14 regressions.
> >
> > But if Jon agrees with you, I will of course create a patch series,
> > pull request, or whatever and send it along to him.
>
> You or Jon could just revert this commit then:
>
> commit 764f80798b958f74dbf0c6e76a8294d183dd9c16
> Author: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
> Date: Tue Jul 4 14:42:20 2017 -0700
>
> doc: Add RCU files to docbook-generation files
>
> Suggested-by: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
>
> But the current condition is bad.
Jon, what would you prefer?
Thanx, Paul
> >>>> Thanks.
> >>>>
> >>>> On 09/17/17 12:49, Paul E. McKenney wrote:
> >>>>> On Sun, Sep 17, 2017 at 10:57:42AM -0700, Randy Dunlap wrote:
> >>>>>> On 09/17/17 10:47, Paul E. McKenney wrote:
> >>>>>>> On Sat, Sep 16, 2017 at 09:41:45PM -0700, Paul E. McKenney wrote:
> >>>>>>>> On Sat, Sep 16, 2017 at 06:26:04PM -0700, Randy Dunlap wrote:
> >>>>>>>>> On 4.14-rc1, I am seeing lots of warnings on rcu kernel-doc:
> >>>>>>>>>
> >>>>>>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>>>>>> :external:
> >>>>>>>>> ./Documentation/core-api/kernel-api.rst:357: ERROR: Error in "kernel-doc" directive:
> >>>>>>>>> unknown option: "external".
> >>>>>>>>
> >>>>>>>> $ grep external include/linux/rcupdate.h
> >>>>>>>> * by a single external-to-structure RCU-protected pointer, then you may
> >>>>>>>> * external-to-structure pointer -after- you have completely initialized
> >>>>>>>>
> >>>>>>>> Do these comments somehow qualify as an "external" option? If so, how
> >>>>>>>> do I tell kernel-doc to ignore them? Or must I reword them to avoid
> >>>>>>>> the word "external"?
> >>>>>>>>
> >>>>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>>>>>> :external:
> >>>>>>>>> ./Documentation/core-api/kernel-api.rst:360: ERROR: Error in "kernel-doc" directive:
> >>>>>>>>> unknown option: "external".
> >>>>>>>>
> >>>>>>>> $ grep external include/linux/rcupdate_wait.h
> >>>>>>>>
> >>>>>>>> There is no occurrence of the string "external" in this file. So this
> >>>>>>>> "external" option is unknown to me as well. So, any hints on how I
> >>>>>>>> should interpret these error messages?
> >>>>>>>
> >>>>>>> And thanks to Akira Yokosawa for pointing out my confusion in reading
> >>>>>>> these error messages. The line numbers of course apply to the file
> >>>>>>> Documentation/core-api/kernel-api.rst rather than the various RCU
> >>>>>>> C-language source files.
> >>>>>>>
> >>>>>>> The patch below removes the error messages for me. Is this what you
> >>>>>>> had in mind? (Might need other options at some point, but somewhere
> >>>>>>> to start.)
> >>>>>>>
> >>>>>>
> >>>>>> Yes, much better. Thanks.
> >>>>>>
> >>>>>> Just some missing kernel-doc on parameters mostly remaining:
> >>>>>
> >>>>> I have now fixed a number of these, thank you.
> >>>>>
> >>>>> Any hints for how to represent code samples within a "/**" comment?
> >>>>>
> >>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:559: ERROR: Unexpected indentation.
> >>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:563: WARNING: Block quote ends without a blank line; unexpected unindent.
> >>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:777: ERROR: Unexpected indentation.
> >>>>> /home/git/linux-2.6-tip/include/linux/rcupdate.h:778: WARNING: Block quote ends without a blank line; unexpected unindent.
> >>>>>
> >>>>> Thanx, Paul
> >>>>>
> >>>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'p'
> >>>>>> ../include/linux/rcupdate.h:818: warning: No description found for parameter 'v'
> >>>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'p'
> >>>>>> ../include/linux/rcupdate.h:826: warning: No description found for parameter 'v'
> >>>>>> ../include/linux/srcu.h:95: warning: No description found for parameter 'sp'
> >>>>>> ../kernel/rcu/srcutree.c:873: warning: No description found for parameter 'rhp'
> >>>>>> ../kernel/rcu/srcutree.c:873: warning: Excess function parameter 'head' description in 'call_srcu'
> >>>>>> ../include/linux/rculist.h:302: warning: Incorrect use of kernel-doc format: * list_first_or_null_rcu - get the first element from a list
> >>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'ptr'
> >>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'type'
> >>>>>> ../include/linux/rculist.h:317: warning: No description found for parameter 'member'
> >>>>>> ../kernel/rcu/sync.c:94: warning: No description found for parameter 'rsp'
> >>>>>> ../kernel/rcu/sync.c:162: warning: No description found for parameter 'rcu'
> >>>>>> ../kernel/rcu/sync.c:162: warning: Excess function parameter 'rsp' description in 'rcu_sync_func'
> >>>>>>
> >>>>>>>
> >>>>>>> ------------------------------------------------------------------------
> >>>>>>>
> >>>>>>> diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
> >>>>>>> index 8282099e0cbf..30b2666bf494 100644
> >>>>>>> --- a/Documentation/core-api/kernel-api.rst
> >>>>>>> +++ b/Documentation/core-api/kernel-api.rst
> >>>>>>> @@ -352,44 +352,44 @@ Read-Copy Update (RCU)
> >>>>>>> ----------------------
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcupdate.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcupdate_wait.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcutree.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/tree.c
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/tree_plugin.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/tree_exp.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/update.c
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/srcu.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/srcutree.c
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rculist_bl.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rculist.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rculist_nulls.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: include/linux/rcu_sync.h
> >>>>>>> - :external:
> >>>>>>> + :export
> >>>>>>>
> >>>>>>> .. kernel-doc:: kernel/rcu/sync.c
> >>>>>>> - :external:
> >>>>>>> + :export
>
>
> --
> ~Randy
>
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-16 20:26 ` Paul E. McKenney
2017-10-16 21:46 ` Randy Dunlap
@ 2017-10-18 16:03 ` Jonathan Corbet
2017-10-18 16:27 ` Paul E. McKenney
1 sibling, 1 reply; 20+ messages in thread
From: Jonathan Corbet @ 2017-10-18 16:03 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: Randy Dunlap, LKML, linux-doc
On Mon, 16 Oct 2017 13:26:19 -0700
"Paul E. McKenney" <paulmck@linux.vnet.ibm.com> wrote:
> OK, how about if I submit them to the 4.15 merge window, but add the
> appropriate -stable tags to get them backported? Yes, these are bugs,
> but I cannot in good conscience claim that they are v4.14 regressions.
>
> But if Jon agrees with you, I will of course create a patch series,
> pull request, or whatever and send it along to him.
[Sorry for being slow ... $EXCUSES ... ]
One could argue that they are indeed a regression; they introduced a bunch
of build errors into 4.14. I think it would be better to see it fixed if
possible. I don't care that much about how it gets there; Paul, I can
send it Linusward if you don't want to.
Thanks,
jon
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-18 16:03 ` Jonathan Corbet
@ 2017-10-18 16:27 ` Paul E. McKenney
2017-10-18 16:36 ` Jonathan Corbet
0 siblings, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-10-18 16:27 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Randy Dunlap, LKML, linux-doc
On Wed, Oct 18, 2017 at 10:03:40AM -0600, Jonathan Corbet wrote:
> On Mon, 16 Oct 2017 13:26:19 -0700
> "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> wrote:
>
> > OK, how about if I submit them to the 4.15 merge window, but add the
> > appropriate -stable tags to get them backported? Yes, these are bugs,
> > but I cannot in good conscience claim that they are v4.14 regressions.
> >
> > But if Jon agrees with you, I will of course create a patch series,
> > pull request, or whatever and send it along to him.
>
> [Sorry for being slow ... $EXCUSES ... ]
>
> One could argue that they are indeed a regression; they introduced a bunch
> of build errors into 4.14. I think it would be better to see it fixed if
> possible. I don't care that much about how it gets there; Paul, I can
> send it Linusward if you don't want to.
I never have pushed directly to Linus, so I might as well get started
doing so.
On a related topic... Is there anything that test-builds docbook prior
to patches hitting mainline? My experience indicates that the answer is
"no".
Thanx, Paul
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-18 16:27 ` Paul E. McKenney
@ 2017-10-18 16:36 ` Jonathan Corbet
2017-10-20 16:42 ` Paul E. McKenney
0 siblings, 1 reply; 20+ messages in thread
From: Jonathan Corbet @ 2017-10-18 16:36 UTC (permalink / raw)
To: Paul E. McKenney; +Cc: Randy Dunlap, LKML, linux-doc
On Wed, 18 Oct 2017 09:27:01 -0700
"Paul E. McKenney" <paulmck@linux.vnet.ibm.com> wrote:
> On a related topic... Is there anything that test-builds docbook prior
> to patches hitting mainline? My experience indicates that the answer is
> "no".
The zero-day robot is said to be testing for new doc-build errors, but I
haven't actually seen much of that.
jon
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-18 16:36 ` Jonathan Corbet
@ 2017-10-20 16:42 ` Paul E. McKenney
2017-10-20 16:53 ` Randy Dunlap
0 siblings, 1 reply; 20+ messages in thread
From: Paul E. McKenney @ 2017-10-20 16:42 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: Randy Dunlap, LKML, linux-doc
On Wed, Oct 18, 2017 at 10:36:47AM -0600, Jonathan Corbet wrote:
> On Wed, 18 Oct 2017 09:27:01 -0700
> "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> wrote:
>
> > On a related topic... Is there anything that test-builds docbook prior
> > to patches hitting mainline? My experience indicates that the answer is
> > "no".
>
> The zero-day robot is said to be testing for new doc-build errors, but I
> haven't actually seen much of that.
Well, on the good side, Linus did take the fixes. I will leave it
to you guys to sort things as needed with Fengguang. ;-)
Thanx, Paul
^ permalink raw reply [flat|nested] 20+ messages in thread
* Re: rcu kernel-doc issues (4.14-rc1)
2017-10-20 16:42 ` Paul E. McKenney
@ 2017-10-20 16:53 ` Randy Dunlap
0 siblings, 0 replies; 20+ messages in thread
From: Randy Dunlap @ 2017-10-20 16:53 UTC (permalink / raw)
To: paulmck, Jonathan Corbet; +Cc: LKML, linux-doc
On 10/20/17 09:42, Paul E. McKenney wrote:
> On Wed, Oct 18, 2017 at 10:36:47AM -0600, Jonathan Corbet wrote:
>> On Wed, 18 Oct 2017 09:27:01 -0700
>> "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> wrote:
>>
>>> On a related topic... Is there anything that test-builds docbook prior
>>> to patches hitting mainline? My experience indicates that the answer is
>>> "no".
>>
>> The zero-day robot is said to be testing for new doc-build errors, but I
>> haven't actually seen much of that.
>
> Well, on the good side, Linus did take the fixes. I will leave it
> to you guys to sort things as needed with Fengguang. ;-)
Thanks.
--
~Randy
^ permalink raw reply [flat|nested] 20+ messages in thread
end of thread, other threads:[~2017-10-20 16:53 UTC | newest]
Thread overview: 20+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-09-17 1:26 rcu kernel-doc issues (4.14-rc1) Randy Dunlap
2017-09-17 4:41 ` Paul E. McKenney
2017-09-17 17:47 ` Paul E. McKenney
2017-09-17 17:57 ` Randy Dunlap
2017-09-17 19:49 ` Paul E. McKenney
2017-09-18 2:40 ` Paul E. McKenney
2017-09-18 7:30 ` Markus Heiser
2017-09-18 14:21 ` Paul E. McKenney
2017-10-16 19:58 ` Randy Dunlap
2017-10-16 20:07 ` Paul E. McKenney
2017-10-16 20:18 ` Randy Dunlap
2017-10-16 20:26 ` Paul E. McKenney
2017-10-16 21:46 ` Randy Dunlap
2017-10-16 23:35 ` Paul E. McKenney
2017-10-18 16:03 ` Jonathan Corbet
2017-10-18 16:27 ` Paul E. McKenney
2017-10-18 16:36 ` Jonathan Corbet
2017-10-20 16:42 ` Paul E. McKenney
2017-10-20 16:53 ` Randy Dunlap
2017-09-18 6:43 ` Markus Heiser
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).