nodocs in 4.19-rcX

nodocs in 4.19-rcX

[Randy Dunlap]

Hi Jonathan,

4.19-rc contains some users of :nodocs: but that is not recognized yet,
so we get:

lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:78: ERROR: Error in "kernel-doc" directive:
unknown option: "nodocs".

.. kernel-doc:: mm/bootmem.c
   :nodocs:

lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:91: ERROR: Error in "kernel-doc" directive:
unknown option: "nodocs".

.. kernel-doc:: mm/memblock.c
   :nodocs:


Do you plan to merge the patch(es) for :nodocs: ?

thanks,
-- 
~Randy

Re: nodocs in 4.19-rcX

[Jonathan Corbet]

On Mon, 10 Sep 2018 15:51:20 -0700
Randy Dunlap <rdunlap@infradead.org> wrote:

> 4.19-rc contains some users of :nodocs: but that is not recognized yet,
> so we get:
> 
> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:78: ERROR: Error in "kernel-doc" directive:
> unknown option: "nodocs".
> 
> .. kernel-doc:: mm/bootmem.c
>    :nodocs:
> 
> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:91: ERROR: Error in "kernel-doc" directive:
> unknown option: "nodocs".
> 
> .. kernel-doc:: mm/memblock.c
>    :nodocs:
> 
> 
> Do you plan to merge the patch(es) for :nodocs: ?

:nodocs" was v1 of the patch set:

  https://lwn.net/ml/linux-doc/1529328996-16247-1-git-send-email-rppt%40linux.vnet.ibm.com/

In the end, I merged v3, which changed things (and did not contain
the :nodocs: directive:

  https://lwn.net/ml/linux-doc/1530306311-10510-1-git-send-email-rppt%40linux.vnet.ibm.com/

So I'm guessing that anything that snuck in with :nodocs: didn't get
updated.  Somehow I missed that.  Adding CC: Mike, since his
fingerprints are on all aspects of this...:)

jon

Re: nodocs in 4.19-rcX

[Randy Dunlap]

On 9/11/18 8:25 AM, Jonathan Corbet wrote:
> On Mon, 10 Sep 2018 15:51:20 -0700
> Randy Dunlap <rdunlap@infradead.org> wrote:
> 
>> 4.19-rc contains some users of :nodocs: but that is not recognized yet,
>> so we get:
>>
>> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:78: ERROR: Error in "kernel-doc" directive:
>> unknown option: "nodocs".
>>
>> .. kernel-doc:: mm/bootmem.c
>>    :nodocs:
>>
>> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:91: ERROR: Error in "kernel-doc" directive:
>> unknown option: "nodocs".
>>
>> .. kernel-doc:: mm/memblock.c
>>    :nodocs:
>>
>>
>> Do you plan to merge the patch(es) for :nodocs: ?
> 
> :nodocs" was v1 of the patch set:
> 
>   https://lwn.net/ml/linux-doc/1529328996-16247-1-git-send-email-rppt%40linux.vnet.ibm.com/
> 
> In the end, I merged v3, which changed things (and did not contain
> the :nodocs: directive:
> 
>   https://lwn.net/ml/linux-doc/1530306311-10510-1-git-send-email-rppt%40linux.vnet.ibm.com/

Yes, I found that later.

which uses (for the record)
   :functions:
with an empty functions list -- to exclude "DOC:" sections.

> So I'm guessing that anything that snuck in with :nodocs: didn't get
> updated.  Somehow I missed that.  Adding CC: Mike, since his
> fingerprints are on all aspects of this...:)

thanks.

-- 
~Randy

Re: nodocs in 4.19-rcX

[Mike Rapoport]

On Tue, Sep 11, 2018 at 08:35:18AM -0700, Randy Dunlap wrote:
> On 9/11/18 8:25 AM, Jonathan Corbet wrote:
> > On Mon, 10 Sep 2018 15:51:20 -0700
> > Randy Dunlap <rdunlap@infradead.org> wrote:
> > 
> >> 4.19-rc contains some users of :nodocs: but that is not recognized yet,
> >> so we get:
> >>
> >> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:78: ERROR: Error in "kernel-doc" directive:
> >> unknown option: "nodocs".
> >>
> >> .. kernel-doc:: mm/bootmem.c
> >>    :nodocs:
> >>
> >> lnx-419-rc3/Documentation/core-api/boot-time-mm.rst:91: ERROR: Error in "kernel-doc" directive:
> >> unknown option: "nodocs".
> >>
> >> .. kernel-doc:: mm/memblock.c
> >>    :nodocs:
> >>
> >>
> >> Do you plan to merge the patch(es) for :nodocs: ?
> > 
> > :nodocs" was v1 of the patch set:
> > 
> >   https://lwn.net/ml/linux-doc/1529328996-16247-1-git-send-email-rppt%40linux.vnet.ibm.com/
> > 
> > In the end, I merged v3, which changed things (and did not contain
> > the :nodocs: directive:
> > 
> >   https://lwn.net/ml/linux-doc/1530306311-10510-1-git-send-email-rppt%40linux.vnet.ibm.com/
> 
> Yes, I found that later.
> 
> which uses (for the record)
>    :functions:
> with an empty functions list -- to exclude "DOC:" sections.
> 
> > So I'm guessing that anything that snuck in with :nodocs: didn't get
> > updated.  Somehow I missed that.  Adding CC: Mike, since his
> > fingerprints are on all aspects of this...:)

Yeah, right. I've also missed that back then.
The fix is below.

> thanks.
> 
> -- 
> ~Randy
> 

From 1d7ab80e5388d993b7b262b24da1f3e55f30f508 Mon Sep 17 00:00:00 2001
From: Mike Rapoport <rppt@linux.vnet.ibm.com>
Date: Tue, 11 Sep 2018 19:16:36 +0300
Subject: [PATCH] docs/boot-time-mm: fix kernel-doc directive for including all
 but DOC:

There were several rounds of the patches that enabled "functions" directive
with no parameters in kerneldoc.py to allow including all the kernel-doc
comments except the DOC: sections.

Yet, the boot-time-mm.rst sneaked in with the older version of that
directive and was not updated. Update it now.

Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
---
 Documentation/core-api/boot-time-mm.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/core-api/boot-time-mm.rst b/Documentation/core-api/boot-time-mm.rst
index 03cb164..6e12e89 100644
--- a/Documentation/core-api/boot-time-mm.rst
+++ b/Documentation/core-api/boot-time-mm.rst
@@ -76,7 +76,7 @@ These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n``
 
 .. kernel-doc:: include/linux/bootmem.h
 .. kernel-doc:: mm/bootmem.c
-   :nodocs:
+   :functions:
 
 Memblock specific API
 ---------------------
@@ -89,4 +89,4 @@ really happens under the hood.
 
 .. kernel-doc:: include/linux/memblock.h
 .. kernel-doc:: mm/memblock.c
-   :nodocs:
+   :functions:
-- 
2.7.4

-- 
Sincerely yours,
Mike.

Re: nodocs in 4.19-rcX

[Randy Dunlap]

> From 1d7ab80e5388d993b7b262b24da1f3e55f30f508 Mon Sep 17 00:00:00 2001
> From: Mike Rapoport <rppt@linux.vnet.ibm.com>
> Date: Tue, 11 Sep 2018 19:16:36 +0300
> Subject: [PATCH] docs/boot-time-mm: fix kernel-doc directive for including all
>  but DOC:
> 
> There were several rounds of the patches that enabled "functions" directive
> with no parameters in kerneldoc.py to allow including all the kernel-doc
> comments except the DOC: sections.
> 
> Yet, the boot-time-mm.rst sneaked in with the older version of that
> directive and was not updated. Update it now.
> 
> Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>

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

Thanks.

> ---
>  Documentation/core-api/boot-time-mm.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/core-api/boot-time-mm.rst b/Documentation/core-api/boot-time-mm.rst
> index 03cb164..6e12e89 100644
> --- a/Documentation/core-api/boot-time-mm.rst
> +++ b/Documentation/core-api/boot-time-mm.rst
> @@ -76,7 +76,7 @@ These interfaces available only with bootmem, i.e when ``CONFIG_NO_BOOTMEM=n``
>  
>  .. kernel-doc:: include/linux/bootmem.h
>  .. kernel-doc:: mm/bootmem.c
> -   :nodocs:
> +   :functions:
>  
>  Memblock specific API
>  ---------------------
> @@ -89,4 +89,4 @@ really happens under the hood.
>  
>  .. kernel-doc:: include/linux/memblock.h
>  .. kernel-doc:: mm/memblock.c
> -   :nodocs:
> +   :functions:
> 


-- 
~Randy