Skip to contentSkip to conversation

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

PATCH In review Fabio M. De Francesco 2 participants 6 messages Apr 18, 2022 – Apr 21, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

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

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 <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ira Weiny <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>

---

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/[email protected]/

 Documentation/vm/highmem.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/vm/highmem.rst +1 -0
index 5dcee6233cd5..1a3e6a8f5d3e 100644
@@ -161,3 +161,4 @@ Functions
 =========
 
 .. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
Signature · 1 line
2.34.1
Reviewed-by on v1 1/1
#1 lore raw
Quoted 6 lines · 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.

Quoted 6 lines
Cc Jonathan Corbet <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ira Weiny <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>

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:

Quoted 21 lines

---

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/[email protected]/

 Documentation/vm/highmem.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/vm/highmem.rst +1 -0
index 5dcee6233cd5..1a3e6a8f5d3e 100644
@@ -161,3 +161,4 @@ Functions
 =========
 
 .. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
Signature · 1 line
2.34.1
#2 lore raw
Quoted 7 lines · On lunedì 18 aprile 2022 23:36:49 CEST Ira Weiny wrote:
Quoted 6 lines · 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.

Quoted 8 lines
Quoted 6 lines
Cc Jonathan Corbet <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ira Weiny <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>

I thought I saw a patch fly by which changed the comment of

kunmap_atomic() in

Quoted 1 line

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.

Quoted 1 line

This is a good inclusion for now. However, I think I would rather see

this as

Quoted 1 line

part of a new series which puts the bulk of the documentation with the

code as

Quoted 1 line

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

Quoted 3 lines

For this particular change:

Thank you so much for your review,

Fabio

Quoted 10 lines

Documentation/vm/

Quoted 10 lines

---

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/[email protected]/

 Documentation/vm/highmem.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/vm/ renamed from Documentation/vm/highmem.rst +0 -0

highmem.rst

Quoted 12 lines
Quoted 11 lines

index 5dcee6233cd5..1a3e6a8f5d3e 100644

Documentation/vm/highmem.rst +1 -0
@@ -161,3 +161,4 @@ Functions
 =========
 
 .. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
Signature · 1 line
2.34.1
#3 lore raw
In reply to Ira Weiny
Quoted 7 lines · On lunedì 18 aprile 2022 23:36:49 CEST Ira Weiny wrote:
Quoted 6 lines · 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.

Quoted 8 lines
Quoted 6 lines
Cc Jonathan Corbet <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ira Weiny <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>

I thought I saw a patch fly by which changed the comment of

kunmap_atomic() in

Quoted 1 line

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/[email protected]/

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

#4 lore raw
Quoted 7 lines · On martedì 19 aprile 2022 14:35:48 CEST Fabio M. De Francesco wrote:
Quoted 1 line · On lunedì 18 aprile 2022 23:36:49 CEST Ira Weiny wrote:

I thought I saw a patch fly by which changed the comment of

kunmap_atomic() in

Quoted 1 line

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.

Quoted 2 lines

It looks that you are talking about the following patch and, if so, you

saw

Quoted 6 lines

it correctly:

"[PATCH v2] mm/highmem: Fix kernel-doc warnings in highmem*.h" at
https://lore.kernel.org/lkml/[email protected]/

I forgot to send it to the Outreachy list.

No, I'm a bit distracted and I remembered it badly :(

This patch is already here at
https://lore.kernel.org/outreachy/[email protected]/

Fabio

Quoted 3 lines

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.

#5 lore raw
In reply to Fabio M. De Francesco
Quoted 33 lines · 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 <[email protected]>
Cc Thomas Gleixner <[email protected]>
Cc Ira Weiny <[email protected]>
Cc Matthew Wilcox <[email protected]>
Cc Peter Zijlstra <[email protected]>

---

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/[email protected]/

 Documentation/vm/highmem.rst | 1 +
 1 file changed, 1 insertion(+)
Documentation/vm/highmem.rst +1 -0
index 5dcee6233cd5..1a3e6a8f5d3e 100644
@@ -161,3 +161,4 @@ Functions
 =========
 
 .. kernel-doc:: include/linux/highmem.h
+.. kernel-doc:: include/linux/highmem-internal.h
Signature · 1 line
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