[PATCH 1/1] container_of: Document container_of_const() is preferred

[Sakari Ailus]

There is a warning in kerneldoc documentation of container_of() that
constness of @ptr is lost. While this is a suggestion container_of_const()
should be used instead, the vast majority of new code still uses
container_of():

$ git diff v6.8 v6.9|grep container_of\(|wc -l
788
$ git diff v6.8 v6.9|grep container_of_const|wc -l
11

Make an explicit recommendation to use container_of_const(), unless @ptr
is const but its container isn't.

Signed-off-by: Sakari Ailus <sakari.ailus@xxxxxxxxxxxxxxx>
---
 include/linux/container_of.h | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/include/linux/container_of.h b/include/linux/container_of.h
index 713890c867be..7563015ff165 100644
--- a/include/linux/container_of.h
+++ b/include/linux/container_of.h
@@ -13,7 +13,9 @@
  * @type:	the type of the container struct this is embedded in.
  * @member:	the name of the member within the struct.
  *
- * WARNING: any const qualifier of @ptr is lost.
+ * WARNING: any const qualifier of @ptr is lost. container_of() should only be
+ * used in cases where @ptr is const and its container is not and you know what
+ * you're doing. Otherwise always use container_of_const().
  */
 #define container_of(ptr, type, member) ({				\
 	void *__mptr = (void *)(ptr);					\
-- 
2.39.2