Commit 198fba41 authored by Mike Rapoport's avatar Mike Rapoport Committed by Linus Torvalds
Browse files

mm/mmzone.h: fix existing kernel-doc comments and link them to core-api 

There are a couple of kernel-doc comments in include/linux/mmzone.h but
they have minor formatting issues that would cause kernel-doc warnings.

Fix the formatting of those comments, add missing Return: descriptions and
link include/linux/mmzone.h to Documentation/core-api/mm-api.rst

Link: https://lkml.kernel.org/r/20210426141927.1314326-2-rppt@kernel.org


Signed-off-by: default avatarMike Rapoport <rppt@linux.ibm.com>
Reviewed-by: default avatarMatthew Wilcox (Oracle) <willy@infradead.org>
Reviewed-by: default avatarAnshuman Khandual <anshuman.khandual@arm.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 9df65f52

Documentation/core-api/mm-api.rst

+1 −0
Original line number Diff line number Diff line
@@ -97,3 +97,4 @@ More Memory Management Functions 
   :internal:

.. kernel-doc:: include/linux/mm.h

   :internal:

.. kernel-doc:: include/linux/mmzone.h

include/linux/mmzone.h

+24 −19
Original line number Diff line number Diff line
@@ -993,7 +993,8 @@ static inline int is_highmem_idx(enum zone_type idx) 
 * is_highmem - helper function to quickly check if a struct zone is a

 *              highmem zone or not.  This is an attempt to keep references

 *              to ZONE_{DMA/NORMAL/HIGHMEM/etc} in general code to a minimum.

 * @zone - pointer to struct zone variable

 * @zone: pointer to struct zone variable

 * Return: 1 for a highmem zone, 0 otherwise

 */

static inline int is_highmem(struct zone *zone)

{
@@ -1044,7 +1045,7 @@ extern struct zone *next_zone(struct zone *zone); 


/**

 * for_each_online_pgdat - helper macro to iterate over all online nodes

 * @pgdat - pointer to a pg_data_t variable

 * @pgdat: pointer to a pg_data_t variable

 */

#define for_each_online_pgdat(pgdat)			\

	for (pgdat = first_online_pgdat();		\
@@ -1052,7 +1053,7 @@ extern struct zone *next_zone(struct zone *zone); 
	     pgdat = next_online_pgdat(pgdat))

/**

 * for_each_zone - helper macro to iterate over all memory zones

 * @zone - pointer to struct zone variable

 * @zone: pointer to struct zone variable

 *

 * The user only needs to declare the zone variable, for_each_zone

 * fills it in.
@@ -1091,15 +1092,18 @@ struct zoneref *__next_zones_zonelist(struct zoneref *z, 


/**

 * next_zones_zonelist - Returns the next zone at or below highest_zoneidx within the allowed nodemask using a cursor within a zonelist as a starting point

 * @z - The cursor used as a starting point for the search

 * @highest_zoneidx - The zone index of the highest zone to return

 * @nodes - An optional nodemask to filter the zonelist with

 * @z: The cursor used as a starting point for the search

 * @highest_zoneidx: The zone index of the highest zone to return

 * @nodes: An optional nodemask to filter the zonelist with

 *

 * This function returns the next zone at or below a given zone index that is

 * within the allowed nodemask using a cursor as the starting point for the

 * search. The zoneref returned is a cursor that represents the current zone

 * being examined. It should be advanced by one before calling

 * next_zones_zonelist again.

 *

 * Return: the next zone at or below highest_zoneidx within the allowed

 * nodemask using a cursor within a zonelist as a starting point

 */

static __always_inline struct zoneref *next_zones_zonelist(struct zoneref *z,

					enum zone_type highest_zoneidx,
@@ -1112,10 +1116,9 @@ static __always_inline struct zoneref *next_zones_zonelist(struct zoneref *z, 


/**

 * first_zones_zonelist - Returns the first zone at or below highest_zoneidx within the allowed nodemask in a zonelist

 * @zonelist - The zonelist to search for a suitable zone

 * @highest_zoneidx - The zone index of the highest zone to return

 * @nodes - An optional nodemask to filter the zonelist with

 * @return - Zoneref pointer for the first suitable zone found (see below)

 * @zonelist: The zonelist to search for a suitable zone

 * @highest_zoneidx: The zone index of the highest zone to return

 * @nodes: An optional nodemask to filter the zonelist with

 *

 * This function returns the first zone at or below a given zone index that is

 * within the allowed nodemask. The zoneref returned is a cursor that can be
@@ -1125,6 +1128,8 @@ static __always_inline struct zoneref *next_zones_zonelist(struct zoneref *z, 
 * When no eligible zone is found, zoneref->zone is NULL (zoneref itself is

 * never NULL). This may happen either genuinely, or due to concurrent nodemask

 * update due to cpuset modification.

 *

 * Return: Zoneref pointer for the first suitable zone found

 */

static inline struct zoneref *first_zones_zonelist(struct zonelist *zonelist,

					enum zone_type highest_zoneidx,
@@ -1136,11 +1141,11 @@ static inline struct zoneref *first_zones_zonelist(struct zonelist *zonelist, 


/**

 * for_each_zone_zonelist_nodemask - helper macro to iterate over valid zones in a zonelist at or below a given zone index and within a nodemask

 * @zone - The current zone in the iterator

 * @z - The current pointer within zonelist->_zonerefs being iterated

 * @zlist - The zonelist being iterated

 * @highidx - The zone index of the highest zone to return

 * @nodemask - Nodemask allowed by the allocator

 * @zone: The current zone in the iterator

 * @z: The current pointer within zonelist->_zonerefs being iterated

 * @zlist: The zonelist being iterated

 * @highidx: The zone index of the highest zone to return

 * @nodemask: Nodemask allowed by the allocator

 *

 * This iterator iterates though all zones at or below a given zone index and

 * within a given nodemask
@@ -1160,10 +1165,10 @@ static inline struct zoneref *first_zones_zonelist(struct zonelist *zonelist, 


/**

 * for_each_zone_zonelist - helper macro to iterate over valid zones in a zonelist at or below a given zone index

 * @zone - The current zone in the iterator

 * @z - The current pointer within zonelist->zones being iterated

 * @zlist - The zonelist being iterated

 * @highidx - The zone index of the highest zone to return

 * @zone: The current zone in the iterator

 * @z: The current pointer within zonelist->zones being iterated

 * @zlist: The zonelist being iterated

 * @highidx: The zone index of the highest zone to return

 *

 * This iterator iterates though all zones at or below a given zone index.

 */