From 8c27ceff3604b249a9efafbd1bd8b141b79e619d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:12:27 -0200 Subject: docs: fix locations of several documents that got moved The previous patch renamed several files that are cross-referenced along the Kernel documentation. Adjust the links to point to the right places. Signed-off-by: Mauro Carvalho Chehab --- scripts/checkpatch.pl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'scripts') diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index a8368d1c4348..d0c729ccec20 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -2187,7 +2187,7 @@ sub process { if ($rawline=~/^\+\+\+\s+(\S+)/) { $setup_docs = 0; - if ($1 =~ m@Documentation/kernel-parameters.txt$@) { + if ($1 =~ m@Documentation/admin-guide/kernel-parameters.rst$@) { $setup_docs = 1; } #next; @@ -5102,7 +5102,7 @@ sub process { my $asm_volatile = qr{\b(__asm__|asm)\s+(__volatile__|volatile)\b}; if ($line =~ /\bvolatile\b/ && $line !~ /$asm_volatile/) { WARN("VOLATILE", - "Use of volatile is usually wrong: see Documentation/volatile-considered-harmful.txt\n" . $herecurr); + "Use of volatile is usually wrong: see Documentation/process/volatile-considered-harmful.rst\n" . $herecurr); } # Check for user-visible strings broken across lines, which breaks the ability @@ -5817,7 +5817,7 @@ sub process { if (!grep(/$name/, @setup_docs)) { CHK("UNDOCUMENTED_SETUP", - "__setup appears un-documented -- check Documentation/kernel-parameters.txt\n" . $herecurr); + "__setup appears un-documented -- check Documentation/admin-guide/kernel-parameters.rst\n" . $herecurr); } } -- cgit v1.2.3 From c950a1739eaef2ab64372fc35af7301fcef2c9a7 Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:08 +0200 Subject: kernel-doc: better parsing of named variable arguments Without this patch we get warnings for named variable arguments. warning: No description found for parameter '...' warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue' Signed-off-by: Silvio Fricke Reviewed-by: Jani Nikula --- scripts/kernel-doc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 93721f3c91bf..e10378f769f9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -204,6 +204,7 @@ EOF ## init lots of data + my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; @@ -211,7 +212,7 @@ my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; -my $type_param = '\@(\w+)'; +my $type_param = '\@(\w+(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; @@ -2353,7 +2354,10 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { - $param = "..."; + if (!$param =~ /\w\.\.\.$/) { + # handles unnamed variable parameters + $param = "..."; + } if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } -- cgit v1.2.3 From 0c9aa209579d41c9b8bf1fc39ce042bea2ec422d Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 16 Nov 2016 17:26:16 +0200 Subject: kernel-doc: add support for one line inline struct member doc comments kernel-doc supports documenting struct members "inline" since a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation in struct body"). This requires the inline kernel-doc comments to have the opening and closing comment markers (/** and */ respectively) on lines of their own, even for short comments. For example: /** * struct foo - struct documentation */ struct foo { /** * @bar: member documentation */ int bar; }; Add support for one line inline comments: /** * struct foo - struct documentation */ struct foo { /** @bar: member documentation */ int bar; }; Note that mixing of the two in one doc comment is not allowed; either both comment markers must be on lines of their own, or both must be on the one line. This limitation keeps both the comments more uniform, and kernel-doc less complicated. Cc: Daniel Vetter Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/kernel-doc b/scripts/kernel-doc index e10378f769f9..030fc633acd4 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -421,6 +421,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)'; my $doc_inline_end = '^\s*\*/\s*$'; +my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$'; my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;'; my %parameterdescs; @@ -3024,7 +3025,16 @@ sub process_file($) { } } } elsif ($state == STATE_PROTO) { # scanning for function '{' (end of prototype) - if (/$doc_inline_start/) { + if (/$doc_inline_oneline/) { + $section = $1; + $contents = $2; + if ($contents ne "") { + $contents .= "\n"; + dump_section($file, $section, xml_escape($contents)); + $section = $section_default; + $contents = ""; + } + } elsif (/$doc_inline_start/) { $state = STATE_INLINE; $inline_doc_state = STATE_INLINE_NAME; } elsif ($decl_type eq 'function') { -- cgit v1.2.3 From f15c323397f87b978f4057eb1462efcbf487493a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 5 Dec 2016 09:41:41 -0200 Subject: scripts: add a script to check if Documentation/00-INDEX is sane It is easy to forget adding/removing entries at the Documentation/00-INDEX file. In a matter of fact, even before ReST conversion, people use to forget adding things here, as there are lots of missing stuff out there. Now that we're doing a hard work converting entries to ReST, and while this hole file is not outdated, it is good to have some tool that would help to verify that this file is kept updated. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/check_00index.sh | 66 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100755 scripts/check_00index.sh (limited to 'scripts') diff --git a/scripts/check_00index.sh b/scripts/check_00index.sh new file mode 100755 index 000000000000..6ac9527aeddb --- /dev/null +++ b/scripts/check_00index.sh @@ -0,0 +1,66 @@ +#!/bin/bash + +cd Documentation/ + +# Check entries that should be removed + +obsolete="" +for i in $(tail -n +12 00-INDEX |grep -E '^[a-zA-Z0-9]+'); do + if [ ! -e $i ]; then + obsolete="$obsolete $i" + fi +done + +# Check directory entries that should be added +search="" +dir="" +for i in $(find . -maxdepth 1 -type d); do + if [ "$i" != "." ]; then + new=$(echo $i|perl -ne 's,./(.*),$1/,; print $_') + search="$search $new" + fi +done + +for i in $search; do + if [ "$(grep -P "^$i" 00-INDEX)" == "" ]; then + dir="$dir $i" + fi +done + +# Check file entries that should be added +search="" +file="" +for i in $(find . -maxdepth 1 -type f); do + if [ "$i" != "./.gitignore" ]; then + new=$(echo $i|perl -ne 's,./(.*),$1,; print $_') + search="$search $new" + fi +done + +for i in $search; do + if [ "$(grep -P "^$i\$" 00-INDEX)" == "" ]; then + file="$file $i" + fi +done + +# Output its findings + +echo -e "Documentation/00-INDEX check results:\n" + +if [ "$obsolete" != "" ]; then + echo -e "- Should remove those entries:\n\t$obsolete\n" +else + echo -e "- No obsolete entries\n" +fi + +if [ "$dir" != "" ]; then + echo -e "- Should document those directories:\n\t$dir\n" +else + echo -e "- No new directories to add\n" +fi + +if [ "$file" != "" ]; then + echo -e "- Should document those files:\n\t$file" +else + echo "- No new files to add" +fi -- cgit v1.2.3