* [PATCH] checkpatch: Check networking specific block comment style
@ 2012-09-12 0:47 Joe Perches
2012-09-12 1:19 ` Allan, Bruce W
0 siblings, 1 reply; 3+ messages in thread
From: Joe Perches @ 2012-09-12 0:47 UTC (permalink / raw)
To: Andrew Morton; +Cc: Andy Whitcroft, David Miller, LKML, netdev
In an effort to get fewer checkpatch reviewer corrections,
add a networking specific style test for the preferred
networking comment style.
/* The preferred style for block comments in
* drivers/net/... and net/... is like this
*/
These tests are only used in net/ and drivers/net/
Tested with:
$ cat drivers/net/t.c
/* foo */
/*
* foo
*/
/* foo
*/
/* foo
* bar */
$ ./scripts/checkpatch.pl -f drivers/net/t.c
WARNING: networking block comments don't use an empty /* line, use /* Comment...
#4: FILE: net/t.c:4:
+
+/*
WARNING: networking block comments put the trailing */ on a separate line
#12: FILE: net/t.c:12:
+ * bar */
total: 0 errors, 2 warnings, 12 lines checked
Signed-off-by: Joe Perches <joe@perches.com>
---
scripts/checkpatch.pl | 14 ++++++++++++++
1 files changed, 14 insertions(+), 0 deletions(-)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index ca05ba2..7165516 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -1873,6 +1873,20 @@ sub process {
"No space is necessary after a cast\n" . $hereprev);
}
+ if ($realfile =~ m@^(drivers/net/|net/)@ &&
+ $rawline =~ /^\+[ \t]*\/\*[ \t]*$/ &&
+ $prevrawline =~ /^\+[ \t]*$/) {
+ WARN("NETWORKING_BLOCK_COMMENT_STYLE",
+ "networking block comments don't use an empty /* line, use /* Comment...\n" . $hereprev);
+ }
+
+ if ($realfile =~ m@^(drivers/net/|net/)@ &&
+ $rawline !~ m@^\+[ \t]*(\/\*|\*\/)@ &&
+ $rawline =~ m@^\+[ \t]*.+\*\/[ \t]*$@) {
+ WARN("NETWORKING_BLOCK_COMMENT_STYLE",
+ "networking block comments put the trailing */ on a separate line\n" . $herecurr);
+ }
+
# check for spaces at the beginning of a line.
# Exceptions:
# 1) within comments
^ permalink raw reply related [flat|nested] 3+ messages in thread
* RE: [PATCH] checkpatch: Check networking specific block comment style
2012-09-12 0:47 [PATCH] checkpatch: Check networking specific block comment style Joe Perches
@ 2012-09-12 1:19 ` Allan, Bruce W
2012-09-12 3:11 ` [PATCH] CodingStyle: Add " Joe Perches
0 siblings, 1 reply; 3+ messages in thread
From: Allan, Bruce W @ 2012-09-12 1:19 UTC (permalink / raw)
To: Joe Perches, Andrew Morton; +Cc: Andy Whitcroft, David Miller, LKML, netdev
> -----Original Message-----
> From: netdev-owner@vger.kernel.org [mailto:netdev-
> owner@vger.kernel.org] On Behalf Of Joe Perches
> Sent: Tuesday, September 11, 2012 5:48 PM
> To: Andrew Morton
> Cc: Andy Whitcroft; David Miller; LKML; netdev
> Subject: [PATCH] checkpatch: Check networking specific block comment
> style
>
> In an effort to get fewer checkpatch reviewer corrections,
> add a networking specific style test for the preferred
> networking comment style.
>
> /* The preferred style for block comments in
> * drivers/net/... and net/... is like this
> */
>
> These tests are only used in net/ and drivers/net/
>
> Tested with:
>
> $ cat drivers/net/t.c
>
> /* foo */
>
> /*
> * foo
> */
>
> /* foo
> */
>
> /* foo
> * bar */
> $ ./scripts/checkpatch.pl -f drivers/net/t.c
> WARNING: networking block comments don't use an empty /* line, use /* Comment...
This conflicts with the preferred style for long (multi-line) comments documented in
./Documentation/CodingStyle. If this is the way comments should be done in the
networking code this patch should also include an update to Chapter 8 in CodingStyle
documenting the networking specific style to avoid confusion.
^ permalink raw reply [flat|nested] 3+ messages in thread
* [PATCH] CodingStyle: Add networking specific block comment style
2012-09-12 1:19 ` Allan, Bruce W
@ 2012-09-12 3:11 ` Joe Perches
0 siblings, 0 replies; 3+ messages in thread
From: Joe Perches @ 2012-09-12 3:11 UTC (permalink / raw)
To: Allan, Bruce W; +Cc: Andrew Morton, Andy Whitcroft, David Miller, LKML, netdev
The block comment style in net/ and drivers/net is non-standard.
Document it.
Signed-off-by: Joe Perches <joe@perches.com>
---
> This conflicts with the preferred style for long (multi-line) comments documented in
> ./Documentation/CodingStyle. If this is the way comments should be done in the
> networking code this patch should also include an update to Chapter 8 in CodingStyle
> documenting the networking specific style to avoid confusion.
Documentation/CodingStyle | 10 ++++++++++
1 files changed, 10 insertions(+), 0 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index cb9258b..495e5ba 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -454,6 +454,16 @@ The preferred style for long (multi-line) comments is:
* with beginning and ending almost-blank lines.
*/
+For files in net/ and drivers/net/ the preferred style for long (multi-line)
+comments is a little different.
+
+ /* The preferred comment style for files in net/ and drivers/net
+ * looks like this.
+ *
+ * It is nearly the same as the generally preferred comment style,
+ * but there is no initial almost-blank line.
+ */
+
It's also important to comment data, whether they are basic types or derived
types. To this end, use just one data declaration per line (no commas for
multiple data declarations). This leaves you room for a small comment on each
^ permalink raw reply related [flat|nested] 3+ messages in thread
end of thread, other threads:[~2012-09-12 3:11 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2012-09-12 0:47 [PATCH] checkpatch: Check networking specific block comment style Joe Perches
2012-09-12 1:19 ` Allan, Bruce W
2012-09-12 3:11 ` [PATCH] CodingStyle: Add " Joe Perches
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).