[U-Boot] [PATCH v2 0/3] Adjust and fix kernel-doc

[U-Boot] [PATCH v2 0/3] Adjust and fix kernel-doc

[Masahiro Yamada]

"make %docs" have not worked for a while.

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

This series adjusts kernel doc stuff to the current build system
and fixes errors.

By applying this series, "make pdfdocs", "make htmldocs", etc. will work.

This series uses my Kbuild series as a prerequisite.
"Switch over to real Kbuild" series must be applied beforehand.


Changes in v2:
  - fix typos in commit log
  - update also .gitignore

Masahiro Yamada (3):
  kernel-doc: move kernel-doc tools to scripts/
  kernel-doc: update kernel-doc related files to Linux v3.13
  kernel-doc: fix some errors

 Makefile                                 | 10 +++--
 doc/DocBook/.gitignore                   |  1 -
 doc/DocBook/Makefile                     | 17 +++-----
 doc/DocBook/stylesheet.xsl               |  1 -
 include/linker_lists.h                   |  6 +--
 scripts/.gitignore                       |  4 ++
 scripts/Makefile                         | 14 ++++++
 {tools/kernel-doc => scripts}/docproc.c  | 74 +++++++++++++++++---------------
 {tools/kernel-doc => scripts}/kernel-doc | 74 +++++++++++++++++++++++++++-----
 tools/.gitignore                         |  1 -
 tools/Makefile                           |  2 -
 tools/kernel-doc/Makefile                | 10 -----
 12 files changed, 137 insertions(+), 77 deletions(-)
 create mode 100644 scripts/.gitignore
 rename {tools/kernel-doc => scripts}/docproc.c (90%)
 rename {tools/kernel-doc => scripts}/kernel-doc (97%)
 delete mode 100644 tools/kernel-doc/Makefile

-- 
1.8.3.2

[U-Boot] [PATCH v2 1/3] kernel-doc: move kernel-doc tools to scripts/

[Masahiro Yamada]

tools/kernel-doc/docproc.c and tools/kernel-doc/kernel-doc are
files imported from 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>
Acked-by: Simon Glass <sjg@chromium.org>
---

Changes in v2:
  - fix typos in commit log

 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 817f2a9..cb9c243 100644
--- a/Makefile
+++ b/Makefile
@@ -1151,9 +1151,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 ;
 
@@ -1261,6 +1258,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
-- 
1.8.3.2

[U-Boot] [PATCH v2 2/3] kernel-doc: update kernel-doc related files to Linux v3.13

[Masahiro Yamada]

Signed-off-by: Masahiro Yamada <yamada.m@jp.panasonic.com>
Acked-by: Simon Glass <sjg@chromium.org>
---

Changes in v2:
  - update also .gitignore

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

diff --git a/doc/DocBook/.gitignore b/doc/DocBook/.gitignore
index 90c1b11..720f245 100644
--- a/doc/DocBook/.gitignore
+++ b/doc/DocBook/.gitignore
@@ -1,4 +1,3 @@
-*/
 *.xml
 *.ps
 *.pdf
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@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";
-- 
1.8.3.2

[U-Boot] [PATCH v2 3/3] kernel-doc: fix some errors

[Masahiro Yamada]

  - 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>
Acked-by: Simon Glass <sjg@chromium.org>
---

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


Changes in v2: None

 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
-- 
1.8.3.2

[U-Boot] [U-Boot, v2, 1/3] kernel-doc: move kernel-doc tools to scripts/

[Tom Rini]

On Wed, Feb 05, 2014 at 10:52:50AM +0900, Masahiro Yamada wrote:

> tools/kernel-doc/docproc.c and tools/kernel-doc/kernel-doc are
> files imported from 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>
> Acked-by: Simon Glass <sjg@chromium.org>

Applied to u-boot/master, thanks!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/b06459c9/attachment.pgp>

[U-Boot] [U-Boot, v2, 2/3] kernel-doc: update kernel-doc related files to Linux v3.13

[Tom Rini]

On Wed, Feb 05, 2014 at 10:52:51AM +0900, Masahiro Yamada wrote:

> Signed-off-by: Masahiro Yamada <yamada.m@jp.panasonic.com>
> Acked-by: Simon Glass <sjg@chromium.org>

Applied to u-boot/master, thanks!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/63d0c0e6/attachment.pgp>

[U-Boot] [U-Boot,v2,3/3] kernel-doc: fix some errors

[Tom Rini]

On Wed, Feb 05, 2014 at 10:52:52AM +0900, Masahiro Yamada wrote:

> - 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>
> Acked-by: Simon Glass <sjg@chromium.org>

Applied to u-boot/master, thanks!

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: Digital signature
URL: <http://lists.denx.de/pipermail/u-boot/attachments/20140219/9eb8f9cc/attachment.pgp>