[PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[Fabio M. De Francesco]

In Documentation/vm/highmem.rst the kernel-doc comments are missing,
therefore kunmap_local() and kunmap_atomic() are yet undocumented.

Add a kernel-doc directive to include the above-mentioned kernel-doc
comments in highmem.rst.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Ira Weiny <ira.weiny@intel.com>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
---

This patch must be applied and built on top of 
"[PATCH v3 2/2] Documentation/vm: Include kernel-doc to highmem.rst"
https://lore.kernel.org/lkml/20220415231917.25962-3-fmdefrancesco@gmail.com/

 Documentation/vm/highmem.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/highmem.rst
index 5dcee6233cd5..1a3e6a8f5d3e 100644
--- a/Documentation/vm/highmem.rst
+++ b/Documentation/vm/highmem.rst
@@ -161,3 +161,4 @@ Functions
 =========
 
 .. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
-- 
2.34.1

Re: [PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[Ira Weiny]

On Mon, Apr 18, 2022 at 10:17:40AM +0200, Fabio M. De Francesco wrote:
> In Documentation/vm/highmem.rst the kernel-doc comments are missing,
> therefore kunmap_local() and kunmap_atomic() are yet undocumented.
> 
> Add a kernel-doc directive to include the above-mentioned kernel-doc
> comments in highmem.rst.
> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Ira Weiny <ira.weiny@intel.com>
> Cc: Matthew Wilcox <willy@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>

I thought I saw a patch fly by which changed the comment of kunmap_atomic() in
include/linux/highmem-internal.h?  Did I miss that somewhere?

This is a good inclusion for now.  However, I think I would rather see this as
part of a new series which puts the bulk of the documentation with the code as
I proposed in patch 1/2 in your other series.

For this particular change:

Reviewed-by: Ira Weiny <ira.weiny@intel.com>

> ---
> 
> This patch must be applied and built on top of 
> "[PATCH v3 2/2] Documentation/vm: Include kernel-doc to highmem.rst"
> https://lore.kernel.org/lkml/20220415231917.25962-3-fmdefrancesco@gmail.com/
> 
>  Documentation/vm/highmem.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/highmem.rst
> index 5dcee6233cd5..1a3e6a8f5d3e 100644
> --- a/Documentation/vm/highmem.rst
> +++ b/Documentation/vm/highmem.rst
> @@ -161,3 +161,4 @@ Functions
>  =========
>  
>  .. kernel-doc:: include/linux/highmem.h
> +.. kernel-doc:: include/linux/highmem-internal.h
> -- 
> 2.34.1
> 

Re: [PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[Fabio M. De Francesco]

On lunedì 18 aprile 2022 23:36:49 CEST Ira Weiny wrote:
> On Mon, Apr 18, 2022 at 10:17:40AM +0200, Fabio M. De Francesco wrote:
> > In Documentation/vm/highmem.rst the kernel-doc comments are missing,
> > therefore kunmap_local() and kunmap_atomic() are yet undocumented.
> > 
> > Add a kernel-doc directive to include the above-mentioned kernel-doc
> > comments in highmem.rst.
> > 
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: Thomas Gleixner <tglx@linutronix.de>
> > Cc: Ira Weiny <ira.weiny@intel.com>
> > Cc: Matthew Wilcox <willy@infradead.org>
> > Cc: Peter Zijlstra <peterz@infradead.org>
> > Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> 
> I thought I saw a patch fly by which changed the comment of 
kunmap_atomic() in
> include/linux/highmem-internal.h?  Did I miss that somewhere?

No, you're right. I had noticed just some minutes before reading your 
review that a made a typo.

I wanted to write: "In Documentation/vm/highmem.rst some kernel-doc 
comments are missing" instead for some unknown reason I wrote "the" in 
place of "some" :(

I'll fix it ASAP.

> This is a good inclusion for now.  However, I think I would rather see 
this as
> part of a new series which puts the bulk of the documentation with the 
code as
> I proposed in patch 1/2 in your other series.

I have also read your review of the patch above. I agree with you that the 
"how" should be placed in the kernel-doc comments in the code. And I also 
agree that this patch should be part of a new version of a reorganized 
series.

I'll start working on your suggestions by tomorrow morning (it's midnight 
here in Italy).

> For this particular change:
> 
> Reviewed-by: Ira Weiny <ira.weiny@intel.com>

Thank you so much for your review,

Fabio

> > ---
> > 
> > This patch must be applied and built on top of 
> > "[PATCH v3 2/2] Documentation/vm: Include kernel-doc to highmem.rst"
> > https://lore.kernel.org/lkml/20220415231917.25962-3-fmdefrancesco@gmail.com/
> > 
> >  Documentation/vm/highmem.rst | 1 +
> >  1 file changed, 1 insertion(+)
> > 
> > diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/
highmem.rst
> > index 5dcee6233cd5..1a3e6a8f5d3e 100644
> > --- a/Documentation/vm/highmem.rst
> > +++ b/Documentation/vm/highmem.rst
> > @@ -161,3 +161,4 @@ Functions
> >  =========
> >  
> >  .. kernel-doc:: include/linux/highmem.h
> > +.. kernel-doc:: include/linux/highmem-internal.h
> > -- 
> > 2.34.1
> > 
> 

Re: [PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[Fabio M. De Francesco]

On lunedì 18 aprile 2022 23:36:49 CEST Ira Weiny wrote:
> On Mon, Apr 18, 2022 at 10:17:40AM +0200, Fabio M. De Francesco wrote:
> > In Documentation/vm/highmem.rst the kernel-doc comments are missing,
> > therefore kunmap_local() and kunmap_atomic() are yet undocumented.
> > 
> > Add a kernel-doc directive to include the above-mentioned kernel-doc
> > comments in highmem.rst.
> > 
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: Thomas Gleixner <tglx@linutronix.de>
> > Cc: Ira Weiny <ira.weiny@intel.com>
> > Cc: Matthew Wilcox <willy@infradead.org>
> > Cc: Peter Zijlstra <peterz@infradead.org>
> > Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> 
> I thought I saw a patch fly by which changed the comment of 
kunmap_atomic() in
> include/linux/highmem-internal.h?  Did I miss that somewhere?

Sorry, in my other email I responded after misunderstanding your question 
because I had just noticed a typo so that I had something else in my mind.

It looks that you are talking about the following patch and, if so, you saw 
it correctly:

"[PATCH v2] mm/highmem: Fix kernel-doc warnings in highmem*.h" at 
https://lore.kernel.org/lkml/20220418175638.30018-1-fmdefrancesco@gmail.com/

I forgot to send it to the Outreachy list. I'm about to resend it only to 
this list in order to make Outreachy's organizers to know about it. For v1 
already had an "Acked-by:" tag from Mike Rapoport.

Thanks,

Fabio M. De Francesco

Re: [PATCH] Documentation/vm: Include kernel-doc from highmem-internal.h

[Fabio M. De Francesco]

On lunedì 18 aprile 2022 10:17:40 CEST Fabio M. De Francesco wrote:
> In Documentation/vm/highmem.rst the kernel-doc comments are missing,
> therefore kunmap_local() and kunmap_atomic() are yet undocumented.
> 
> Add a kernel-doc directive to include the above-mentioned kernel-doc
> comments in highmem.rst.
> 
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: Thomas Gleixner <tglx@linutronix.de>
> Cc: Ira Weiny <ira.weiny@intel.com>
> Cc: Matthew Wilcox <willy@infradead.org>
> Cc: Peter Zijlstra <peterz@infradead.org>
> Signed-off-by: Fabio M. De Francesco <fmdefrancesco@gmail.com>
> ---
> 
> This patch must be applied and built on top of 
> "[PATCH v3 2/2] Documentation/vm: Include kernel-doc to highmem.rst"
> https://lore.kernel.org/lkml/20220415231917.25962-3-fmdefrancesco@gmail.com/
> 
>  Documentation/vm/highmem.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/Documentation/vm/highmem.rst b/Documentation/vm/highmem.rst
> index 5dcee6233cd5..1a3e6a8f5d3e 100644
> --- a/Documentation/vm/highmem.rst
> +++ b/Documentation/vm/highmem.rst
> @@ -161,3 +161,4 @@ Functions
>  =========
>  
>  .. kernel-doc:: include/linux/highmem.h
> +.. kernel-doc:: include/linux/highmem-internal.h
> -- 
> 2.34.1
> 
Dear Maintainers,

Please drop this patch because it has been reworked and inserted as part of 
a new series whose subject is "Extend and reorganize Highmem's 
documentation" and which is about to be submitted.

Thanks,

Fabio M. De Francesco