All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] mm: Add pagemap.h to the fine documentation
@ 2020-02-21 22:00 Matthew Wilcox
  2020-02-21 22:33 ` Zi Yan
  2020-02-21 22:35 ` John Hubbard
  0 siblings, 2 replies; 4+ messages in thread
From: Matthew Wilcox @ 2020-02-21 22:00 UTC (permalink / raw)
  To: linux-doc, linux-mm; +Cc: Matthew Wilcox (Oracle)

From: "Matthew Wilcox (Oracle)" <willy@infradead.org>

The documentation currently does not include the deathless prose
written to describe functions in pagemap.h because it's not included
in any rst file.  Fix up the mismatches between parameter names and the
documentation and add the file to mm-api.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 Documentation/core-api/mm-api.rst | 3 +++
 include/linux/pagemap.h           | 8 ++++----
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index be726986ff75..2adffb3f7914 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -73,6 +73,9 @@ File Mapping and Page Cache
 .. kernel-doc:: mm/truncate.c
    :export:
 
+.. kernel-doc:: include/linux/pagemap.h
+   :internal:
+
 Memory pools
 ============
 
diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
index ccb14b6a16b5..6462df717cff 100644
--- a/include/linux/pagemap.h
+++ b/include/linux/pagemap.h
@@ -33,8 +33,8 @@ enum mapping_flags {
 
 /**
  * mapping_set_error - record a writeback error in the address_space
- * @mapping - the mapping in which an error should be set
- * @error - the error to set in the mapping
+ * @mapping: the mapping in which an error should be set
+ * @error: the error to set in the mapping
  *
  * When writeback fails in some way, we must record that error so that
  * userspace can be informed when fsync and the like are called.  We endeavor
@@ -305,9 +305,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
  * atomic allocation!
  */
 static inline struct page *find_or_create_page(struct address_space *mapping,
-					pgoff_t offset, gfp_t gfp_mask)
+					pgoff_t index, gfp_t gfp_mask)
 {
-	return pagecache_get_page(mapping, offset,
+	return pagecache_get_page(mapping, index,
 					FGP_LOCK|FGP_ACCESSED|FGP_CREAT,
 					gfp_mask);
 }
-- 
2.25.0


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] mm: Add pagemap.h to the fine documentation
  2020-02-21 22:00 [PATCH] mm: Add pagemap.h to the fine documentation Matthew Wilcox
@ 2020-02-21 22:33 ` Zi Yan
  2020-02-21 22:35 ` John Hubbard
  1 sibling, 0 replies; 4+ messages in thread
From: Zi Yan @ 2020-02-21 22:33 UTC (permalink / raw)
  To: Matthew Wilcox; +Cc: linux-doc, linux-mm

[-- Attachment #1: Type: text/plain, Size: 2281 bytes --]

On 21 Feb 2020, at 17:00, Matthew Wilcox wrote:

> From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
>
> The documentation currently does not include the deathless prose
> written to describe functions in pagemap.h because it's not included
> in any rst file.  Fix up the mismatches between parameter names and the
> documentation and add the file to mm-api.
>
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  Documentation/core-api/mm-api.rst | 3 +++
>  include/linux/pagemap.h           | 8 ++++----
>  2 files changed, 7 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index be726986ff75..2adffb3f7914 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -73,6 +73,9 @@ File Mapping and Page Cache
>  .. kernel-doc:: mm/truncate.c
>     :export:
>
> +.. kernel-doc:: include/linux/pagemap.h
> +   :internal:
> +
>  Memory pools
>  ============
>
> diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> index ccb14b6a16b5..6462df717cff 100644
> --- a/include/linux/pagemap.h
> +++ b/include/linux/pagemap.h
> @@ -33,8 +33,8 @@ enum mapping_flags {
>
>  /**
>   * mapping_set_error - record a writeback error in the address_space
> - * @mapping - the mapping in which an error should be set
> - * @error - the error to set in the mapping
> + * @mapping: the mapping in which an error should be set
> + * @error: the error to set in the mapping
>   *
>   * When writeback fails in some way, we must record that error so that
>   * userspace can be informed when fsync and the like are called.  We endeavor
> @@ -305,9 +305,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
>   * atomic allocation!
>   */
>  static inline struct page *find_or_create_page(struct address_space *mapping,
> -					pgoff_t offset, gfp_t gfp_mask)
> +					pgoff_t index, gfp_t gfp_mask)
>  {
> -	return pagecache_get_page(mapping, offset,
> +	return pagecache_get_page(mapping, index,
>  					FGP_LOCK|FGP_ACCESSED|FGP_CREAT,
>  					gfp_mask);
>  }
> -- 
> 2.25.0

Looks good to me. Thanks.

Reviewed-by: Zi Yan <ziy@nvidia.com>


--
Best Regards,
Yan Zi

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 854 bytes --]

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] mm: Add pagemap.h to the fine documentation
  2020-02-21 22:00 [PATCH] mm: Add pagemap.h to the fine documentation Matthew Wilcox
  2020-02-21 22:33 ` Zi Yan
@ 2020-02-21 22:35 ` John Hubbard
  2020-02-22  1:58   ` Matthew Wilcox
  1 sibling, 1 reply; 4+ messages in thread
From: John Hubbard @ 2020-02-21 22:35 UTC (permalink / raw)
  To: Matthew Wilcox, linux-doc, linux-mm

On 2/21/20 2:00 PM, Matthew Wilcox wrote:
> From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> 
> The documentation currently does not include the deathless prose

Yea, documentation!

> written to describe functions in pagemap.h because it's not included
> in any rst file.  Fix up the mismatches between parameter names and the


Maybe "Fix up some of the mismatches"? ...below:


> documentation and add the file to mm-api.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>  Documentation/core-api/mm-api.rst | 3 +++
>  include/linux/pagemap.h           | 8 ++++----
>  2 files changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index be726986ff75..2adffb3f7914 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -73,6 +73,9 @@ File Mapping and Page Cache
>  .. kernel-doc:: mm/truncate.c
>     :export:
>  
> +.. kernel-doc:: include/linux/pagemap.h
> +   :internal:
> +
>  Memory pools
>  ============
>  
> diff --git a/include/linux/pagemap.h b/include/linux/pagemap.h
> index ccb14b6a16b5..6462df717cff 100644
> --- a/include/linux/pagemap.h
> +++ b/include/linux/pagemap.h
> @@ -33,8 +33,8 @@ enum mapping_flags {
>  
>  /**
>   * mapping_set_error - record a writeback error in the address_space
> - * @mapping - the mapping in which an error should be set
> - * @error - the error to set in the mapping
> + * @mapping: the mapping in which an error should be set
> + * @error: the error to set in the mapping
>   *
>   * When writeback fails in some way, we must record that error so that
>   * userspace can be informed when fsync and the like are called.  We endeavor
> @@ -305,9 +305,9 @@ static inline struct page *find_lock_page(struct address_space *mapping,
>   * atomic allocation!
>   */
>  static inline struct page *find_or_create_page(struct address_space *mapping,
> -					pgoff_t offset, gfp_t gfp_mask)
> +					pgoff_t index, gfp_t gfp_mask)
>  {
> -	return pagecache_get_page(mapping, offset,
> +	return pagecache_get_page(mapping, index,
>  					FGP_LOCK|FGP_ACCESSED|FGP_CREAT,
>  					gfp_mask);


...for example, the called function itself, pagecache_get_page(), declares
its second arg with a name of "offset". 

Not that it needs to affect this patch, but just to note that I think we might
be at this for a while. :)

Anyway, I also ran 'make htmldocs' on this and poked around, and everything looks
like it should, so:

    Reviewed-by: John Hubbard <jhubbard@nvidia.com>


thanks,
-- 
John Hubbard
NVIDIA

>  }
> 




^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH] mm: Add pagemap.h to the fine documentation
  2020-02-21 22:35 ` John Hubbard
@ 2020-02-22  1:58   ` Matthew Wilcox
  0 siblings, 0 replies; 4+ messages in thread
From: Matthew Wilcox @ 2020-02-22  1:58 UTC (permalink / raw)
  To: John Hubbard; +Cc: linux-doc, linux-mm

On Fri, Feb 21, 2020 at 02:35:52PM -0800, John Hubbard wrote:
> On 2/21/20 2:00 PM, Matthew Wilcox wrote:
> > From: "Matthew Wilcox (Oracle)" <willy@infradead.org>
> > 
> > The documentation currently does not include the deathless prose
> 
> Yea, documentation!
> 
> > written to describe functions in pagemap.h because it's not included
> > in any rst file.  Fix up the mismatches between parameter names and the
> 
> Maybe "Fix up some of the mismatches"? ...below:

Nono, it fixes up all the _sphinx warnings_.  Not our grand plan to rename
the world ;-)

> Anyway, I also ran 'make htmldocs' on this and poked around, and everything looks
> like it should, so:
> 
>     Reviewed-by: John Hubbard <jhubbard@nvidia.com>

Thanks!  Jon, do you want to take this through your tree?  I know I
tagged it as mm, but this seems more like a doc patch than an mm patch.

^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2020-02-22  1:58 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-21 22:00 [PATCH] mm: Add pagemap.h to the fine documentation Matthew Wilcox
2020-02-21 22:33 ` Zi Yan
2020-02-21 22:35 ` John Hubbard
2020-02-22  1:58   ` Matthew Wilcox

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.