[Cocci] [PATCH v2] documentation: coccinelle: Improve command example for make C={1, 2}

From: Sumera Priyadarsini <sylphrenadin@gmail.com>
To: Julia.Lawall@lip6.fr
Cc: michal.lkml@markovi.net, linux-doc@vger.kernel.org,
	corbet@lwn.net, gregkh@linuxfoundation.org,
	Gilles.Muller@lip6.fr, nicolas.palix@imag.fr,
	cocci@systeme.lip6.fr
Subject: [Cocci] [PATCH v2] documentation: coccinelle: Improve command example for make C={1, 2}
Date: Mon, 10 Aug 2020 09:05:54 +0530	[thread overview]
Message-ID: <20200810033554.11212-1-sylphrenadin@gmail.com> (raw)

Modify coccinelle documentation to further clarify
the usage of the makefile C variable flag by coccicheck.

Signed-off-by: Sumera Priyadarsini <sylphrenadin@gmail.com>

---
Changes in v2:
        - Change the message tone to imperative as suggested by Markus
Elfring
	- Add examples for using a specific file and explain in detail
the usage of the C variable, as suggested by Julia Lawall
---
 Documentation/dev-tools/coccinelle.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/dev-tools/coccinelle.rst b/Documentation/dev-tools/coccinelle.rst
index 6c791af1c859..bbcb4f7e8b5c 100644
--- a/Documentation/dev-tools/coccinelle.rst
+++ b/Documentation/dev-tools/coccinelle.rst
@@ -175,13 +175,20 @@ For example, to check drivers/net/wireless/ one may write::
     make coccicheck M=drivers/net/wireless/
 
 To apply Coccinelle on a file basis, instead of a directory basis, the
-following command may be used::
+C flag is used. The C flag is a variable used by the makefile
+to select which files to work with. This flag can be used to
+run scripts for the entire kernel, a specific directory,
+or for a single file. For example, to check drivers/bluetooth/bfusb.c,
 
-    make C=1 CHECK="scripts/coccicheck"
+The value 1 is passed to the C flag to check for files that make considers
+need to be recompiled.::
 
-To check only newly edited code, use the value 2 for the C flag, i.e.::
+    make C=1 CHECK="scripts/coccicheck" "drivers/bluetooth/bfusb.o"
 
-    make C=2 CHECK="scripts/coccicheck"
+The value 2 is passed to the C flag to check for files regardless of
+whether they need to be recompiled or not.::
+
+    make C=2 CHECK="scripts/coccicheck" "drivers/bluetooth/bfusb.o"
 
 In these modes, which work on a file basis, there is no information
 about semantic patches displayed, and no commit message proposed.
-- 
2.17.1

_______________________________________________
Cocci mailing list
Cocci@systeme.lip6.fr
https://systeme.lip6.fr/mailman/listinfo/cocci
