[PATCH] mm: add comments on pglist_data zones

[PATCH] mm: add comments on pglist_data zones

[Ben Widawsky]

While making other modifications it was easy to confuse the two struct
members node_zones and node_zonelists. For those already familiar with
the code, this might seem to be a silly patch, but it's quite helpful to
disambiguate the similar-sounding fields

While here, add a small comment on why nr_zones isn't simply MAX_NR_ZONES

Signed-off-by: Ben Widawsky <ben.widawsky@intel.com>
---
 include/linux/mmzone.h | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git include/linux/mmzone.h include/linux/mmzone.h
index 1b9de7d220fb..4f7c95e9bad8 100644
--- include/linux/mmzone.h
+++ include/linux/mmzone.h
@@ -665,9 +665,21 @@ struct deferred_split {
  * per-zone basis.
  */
 typedef struct pglist_data {
+	/*
+	 * node_zones contains just the zones for THIS node. Not all of the
+	 * zones may be populated, but it is the full list. It is referenced by
+	 * this node's node_zonelists as well as other node's node_zonelists.
+	 */
 	struct zone node_zones[MAX_NR_ZONES];
+
+	/*
+	 * node_zonelists contains references to all zones in all nodes.
+	 * Generally the first zones will be references to this node's
+	 * node_zones.
+	 */
 	struct zonelist node_zonelists[MAX_ZONELISTS];
-	int nr_zones;
+
+	int nr_zones; /* number of populated zones in this node */
 #ifdef CONFIG_FLAT_NODE_MEM_MAP	/* means !SPARSEMEM */
 	struct page *node_mem_map;
 #ifdef CONFIG_PAGE_EXTENSION
-- 
2.26.2

Re: [PATCH] mm: add comments on pglist_data zones

[Matthew Wilcox]

On Wed, May 20, 2020 at 01:54:43PM -0700, Ben Widawsky wrote:
> While making other modifications it was easy to confuse the two struct
> members node_zones and node_zonelists. For those already familiar with
> the code, this might seem to be a silly patch, but it's quite helpful to
> disambiguate the similar-sounding fields
> 
> While here, add a small comment on why nr_zones isn't simply MAX_NR_ZONES

It seems like a real shame to write all this excellent documentation
and not format it as kernel-doc.

> Signed-off-by: Ben Widawsky <ben.widawsky@intel.com>
> ---
>  include/linux/mmzone.h | 14 +++++++++++++-
>  1 file changed, 13 insertions(+), 1 deletion(-)
> 
> diff --git include/linux/mmzone.h include/linux/mmzone.h
> index 1b9de7d220fb..4f7c95e9bad8 100644
> --- include/linux/mmzone.h
> +++ include/linux/mmzone.h
> @@ -665,9 +665,21 @@ struct deferred_split {
>   * per-zone basis.
>   */
>  typedef struct pglist_data {
> +	/*
> +	 * node_zones contains just the zones for THIS node. Not all of the
> +	 * zones may be populated, but it is the full list. It is referenced by
> +	 * this node's node_zonelists as well as other node's node_zonelists.
> +	 */
>  	struct zone node_zones[MAX_NR_ZONES];
> +
> +	/*
> +	 * node_zonelists contains references to all zones in all nodes.
> +	 * Generally the first zones will be references to this node's
> +	 * node_zones.
> +	 */
>  	struct zonelist node_zonelists[MAX_ZONELISTS];
> -	int nr_zones;
> +
> +	int nr_zones; /* number of populated zones in this node */
>  #ifdef CONFIG_FLAT_NODE_MEM_MAP	/* means !SPARSEMEM */
>  	struct page *node_mem_map;
>  #ifdef CONFIG_PAGE_EXTENSION
> -- 
> 2.26.2
> 
> 

Re: [PATCH] mm: add comments on pglist_data zones

[Ben Widawsky]

On 20-05-20 16:22:35, Matthew Wilcox wrote:
> On Wed, May 20, 2020 at 01:54:43PM -0700, Ben Widawsky wrote:
> > While making other modifications it was easy to confuse the two struct
> > members node_zones and node_zonelists. For those already familiar with
> > the code, this might seem to be a silly patch, but it's quite helpful to
> > disambiguate the similar-sounding fields
> > 
> > While here, add a small comment on why nr_zones isn't simply MAX_NR_ZONES
> 
> It seems like a real shame to write all this excellent documentation
> and not format it as kernel-doc.

I admit, I didn't look at all the kernel-doc files. Is there precedent there for
documenting struct members like this? I'd be more than happy to try to document
everything I've dug up in coming up to speed here. 

I've used the docs from Mel quite a bit and would very much like to pay it
forward, as it were.

Re: [PATCH] mm: add comments on pglist_data zones

[Matthew Wilcox]

On Wed, May 20, 2020 at 09:53:00PM -0700, Ben Widawsky wrote:
> On 20-05-20 16:22:35, Matthew Wilcox wrote:
> > On Wed, May 20, 2020 at 01:54:43PM -0700, Ben Widawsky wrote:
> > > While making other modifications it was easy to confuse the two struct
> > > members node_zones and node_zonelists. For those already familiar with
> > > the code, this might seem to be a silly patch, but it's quite helpful to
> > > disambiguate the similar-sounding fields
> > > 
> > > While here, add a small comment on why nr_zones isn't simply MAX_NR_ZONES
> > 
> > It seems like a real shame to write all this excellent documentation
> > and not format it as kernel-doc.
> 
> I admit, I didn't look at all the kernel-doc files. Is there precedent there for
> documenting struct members like this? I'd be more than happy to try to document
> everything I've dug up in coming up to speed here. 
> 
> I've used the docs from Mel quite a bit and would very much like to pay it
> forward, as it were.

I appreciate your willingness!  Fortunately, we have excellent
documentation on adding more documentation ;-)

Documentation/doc-guide/kernel-doc.rst is where you'll want to start.
'Structure, union, and enumeration documentation' is the section.
Do read through the whole section before jumping in because you might
find it more clear to use the style in 'In-line member documentation
comments' rather than the style documented first.