Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1733361 > unrolled thread

rcu kernel-doc issues (4.14-rc1)

Back to article view | Back to linux.kernel

Contents

  rcu kernel-doc issues (4.14-rc1) Randy Dunlap <rdunlap@infradead.org> - 2017-09-17 03:30 +0200
    Re: rcu kernel-doc issues (4.14-rc1) "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2017-09-17 06:50 +0200
      Re: rcu kernel-doc issues (4.14-rc1) "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2017-09-17 19:50 +0200
        Re: rcu kernel-doc issues (4.14-rc1) Randy Dunlap <rdunlap@infradead.org> - 2017-09-17 20:00 +0200
          Re: rcu kernel-doc issues (4.14-rc1) "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2017-09-17 21:50 +0200
            Re: rcu kernel-doc issues (4.14-rc1) "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2017-09-18 04:50 +0200
              Re: rcu kernel-doc issues (4.14-rc1) Markus Heiser <markus.heiser@darmarit.de> - 2017-09-18 09:40 +0200
                Re: rcu kernel-doc issues (4.14-rc1) "Paul E. McKenney" <paulmck@linux.vnet.ibm.com> - 2017-09-18 16:30 +0200
    Re: rcu kernel-doc issues (4.14-rc1) Markus Heiser <markus.heiser@darmarit.de> - 2017-09-18 08:50 +0200

#1733361 — rcu kernel-doc issues (4.14-rc1)

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

[toc] | [next] | [standalone]

#1733391

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
> 

[toc] | [prev] | [next] | [standalone]

#1733505

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
 

[toc] | [prev] | [next] | [standalone]

#1733509

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

[toc] | [prev] | [next] | [standalone]

#1733523

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
> 

[toc] | [prev] | [next] | [standalone]

#1733622

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

[toc] | [prev] | [next] | [standalone]

#1733701

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

[toc] | [prev] | [next] | [standalone]

#1734185

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

[toc] | [prev] | [next] | [standalone]

#1733680

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web