[PATCH v3] doc/checkpatch: Add description to MACRO_ARG_REUSE

[Martin Fernandez <martin.fernandez@eclypsium.com>]

Add a description, an example and a possible workaround to the
MACRO_ARG_REUSE check.

Signed-off-by: Martin Fernandez <martin.fernandez@eclypsium.com>
Acked-by: Dwaipayan Ray <dwaipayanray1@gmail.com>
---
 Documentation/dev-tools/checkpatch.rst | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index b52452bc2963..86545c65cf7b 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -759,6 +759,26 @@ Indentation and Line Breaks
 Macros, Attributes and Symbols
 ------------------------------
 
+  **ARG_REUSE**
+    Using the same argument multiple times in the macro definition
+    would lead to unwanted side-effects.
+
+    For example, given a `min` macro defined like::
+
+      #define min(x, y)  ((x) < (y) ? (x) : (y))
+
+    If you call it with `min(foo(x), 0)`, it would expand to::
+
+      foo(x) < 0 ? foo(x) : 0
+
+    If `foo` has side-effects or it's an expensive calculation the
+    results might not be what the user intended.
+
+    For a workaround the idea is to define local variables to hold the
+    macro's arguments. Checkout the actual implementation of `min` in
+    include/linux/minmax.h for the full implementation of the
+    workaround.
+
   **ARRAY_SIZE**
     The ARRAY_SIZE(foo) macro should be preferred over
     sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
-- 
2.30.2