tools/kernel-doc/docproc.c and tools/kernel-doc/kernel-doc are script files imported Linux Kernel.

They originally resided under scripts/ directory in Linux Kernel.

This commit moves them to the original location.

Signed-off-by: Masahiro Yamada yamada.m@jp.panasonic.com ---

Makefile | 10 +++++++--- doc/DocBook/Makefile | 15 ++++++--------- scripts/.gitignore | 4 ++++ scripts/Makefile | 14 ++++++++++++++ {tools/kernel-doc => scripts}/docproc.c | 2 +- {tools/kernel-doc => scripts}/kernel-doc | 0 tools/.gitignore | 1 - tools/Makefile | 2 -- tools/kernel-doc/Makefile | 10 ---------- 9 files changed, 32 insertions(+), 26 deletions(-) create mode 100644 scripts/.gitignore rename {tools/kernel-doc => scripts}/docproc.c (99%) rename {tools/kernel-doc => scripts}/kernel-doc (100%) delete mode 100644 tools/kernel-doc/Makefile

diff --git a/Makefile b/Makefile index 21274be..3bf759a 100644 --- a/Makefile +++ b/Makefile @@ -1152,9 +1152,6 @@ $(TIMESTAMP_FILE): env: depend scripts_basic $(Q)$(MAKE) $(build)=tools/$@

-xmldocs pdfdocs psdocs htmldocs mandocs: tools/kernel-doc/docproc - $(Q)$(MAKE) U_BOOT_VERSION=$(U_BOOT_VERSION) $(build)=doc/DocBook $@ - tools-all: HOST_TOOLS_ALL=y tools-all: env tools ;

@@ -1272,6 +1269,13 @@ backup: F=`basename $(TOPDIR)` ; cd .. ; \ gtar --force-local -zcvf `LC_ALL=C date "+$$F-%Y-%m-%d-%T.tar.gz"` $$F

+ +# Documentation targets +# --------------------------------------------------------------------------- +%docs: scripts_basic FORCE + $(Q)$(MAKE) $(build)=scripts build_docproc + $(Q)$(MAKE) $(build)=doc/DocBook $@ + # Dummies... PHONY += prepare scripts prepare: ; diff --git a/doc/DocBook/Makefile b/doc/DocBook/Makefile index 75e59c2..3077134 100644 --- a/doc/DocBook/Makefile +++ b/doc/DocBook/Makefile @@ -1,7 +1,7 @@ ### # This makefile is used to generate the kernel documentation, # primarily based on in-line comments in various source files. -# See doc/kernel-doc-nano-HOWTO.txt for instruction in how +# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how # to document the SRC - and how to read it. # To add a new book the only step required is to add the book to the # list of DOCBOOKS. @@ -51,8 +51,8 @@ installmandocs: mandocs

### #External programs used -KERNELDOC = $(srctree)/tools/kernel-doc/kernel-doc -DOCPROC = $(objtree)/tools/kernel-doc/docproc +KERNELDOC = $(srctree)/scripts/kernel-doc +DOCPROC = $(objtree)/scripts/docproc

XMLTOFLAGS = -m $(srctree)/doc/DocBook/stylesheet.xsl XMLTOFLAGS += --skip-validation @@ -134,11 +134,8 @@ build_main_index = rm -rf $(main_idx); \ echo '<h2>U-Boot Version: $(U_BOOT_VERSION)</h2>' >> $(main_idx) && \ cat $(HTML) >> $(main_idx)

-# To work around bug [1] in docbook-xsl-stylesheets 1.76.1 , generate only html -# docs instead of xhtml with xmlto. -# [1] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=654338 quiet_cmd_db2html = HTML $@ - cmd_db2html = xmlto html $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ + cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \ $(patsubst %.html,%,$(notdir $@))</a><p>' > $@

@@ -225,8 +222,8 @@ clean-files := $(DOCBOOKS) \ clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man

cleandocs: - @$(Q)rm -f $(call objectify, $(clean-files)) - @$(Q)rm -rf $(call objectify, $(clean-dirs)) + $(Q)rm -f $(call objectify, $(clean-files)) + $(Q)rm -rf $(call objectify, $(clean-dirs))

# Declare the contents of the .PHONY variable as phony. We keep that # information in a variable se we can use it in if_changed and friends. diff --git a/scripts/.gitignore b/scripts/.gitignore new file mode 100644 index 0000000..82bc06e --- /dev/null +++ b/scripts/.gitignore @@ -0,0 +1,4 @@ +# +# Generated files +# +docproc diff --git a/scripts/Makefile b/scripts/Makefile index ebbadc9..242e3a0 100644 --- a/scripts/Makefile +++ b/scripts/Makefile @@ -1,2 +1,16 @@ +### +# scripts contains sources for various helper programs used throughout +# the kernel for the build process. +# --------------------------------------------------------------------------- +# docproc: Used in Documentation/DocBook + +# The following hostprogs-y programs are only build on demand +hostprogs-y += docproc + +# These targets are used internally to avoid "is up to date" messages +PHONY += build_docproc +build_docproc: scripts/docproc + @: + # Let clean descend into subdirs subdir- += basic diff --git a/tools/kernel-doc/docproc.c b/scripts/docproc.c similarity index 99% rename from tools/kernel-doc/docproc.c rename to scripts/docproc.c index a9b49c5..23c3a43 100644 --- a/tools/kernel-doc/docproc.c +++ b/scripts/docproc.c @@ -65,7 +65,7 @@ FILELINE * docsection;

#define MAXLINESZ 2048 #define MAXFILES 250 -#define KERNELDOCPATH "tools/kernel-doc/" +#define KERNELDOCPATH "scripts/" #define KERNELDOC "kernel-doc" #define DOCBOOK "-docbook" #define LIST "-list" diff --git a/tools/kernel-doc/kernel-doc b/scripts/kernel-doc similarity index 100% rename from tools/kernel-doc/kernel-doc rename to scripts/kernel-doc diff --git a/tools/.gitignore b/tools/.gitignore index 6e4a287..2a90dfe 100644 --- a/tools/.gitignore +++ b/tools/.gitignore @@ -18,4 +18,3 @@ /easylogo/easylogo /gdb/gdbcont /gdb/gdbsend -/kernel-doc/docproc diff --git a/tools/Makefile b/tools/Makefile index 783e643..dcd49f8 100644 --- a/tools/Makefile +++ b/tools/Makefile @@ -183,8 +183,6 @@ HOST_EXTRACFLAGS += -include $(SRCTREE)/include/libfdt_env.h \

__build: $(LOGO-y)

-subdir-y += kernel-doc - $(LOGO_H): $(obj)/bmp_logo $(LOGO_BMP) $(obj)/bmp_logo --gen-info $(LOGO_BMP) > $@

diff --git a/tools/kernel-doc/Makefile b/tools/kernel-doc/Makefile deleted file mode 100644 index f15a4b7..0000000 --- a/tools/kernel-doc/Makefile +++ /dev/null @@ -1,10 +0,0 @@ -# -# Copyright (C) 2012 Marek Vasut marex@denx.de -# -# SPDX-License-Identifier: GPL-2.0+ -# - -hostprogs-y := docproc -always := $(hostprogs-y) - -HOST_EXTRACFLAGS := -pedantic

Signed-off-by: Masahiro Yamada yamada.m@jp.panasonic.com ---

doc/DocBook/stylesheet.xsl | 1 - scripts/docproc.c | 72 +++++++++++++++++++++++--------------------- scripts/kernel-doc | 74 +++++++++++++++++++++++++++++++++++++++------- 3 files changed, 101 insertions(+), 46 deletions(-)

diff --git a/doc/DocBook/stylesheet.xsl b/doc/DocBook/stylesheet.xsl index 8adce56..85b2527 100644 --- a/doc/DocBook/stylesheet.xsl +++ b/doc/DocBook/stylesheet.xsl @@ -7,5 +7,4 @@ <!-- <param name="paper.type">A4</param> --> <param name="generate.section.toc.level">2</param> <param name="use.id.as.filename">1</param> -<param name="html.stylesheet">../docbook.css</param> </stylesheet> diff --git a/scripts/docproc.c b/scripts/docproc.c index 23c3a43..2b69eaf 100644 --- a/scripts/docproc.c +++ b/scripts/docproc.c @@ -72,6 +72,7 @@ FILELINE * docsection; #define FUNCTION "-function" #define NOFUNCTION "-nofunction" #define NODOCSECTIONS "-no-doc-sections" +#define SHOWNOTFOUND "-show-not-found"

static char *srctree, *kernsrctree;

@@ -153,7 +154,7 @@ int symfilecnt = 0; static void add_new_symbol(struct symfile *sym, char * symname) { sym->symbollist = - realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); + realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *)); sym->symbollist[sym->symbolcnt++].name = strdup(symname); }

@@ -214,7 +215,7 @@ static void find_export_symbols(char * filename) char *p; char *e; if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != NULL) || - ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { + ((p = strstr(line, "EXPORT_SYMBOL")) != NULL)) { /* Skip EXPORT_SYMBOL{_GPL} */ while (isalnum(*p) || *p == '_') p++; @@ -290,27 +291,28 @@ static void extfunc(char * filename) { docfunctions(filename, FUNCTION); } static void singfunc(char * filename, char * line) { char *vec[200]; /* Enough for specific functions */ - int i, idx = 0; - int startofsym = 1; + int i, idx = 0; + int startofsym = 1; vec[idx++] = KERNELDOC; vec[idx++] = DOCBOOK; - - /* Split line up in individual parameters preceded by FUNCTION */ - for (i=0; line[i]; i++) { - if (isspace(line[i])) { - line[i] = '\0'; - startofsym = 1; - continue; - } - if (startofsym) { - startofsym = 0; - vec[idx++] = FUNCTION; - vec[idx++] = &line[i]; - } - } + vec[idx++] = SHOWNOTFOUND; + + /* Split line up in individual parameters preceded by FUNCTION */ + for (i=0; line[i]; i++) { + if (isspace(line[i])) { + line[i] = '\0'; + startofsym = 1; + continue; + } + if (startofsym) { + startofsym = 0; + vec[idx++] = FUNCTION; + vec[idx++] = &line[i]; + } + } for (i = 0; i < idx; i++) { - if (strcmp(vec[i], FUNCTION)) - continue; + if (strcmp(vec[i], FUNCTION)) + continue; consume_symbol(vec[i + 1]); } vec[idx++] = filename; @@ -325,7 +327,8 @@ static void singfunc(char * filename, char * line) */ static void docsect(char *filename, char *line) { - char *vec[6]; /* kerneldoc -docbook -function "section" file NULL */ + /* kerneldoc -docbook -show-not-found -function "section" file NULL */ + char *vec[7]; char *s;

for (s = line; *s; s++) @@ -341,10 +344,11 @@ static void docsect(char *filename, char *line)

vec[0] = KERNELDOC; vec[1] = DOCBOOK; - vec[2] = FUNCTION; - vec[3] = line; - vec[4] = filename; - vec[5] = NULL; + vec[2] = SHOWNOTFOUND; + vec[3] = FUNCTION; + vec[4] = line; + vec[5] = filename; + vec[6] = NULL; exec_kernel_doc(vec); }

@@ -456,14 +460,14 @@ static void parse_file(FILE *infile) break; case 'D': while (*s && !isspace(*s)) s++; - *s = '\0'; - symbolsonly(line+2); - break; + *s = '\0'; + symbolsonly(line+2); + break; case 'F': /* filename */ while (*s && !isspace(*s)) s++; *s++ = '\0'; - /* function names */ + /* function names */ while (isspace(*s)) s++; singlefunctions(line +2, s); @@ -511,11 +515,11 @@ int main(int argc, char *argv[]) } /* Open file, exit on error */ infile = fopen(argv[2], "r"); - if (infile == NULL) { - fprintf(stderr, "docproc: "); - perror(argv[2]); - exit(2); - } + if (infile == NULL) { + fprintf(stderr, "docproc: "); + perror(argv[2]); + exit(2); + }

if (strcmp("doc", argv[1]) == 0) { /* Need to do this in two passes. diff --git a/scripts/kernel-doc b/scripts/kernel-doc index cbbf34c..ba2bafd 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. # @@ -245,6 +247,7 @@ my $dohighlight = "";

my $verbose = 0; my $output_mode = "man"; +my $output_preformatted = 0; my $no_doc_sections = 0; my %highlights = %highlights_man; my $blankline = $blankline_man; @@ -254,6 +257,7 @@ my $man_date = ('January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December')[(localtime)[4]] . " " . ((localtime)[5]+1900); +my $show_not_found = 0;

# Essentially these are globals. # They probably want to be tidied up, made more localised or something. @@ -295,9 +299,10 @@ my $doc_special = "@%$&"; my $doc_start = '^/**\s*$'; # Allow whitespace at end of comment start. my $doc_end = '*/'; my $doc_com = '\s**\s*'; +my $doc_com_body = '\s** ?'; my $doc_decl = $doc_com . '(\w+)'; my $doc_sect = $doc_com . '([' . $doc_special . ']?[\w\s]+):(.*)'; -my $doc_content = $doc_com . '(.*)'; +my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?';

my %constants; @@ -313,6 +318,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 --";

@@ -364,6 +370,8 @@ while ($ARGV[0] =~ m/^-(.*)/) { usage(); } elsif ($cmd eq '-no-doc-sections') { $no_doc_sections = 1; + } elsif ($cmd eq '-show-not-found') { + $show_not_found = 1; } }

@@ -432,7 +440,7 @@ sub dump_doc_section { my $contents = join "\n", @_;

if ($no_doc_sections) { - return; + return; }

if (($function_only == 0) || @@ -485,8 +493,13 @@ sub output_highlight { $contents =~ s/\s+$//; } foreach $line (split "\n", $contents) { + if (! $output_preformatted) { + $line =~ s/^\s*//; + } if ($line eq ""){ - print $lineprefix, local_unescape($blankline); + if (! $output_preformatted) { + print $lineprefix, local_unescape($blankline); + } } else { $line =~ s/\\\/&/g; if ($output_mode eq "man" && substr($line, 0, 1) eq ".") { @@ -902,10 +915,12 @@ sub output_section_xml(%) { print "<title>$section</title>\n"; if ($section =~ m/EXAMPLE/i) { print "<informalexample><programlisting>\n"; + $output_preformatted = 1; } else { print "<para>\n"; } output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "</programlisting></informalexample>\n"; } else { @@ -1208,10 +1223,12 @@ sub output_blockhead_xml(%) { } if ($section =~ m/EXAMPLE/i) { print "<example><para>\n"; + $output_preformatted = 1; } else { print "<para>\n"; } output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; if ($section =~ m/EXAMPLE/i) { print "</para></example>\n"; } else { @@ -1287,10 +1304,12 @@ sub output_function_gnome { print "<simplesect>\n <title>$section</title>\n"; if ($section =~ m/EXAMPLE/i) { print "<example><programlisting>\n"; + $output_preformatted = 1; } else { } print "<para>\n"; output_highlight($args{'sections'}{$section}); + $output_preformatted = 0; print "</para>\n"; if ($section =~ m/EXAMPLE/i) { print "</programlisting></example>\n"; @@ -1734,7 +1753,7 @@ sub dump_struct($$) { # strip kmemcheck_bitfield_{begin,end}.*; $members =~ s/kmemcheck_bitfield_.*?;//gos; # strip attributes - $members =~ s/__aligned\s*(\d+)//gos; + $members =~ s/__aligned\s*(.+)//gos;

create_parameterlist($members, ';', $file); check_sections($file, $declaration_name, "struct", $sectcheck, $struct_actual, $nested); @@ -2026,6 +2045,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 # arrays/hashes. @@ -2041,7 +2082,6 @@ sub dump_function($$) { $prototype =~ s/^__inline +//; $prototype =~ s/^__always_inline +//; $prototype =~ s/^noinline +//; - $prototype =~ s/__devinit +//; $prototype =~ s/__init +//; $prototype =~ s/__init_or_module +//; $prototype =~ s/__must_check +//; @@ -2088,14 +2128,22 @@ sub dump_function($$) {

create_parameterlist($args, ',', $file); } else { - print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n"; - ++$errors; + print STDERR "Warning(${file}:$.): cannot understand function prototype: '$prototype'\n"; return; }

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, @@ -2305,6 +2353,9 @@ sub process_file($) {

$section_counter = 0; while (<IN>) { + while (s/\\s*$//) { + $_ .= <IN>; + } if ($state == 0) { if (/$doc_start/o) { $state = 1; # next line is always the function name @@ -2332,7 +2383,7 @@ sub process_file($) { $descr= $1; $descr =~ s/^\s*//; $descr =~ s/\s*$//; - $descr =~ s/\s+/ /; + $descr =~ s/\s+/ /g; $declaration_purpose = xml_escape($descr); $in_purpose = 1; } else { @@ -2424,9 +2475,7 @@ sub process_file($) { # Continued declaration purpose chomp($declaration_purpose); $declaration_purpose .= " " . xml_escape($1); - } elsif ($section =~ m/^Example/) { - $_ =~ s/^\s**//; - $contents .= $_; + $declaration_purpose =~ s/\s+/ /g; } else { $contents .= $1 . "\n"; } @@ -2489,6 +2538,9 @@ sub process_file($) { } if ($initial_section_counter == $section_counter) { print STDERR "Warning(${file}): no structured comments found\n"; + if (($function_only == 1) && ($show_not_found == 1)) { + print STDERR " Was looking for '$_'.\n" for keys %function_table; + } if ($output_mode eq "xml") { # The template wants at least one RefEntry here; make one. print "<refentry>\n";

- Delete fs.xml from DOCBOOKS to fix an error Commit e3ff797c added fs.xml to DOCBOOKS but missed to add doc/DocBook/fs.tmpl - Fix the location of include guard in include/linker_lists.h

Signed-off-by: Masahiro Yamada yamada.m@jp.panasonic.com Reported-by: Abraham Varricatt abraham.varricatt@vvdntech.com ---

This problem was reported by Abraham Varricatt: http://u-boot.10912.n7.nabble.com/quot-make-htmldocs-quot-gives-error-td1688...

doc/DocBook/Makefile | 2 +- include/linker_lists.h | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/doc/DocBook/Makefile b/doc/DocBook/Makefile index 3077134..44afc47 100644 --- a/doc/DocBook/Makefile +++ b/doc/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS.

-DOCBOOKS := fs.xml linker_lists.xml stdio.xml +DOCBOOKS := linker_lists.xml stdio.xml

### # The build process is as follows (targets): diff --git a/include/linker_lists.h b/include/linker_lists.h index 1eebb95..997d149 100644 --- a/include/linker_lists.h +++ b/include/linker_lists.h @@ -8,6 +8,9 @@ * SPDX-License-Identifier: GPL-2.0+ */

+#ifndef __LINKER_LISTS_H__ +#define __LINKER_LISTS_H__ + /* * There is no use in including this from ASM files, but that happens * anyway, e.g. PPC kgdb.S includes command.h which incluse us. @@ -97,9 +100,6 @@ * %u_boot_list_2_drivers_3 */

-#ifndef __LINKER_LISTS_H__ -#define __LINKER_LISTS_H__ - /** * ll_entry_declare() - Declare linker-generated array entry * @_type: Data type of the entry