[PATCH] userns: eliminate many kernel-doc warnings

[PATCH] userns: eliminate many kernel-doc warnings

[Randy Dunlap]

Drop the kernel-doc "/**" notation from 8 structs or functions to
prevent 22 kernel-doc warnings  (samples below).

user_namespace.c:239: warning: Function parameter or member 'map_up' not described in 'idmap_key'
user_namespace.c:246: warning: Function parameter or member 'k' not described in 'cmp_map_id'
user_namespace.c:277: warning: Function parameter or member 'extents' not described in 'map_id_range_down_max'
user_namespace.c:295: warning: Function parameter or member 'extents' not described in 'map_id_range_down_base'
user_namespace.c:344: warning: Function parameter or member 'extents' not described in 'map_id_up_base'
user_namespace.c:364: warning: Function parameter or member 'extents' not described in 'map_id_up_max'
user_namespace.c:776: warning: Function parameter or member 'map' not described in 'insert_extent'
user_namespace.c:844: warning: Function parameter or member 'map' not described in 'sort_idmaps'

Fixes: 6397fac4915a ("userns: bump idmap limits to 340")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Eric Biederman <ebiederm@xmission.com>
Cc: Christian Brauner <brauner@kernel.org>
---
 kernel/user_namespace.c |   16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff -- a/kernel/user_namespace.c b/kernel/user_namespace.c
--- a/kernel/user_namespace.c
+++ b/kernel/user_namespace.c
@@ -228,7 +228,7 @@ void __put_user_ns(struct user_namespace
 }
 EXPORT_SYMBOL(__put_user_ns);
 
-/**
+/*
  * struct idmap_key - holds the information necessary to find an idmapping in a
  * sorted idmap array. It is passed to cmp_map_id() as first argument.
  */
@@ -238,7 +238,7 @@ struct idmap_key {
 	u32 count; /* == 0 unless used with map_id_range_down() */
 };
 
-/**
+/*
  * cmp_map_id - Function to be passed to bsearch() to find the requested
  * idmapping. Expects struct idmap_key to be passed via @k.
  */
@@ -268,7 +268,7 @@ static int cmp_map_id(const void *k, con
 	return 1;
 }
 
-/**
+/*
  * map_id_range_down_max - Find idmap via binary search in ordered idmap array.
  * Can only be called if number of mappings exceeds UID_GID_MAP_MAX_BASE_EXTENTS.
  */
@@ -285,7 +285,7 @@ map_id_range_down_max(unsigned extents,
 		       sizeof(struct uid_gid_extent), cmp_map_id);
 }
 
-/**
+/*
  * map_id_range_down_base - Find idmap via binary search in static extent array.
  * Can only be called if number of mappings is equal or less than
  * UID_GID_MAP_MAX_BASE_EXTENTS.
@@ -334,7 +334,7 @@ static u32 map_id_down(struct uid_gid_ma
 	return map_id_range_down(map, id, 1);
 }
 
-/**
+/*
  * map_id_up_base - Find idmap via binary search in static extent array.
  * Can only be called if number of mappings is equal or less than
  * UID_GID_MAP_MAX_BASE_EXTENTS.
@@ -355,7 +355,7 @@ map_id_up_base(unsigned extents, struct
 	return NULL;
 }
 
-/**
+/*
  * map_id_up_max - Find idmap via binary search in ordered idmap array.
  * Can only be called if number of mappings exceeds UID_GID_MAP_MAX_BASE_EXTENTS.
  */
@@ -767,7 +767,7 @@ static bool mappings_overlap(struct uid_
 	return false;
 }
 
-/**
+/*
  * insert_extent - Safely insert a new idmap extent into struct uid_gid_map.
  * Takes care to allocate a 4K block of memory if the number of mappings exceeds
  * UID_GID_MAP_MAX_BASE_EXTENTS.
@@ -836,7 +836,7 @@ static int cmp_extents_reverse(const voi
 	return 0;
 }
 
-/**
+/*
  * sort_idmaps - Sorts an array of idmap entries.
  * Can only be called if number of mappings exceeds UID_GID_MAP_MAX_BASE_EXTENTS.
  */

Re: [PATCH] userns: eliminate many kernel-doc warnings

[Christian Brauner]

On Wed, 30 Aug 2023 09:32:15 -0700, Randy Dunlap wrote:
> Drop the kernel-doc "/**" notation from 8 structs or functions to
> prevent 22 kernel-doc warnings  (samples below).
> 
> user_namespace.c:239: warning: Function parameter or member 'map_up' not described in 'idmap_key'
> user_namespace.c:246: warning: Function parameter or member 'k' not described in 'cmp_map_id'
> user_namespace.c:277: warning: Function parameter or member 'extents' not described in 'map_id_range_down_max'
> user_namespace.c:295: warning: Function parameter or member 'extents' not described in 'map_id_range_down_base'
> user_namespace.c:344: warning: Function parameter or member 'extents' not described in 'map_id_up_base'
> user_namespace.c:364: warning: Function parameter or member 'extents' not described in 'map_id_up_max'
> user_namespace.c:776: warning: Function parameter or member 'map' not described in 'insert_extent'
> user_namespace.c:844: warning: Function parameter or member 'map' not described in 'sort_idmaps'
> 
> [...]

Applied to the vfs.misc branch of the vfs/vfs.git tree.
Patches in the vfs.misc branch should appear in linux-next soon.

Please report any outstanding bugs that were missed during review in a
new review to the original patch series allowing us to drop it.

It's encouraged to provide Acked-bys and Reviewed-bys even though the
patch has now been applied. If possible patch trailers will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. If in doubt, please check the listed branch.

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git
branch: vfs.misc

[1/1] userns: eliminate many kernel-doc warnings
      https://git.kernel.org/vfs/vfs/c/97966f21d3d4