From ddf5eabd20c6cc2814fa2c00a1a033776fbc3e44 Mon Sep 17 00:00:00 2001 From: Yacine Belkadi Date: Tue, 27 Nov 2012 21:27:18 +0100 Subject: Kernel-doc: Convention: Use a "Return" section to describe return values Non-void functions should describe their return values in their kernel-doc comments. Currently, some don't, others do in various forms. For example: * Return the result. * Return: The result. * Returns the result. * Returns: the result. * Return Value: The result. * @return: the result. * This function returns the result. * It will return the result. Defining a convention would improve consistency of kernel-doc comments. It would also help scripts/kernel-doc identify the text describing the return value of a function. Thus allowing additional checks on the comments, and suitable highlighting in the generated docs (man pages, html, etc). So, as a convention, use a section named "Return" to describe the return value of a function. Signed-off-by: Yacine Belkadi Acked-by: Randy Dunlap Signed-off-by: Michal Marek --- Documentation/kernel-doc-nano-HOWTO.txt | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index 3d8a97747f77..99b57abddf8a 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -64,6 +64,8 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. + * + * Return: Describe the return value of foobar. */ The short description following the subject can span multiple lines @@ -78,6 +80,8 @@ If a function parameter is "..." (varargs), it should be listed in kernel-doc notation as: * @...: description +The return value, if any, should be described in a dedicated section +named "Return". Example kernel-doc data structure comment. @@ -222,6 +226,9 @@ only a "*"). "section header:" names must be unique per function (or struct, union, typedef, enum). +Use the section header "Return" for sections describing the return value +of a function. + Avoid putting a spurious blank line after the function name, or else the description will be repeated! @@ -237,21 +244,21 @@ patterns, which are highlighted appropriately. NOTE 1: The multi-line descriptive text you provide does *not* recognize line breaks, so if you try to format some text nicely, as in: - Return codes + Return: 0 - cool 1 - invalid arg 2 - out of memory this will all run together and produce: - Return codes 0 - cool 1 - invalid arg 2 - out of memory + Return: 0 - cool 1 - invalid arg 2 - out of memory NOTE 2: If the descriptive text you provide has lines that begin with some phrase followed by a colon, each of those phrases will be taken as a new section heading, which means you should similarly try to avoid text like: - Return codes: + Return: 0: cool 1: invalid arg 2: out of memory -- cgit v1.2.3 From 9a52aeeb92853167a67225602b9783f3cf4e578e Mon Sep 17 00:00:00 2001 From: Yacine Belkadi Date: Tue, 27 Nov 2012 21:27:19 +0100 Subject: scripts/kernel-doc: check that non-void fcts describe their return value If a function has a return value, but its kernel-doc comment doesn't contain a "Return" section, then emit the following warning: Warning(file.h:129): No description found for return value of 'fct' Note: This check emits a lot of warnings at the moment, because many functions don't have a 'Return' doc section. So until the number of warnings goes sufficiently down, the check is only performed in verbose mode. Signed-off-by: Yacine Belkadi Acked-by: Randy Dunlap Signed-off-by: Michal Marek --- scripts/kernel-doc | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 46e7aff80d1a..28b761567815 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -137,6 +137,8 @@ use strict; # should document the "Context:" of the function, e.g. whether the functions # can be called form interrupts. Unlike other sections you can end it with an # empty line. +# A non-void function should have a "Return:" section describing the return +# value(s). # Example-sections should contain the string EXAMPLE so that they are marked # appropriately in DocBook. # @@ -315,6 +317,7 @@ my $section_default = "Description"; # default section my $section_intro = "Introduction"; my $section = $section_default; my $section_context = "Context"; +my $section_return = "Return"; my $undescribed = "-- undescribed --"; @@ -2038,6 +2041,28 @@ sub check_sections($$$$$$) { } } +## +# Checks the section describing the return value of a function. +sub check_return_section { + my $file = shift; + my $declaration_name = shift; + my $return_type = shift; + + # Ignore an empty return type (It's a macro) + # Ignore functions with a "void" return type. (But don't ignore "void *") + if (($return_type eq "") || ($return_type =~ /void\s*\w*\s*$/)) { + return; + } + + if (!defined($sections{$section_return}) || + $sections{$section_return} eq "") { + print STDERR "Warning(${file}:$.): " . + "No description found for return value of " . + "'$declaration_name'\n"; + ++$warnings; + } +} + ## # takes a function prototype and the name of the current file being # processed and spits out all the details stored in the global @@ -2109,6 +2134,15 @@ sub dump_function($$) { my $prms = join " ", @parameterlist; check_sections($file, $declaration_name, "function", $sectcheck, $prms, ""); + # This check emits a lot of warnings at the moment, because many + # functions don't have a 'Return' doc section. So until the number + # of warnings goes sufficiently down, the check is only performed in + # verbose mode. + # TODO: always perform the check. + if ($verbose) { + check_return_section($file, $declaration_name, $return_type); + } + output_declaration($declaration_name, 'function', {'function' => $declaration_name, -- cgit v1.2.3 From ad99ac2fa76b4a793ee801920f7501c8df6534d0 Mon Sep 17 00:00:00 2001 From: Julia Lawall Date: Sat, 3 Nov 2012 21:02:09 +0100 Subject: scripts/coccinelle/misc/warn.cocci: use WARN Use WARN(1,...) rather than printk followed by WARN(1). Signed-off-by: Julia Lawall Signed-off-by: Michal Marek --- scripts/coccinelle/misc/warn.cocci | 109 +++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 scripts/coccinelle/misc/warn.cocci diff --git a/scripts/coccinelle/misc/warn.cocci b/scripts/coccinelle/misc/warn.cocci new file mode 100644 index 000000000000..fda8c3558e4f --- /dev/null +++ b/scripts/coccinelle/misc/warn.cocci @@ -0,0 +1,109 @@ +/// Use WARN(1,...) rather than printk followed by WARN_ON(1) +/// +// Confidence: High +// Copyright: (C) 2012 Julia Lawall, INRIA/LIP6. GPLv2. +// Copyright: (C) 2012 Gilles Muller, INRIA/LiP6. GPLv2. +// URL: http://coccinelle.lip6.fr/ +// Comments: +// Options: -no_includes -include_headers + +virtual patch +virtual context +virtual org +virtual report + +@bad1@ +position p; +@@ + +printk(...); +printk@p(...); +WARN_ON(1); + +@r1 depends on context || report || org@ +position p != bad1.p; +@@ + + printk@p(...); +*WARN_ON(1); + +@script:python depends on org@ +p << r1.p; +@@ + +cocci.print_main("printk + WARN_ON can be just WARN",p) + +@script:python depends on report@ +p << r1.p; +@@ + +msg = "SUGGESTION: printk + WARN_ON can be just WARN" +coccilib.report.print_report(p[0],msg) + +@ok1 depends on patch@ +expression list es; +position p != bad1.p; +@@ + +-printk@p( ++WARN(1, + es); +-WARN_ON(1); + +@depends on patch@ +expression list ok1.es; +@@ + +if (...) +- { + WARN(1,es); +- } + +// -------------------------------------------------------------------- + +@bad2@ +position p; +@@ + +printk(...); +printk@p(...); +WARN_ON_ONCE(1); + +@r2 depends on context || report || org@ +position p != bad1.p; +@@ + + printk@p(...); +*WARN_ON_ONCE(1); + +@script:python depends on org@ +p << r2.p; +@@ + +cocci.print_main("printk + WARN_ON_ONCE can be just WARN_ONCE",p) + +@script:python depends on report@ +p << r2.p; +@@ + +msg = "SUGGESTION: printk + WARN_ON_ONCE can be just WARN_ONCE" +coccilib.report.print_report(p[0],msg) + +@ok2 depends on patch@ +expression list es; +position p != bad2.p; +@@ + +-printk@p( ++WARN_ONCE(1, + es); +-WARN_ON_ONCE(1); + +@depends on patch@ +expression list ok2.es; +@@ + +if (...) +- { + WARN_ONCE(1,es); +- } -- cgit v1.2.3 From 596585090a6d7f0a62b4e5864ad8cedf1af964d1 Mon Sep 17 00:00:00 2001 From: Joonsoo Kim Date: Tue, 11 Dec 2012 00:11:45 +0900 Subject: scripts/tags.sh: Support subarch for ARM Current tags.sh doesn't handle subarch for ARM. There are too many subarch on ARM, it is hard that we locate some functions which are defined in every subarch with tags util family. Therefore support subarch for removing this unconvenience. We can use ARM subarch functionality like below. "make cscope O=. SRCARCH=arm SUBARCH=xxx" Signed-off-by: Joonsoo Kim Signed-off-by: Michal Marek --- scripts/tags.sh | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/scripts/tags.sh b/scripts/tags.sh index 79fdafb0d263..8fb18d1da71b 100755 --- a/scripts/tags.sh +++ b/scripts/tags.sh @@ -48,13 +48,14 @@ find_arch_sources() for i in $archincludedir; do prune="$prune -wholename $i -prune -o" done - find ${tree}arch/$1 $ignore $prune -name "$2" -print; + find ${tree}arch/$1 $ignore $subarchprune $prune -name "$2" -print; } # find sources in arch/$1/include find_arch_include_sources() { - include=$(find ${tree}arch/$1/ -name include -type d); + include=$(find ${tree}arch/$1/ $subarchprune \ + -name include -type d -print); if [ -n "$include" ]; then archincludedir="$archincludedir $include" find $include $ignore -name "$2" -print; @@ -234,6 +235,21 @@ if [ "${ARCH}" = "um" ]; then else archinclude=${SUBARCH} fi +elif [ "${SRCARCH}" = "arm" -a "${SUBARCH}" != "" ]; then + subarchdir=$(find ${tree}arch/$SRCARCH/ -name "mach-*" -type d -o \ + -name "plat-*" -type d); + for i in $subarchdir; do + case "$i" in + *"mach-"${SUBARCH}) + ;; + *"plat-"${SUBARCH}) + ;; + *) + subarchprune="$subarchprune \ + -wholename $i -prune -o" + ;; + esac + done fi remove_structs= -- cgit v1.2.3 From 923e02ecf3f8db19d52176723fefa0ffe6e9a3cd Mon Sep 17 00:00:00 2001 From: Joonsoo Kim Date: Tue, 11 Dec 2012 00:11:46 +0900 Subject: scripts/tags.sh: Support compiled source We usually have interst in compiled files only, because they are strongly related to individual's work. Current tags.sh can't select compiled files, so support it. We can use this functionality like below. "make cscope O=. SRCARCH=xxxx COMPILED_SOURCE=compiled" It must be executed after building the kernel. Signed-off-by: Joonsoo Kim Signed-off-by: Michal Marek --- scripts/tags.sh | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/scripts/tags.sh b/scripts/tags.sh index 8fb18d1da71b..08f06c00745e 100755 --- a/scripts/tags.sh +++ b/scripts/tags.sh @@ -96,6 +96,32 @@ all_sources() find_other_sources '*.[chS]' } +all_compiled_sources() +{ + for i in $(all_sources); do + case "$i" in + *.[cS]) + j=${i/\.[cS]/\.o} + if [ -e $j ]; then + echo $i + fi + ;; + *) + echo $i + ;; + esac + done +} + +all_target_sources() +{ + if [ -n "$COMPILED_SOURCE" ]; then + all_compiled_sources + else + all_sources + fi +} + all_kconfigs() { for arch in $ALLSOURCE_ARCHS; do @@ -111,18 +137,18 @@ all_defconfigs() docscope() { - (echo \-k; echo \-q; all_sources) > cscope.files + (echo \-k; echo \-q; all_target_sources) > cscope.files cscope -b -f cscope.out } dogtags() { - all_sources | gtags -i -f - + all_target_sources | gtags -i -f - } exuberant() { - all_sources | xargs $1 -a \ + all_target_sources | xargs $1 -a \ -I __initdata,__exitdata,__acquires,__releases \ -I __read_mostly,____cacheline_aligned \ -I ____cacheline_aligned_in_smp \ @@ -174,7 +200,7 @@ exuberant() emacs() { - all_sources | xargs $1 -a \ + all_target_sources | xargs $1 -a \ --regex='/^(ENTRY|_GLOBAL)(\([^)]*\)).*/\2/' \ --regex='/^SYSCALL_DEFINE[0-9]?(\([^,)]*\).*/sys_\1/' \ --regex='/^TRACE_EVENT(\([^,)]*\).*/trace_\1/' \ @@ -221,11 +247,10 @@ xtags() elif $1 --version 2>&1 | grep -iq emacs; then emacs $1 else - all_sources | xargs $1 -a + all_target_sources | xargs $1 -a fi } - # Support um (which uses SUBARCH) if [ "${ARCH}" = "um" ]; then if [ "$SUBARCH" = "i386" ]; then -- cgit v1.2.3 From c6ba8d06ecfc1dadcf7f1b54960cf9332ba5ae8d Mon Sep 17 00:00:00 2001 From: Hiroshi Doyu Date: Fri, 14 Dec 2012 08:47:59 +0200 Subject: scripts/config: Fix wrong "shift" for --keep-case Remove wrong "shift" for --keep-case. There is always "shift" at beginning of while-loop. No need "shift" at --keep-case just before "continue" to process next argument. Now the following works as expected: ./scripts/config -e aAa -k -e bBb -e cCc && tail -3 .config CONFIG_AAA=y CONFIG_bBb=y CONFIG_cCc=y Signed-off-by: Hiroshi Doyu Signed-off-by: Michal Marek --- scripts/config | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/config b/scripts/config index ee355394f4ef..bb4d3deb6d1c 100755 --- a/scripts/config +++ b/scripts/config @@ -101,7 +101,6 @@ while [ "$1" != "" ] ; do case "$CMD" in --keep-case|-k) MUNGE_CASE=no - shift continue ;; --refresh) -- cgit v1.2.3