From 5cb5c31cdf246099f7d48a57f448b05b7941cd6a Mon Sep 17 00:00:00 2001 From: Johannes Berg Date: Tue, 19 Sep 2017 13:08:13 +0200 Subject: scripts/kernel-doc: warn on excess enum value descriptions The existing message "Excess struct/union/enum/typedef member [...]" made it sound like this would already be done, but the code is never invoked for enums or typedefs (and really can't be). Add some code to the enum dumper to handle this there instead. While at it, also make the above message more accurate by simply dumping the type that was passed in, and pass the struct/union differentiation in. Signed-off-by: Johannes Berg Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 9d3eafea58f0..67d051edd615 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -2168,7 +2168,7 @@ sub dump_struct($$) { my $nested; if ($x =~ /(struct|union)\s+(\w+)\s*{(.*)}/) { - #my $decl_type = $1; + my $decl_type = $1; $declaration_name = $2; my $members = $3; @@ -2194,7 +2194,7 @@ sub dump_struct($$) { $members =~ s/DECLARE_HASHTABLE\s*\(([^,)]+), ([^,)]+)\)/unsigned long $1\[1 << (($2) - 1)\]/gos; create_parameterlist($members, ';', $file); - check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); + check_sections($file, $declaration_name, $decl_type, $sectcheck, $struct_actual, $nested); output_declaration($declaration_name, 'struct', @@ -2226,6 +2226,8 @@ sub dump_enum($$) { if ($x =~ /enum\s+(\w+)\s*{(.*)}/) { $declaration_name = $1; my $members = $2; + my %_members; + $members =~ s/\s+$//; foreach my $arg (split ',', $members) { @@ -2236,9 +2238,16 @@ sub dump_enum($$) { print STDERR "${file}:$.: warning: Enum value '$arg' ". "not described in enum '$declaration_name'\n"; } - + $_members{$arg} = 1; } + while (my ($k, $v) = each %parameterdescs) { + if (!exists($_members{$k})) { + print STDERR "${file}:$.: warning: Excess enum value " . + "'$k' description in '$declaration_name'\n"; + } + } + output_declaration($declaration_name, 'enum', {'enum' => $declaration_name, @@ -2506,7 +2515,7 @@ sub check_sections($$$$$$) { } else { if ($nested !~ m/\Q$sects[$sx]\E/) { print STDERR "${file}:$.: warning: " . - "Excess struct/union/enum/typedef member " . + "Excess $decl_type member " . "'$sects[$sx]' " . "description in '$decl_name'\n"; ++$warnings; -- cgit v1.2.3 From e8939222dced668fc5cae02b0b601af069801107 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Mon, 9 Oct 2017 18:26:15 +0300 Subject: Documentation: add script and build target to check for broken file references Add a simple script and build target to do a treewide grep for references to files under Documentation, and report the non-existing file in stderr. It tries to take into account punctuation not part of the filename, and wildcards, but there are bound to be false positives too. Mostly seems accurate though. We've moved files around enough to make having this worthwhile. Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/documentation-file-ref-check | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100755 scripts/documentation-file-ref-check (limited to 'scripts') diff --git a/scripts/documentation-file-ref-check b/scripts/documentation-file-ref-check new file mode 100755 index 000000000000..bc1659900e89 --- /dev/null +++ b/scripts/documentation-file-ref-check @@ -0,0 +1,15 @@ +#!/bin/sh +# Treewide grep for references to files under Documentation, and report +# non-existing files in stderr. + +for f in $(git ls-files); do + for ref in $(grep -ho "Documentation/[A-Za-z0-9_.,~/*+-]*" "$f"); do + # presume trailing . and , are not part of the name + ref=${ref%%[.,]} + + # use ls to handle wildcards + if ! ls $ref >/dev/null 2>&1; then + echo "$f: $ref" >&2 + fi + done +done -- cgit v1.2.3 From 45653c845b0c670b7a194acc6a90bc70aa049252 Mon Sep 17 00:00:00 2001 From: sayli karnik Date: Sat, 9 Sep 2017 22:26:18 +0530 Subject: scripts: Add a script to find unused documentation Add a script that finds files with kernel-doc comments for imported functions that are not included anywhere in documentation. Signed-off-by: sayli karnik Signed-off-by: Jonathan Corbet --- scripts/find-unused-docs.sh | 62 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100755 scripts/find-unused-docs.sh (limited to 'scripts') diff --git a/scripts/find-unused-docs.sh b/scripts/find-unused-docs.sh new file mode 100755 index 000000000000..3f46f8977dc4 --- /dev/null +++ b/scripts/find-unused-docs.sh @@ -0,0 +1,62 @@ +#!/bin/bash +# (c) 2017, Jonathan Corbet +# sayli karnik +# +# This script detects files with kernel-doc comments for exported functions +# that are not included in documentation. +# +# usage: Run 'scripts/find-unused-docs.sh directory' from top level of kernel +# tree. +# +# example: $scripts/find-unused-docs.sh drivers/scsi +# +# Licensed under the terms of the GNU GPL License + +if ! [ -d "Documentation" ]; then + echo "Run from top level of kernel tree" + exit 1 +fi + +if [ "$#" -ne 1 ]; then + echo "Usage: scripts/find-unused-docs.sh directory" + exit 1 +fi + +if ! [ -d "$1" ]; then + echo "Directory $1 doesn't exist" + exit 1 +fi + +cd "$( dirname "${BASH_SOURCE[0]}" )" +cd .. + +cd Documentation/ + +echo "The following files contain kerneldoc comments for exported functions \ +that are not used in the formatted documentation" + +# FILES INCLUDED + +files_included=($(grep -rHR ".. kernel-doc" --include \*.rst | cut -d " " -f 3)) + +declare -A FILES_INCLUDED + +for each in "${files_included[@]}"; do + FILES_INCLUDED[$each]="$each" + done + +cd .. + +# FILES NOT INCLUDED + +for file in `find $1 -name '*.c'`; do + + if [[ ${FILES_INCLUDED[$file]+_} ]]; then + continue; + fi + str=$(scripts/kernel-doc -text -export "$file" 2>/dev/null) + if [[ -n "$str" ]]; then + echo "$file" + fi + done + -- cgit v1.2.3