Commit 78a34380 authored by Sam Ravnborg's avatar Sam Ravnborg

docbook: Warn about missing parameter definitions

Previously kernel-doc silently ignored missing parameter descriptions
but sometimes 'make sgmldocs' failed with exit code > 0.
When kernel-doc encounter parameters where the description is missing
it now prints a warning.
docproc corrected so previously exit code are recorded.
docbook makefile cleaned up a bit
parent efaa7474
...@@ -39,8 +39,8 @@ htmldocs: $(HTML) ...@@ -39,8 +39,8 @@ htmldocs: $(HTML)
### ###
#External programs used #External programs used
KERNELDOC=$(objtree)/scripts/kernel-doc KERNELDOC = scripts/kernel-doc
DOCPROC=$(objtree)/scripts/docproc DOCPROC = scripts/docproc
### ###
# DOCPROC is used for two purposes: # DOCPROC is used for two purposes:
...@@ -50,10 +50,10 @@ DOCPROC=$(objtree)/scripts/docproc ...@@ -50,10 +50,10 @@ DOCPROC=$(objtree)/scripts/docproc
# The following rules are used to generate the .sgml documentation # The following rules are used to generate the .sgml documentation
# required to generate the final targets. (ps, pdf, html). # required to generate the final targets. (ps, pdf, html).
quiet_cmd_docproc = DOCPROC $@ quiet_cmd_docproc = DOCPROC $@
cmd_docproc = $(DOCPROC) doc $< >$@ cmd_docproc = $(DOCPROC) doc $< >$@
define rule_docproc define rule_docproc
set -e set -e; \
$(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
$(cmd_$(1)); \ $(cmd_$(1)); \
( \ ( \
echo 'cmd_$@ := $(cmd_$(1))'; \ echo 'cmd_$@ := $(cmd_$(1))'; \
...@@ -96,41 +96,55 @@ $(obj)/parportbook.ps $(obj)/parportbook.pdf: $(EPS-parportbook) $(PNG-parportbo ...@@ -96,41 +96,55 @@ $(obj)/parportbook.ps $(obj)/parportbook.pdf: $(EPS-parportbook) $(PNG-parportbo
### ###
# Rules to generate postscript, PDF and HTML # Rules to generate postscript, PDF and HTML
# db2html creates a directory. Generate a html file used for timestamp # db2html creates a directory. Generate a html file used for timestamp
quiet_cmd_db2ps = DB2PS $@
cmd_db2ps = db2ps -o $(dir $@) $<
%.ps : %.sgml %.ps : %.sgml
@(which db2ps > /dev/null 2>&1) || \ @(which db2ps > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \ (echo "*** You need to install DocBook stylesheets ***"; \
exit 1) exit 1)
$(call do_cmd,DB2PS $@,db2ps -o $(dir $@) $<) $(call cmd,db2ps)
quiet_cmd_db2pdf = DB2PDF $@
cmd_db2pdf = db2pdf -o $(dir $@) $<
%.pdf : %.sgml %.pdf : %.sgml
@(which db2pdf > /dev/null 2>&1) || \ @(which db2pdf > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \ (echo "*** You need to install DocBook stylesheets ***"; \
exit 1) exit 1)
$(call do_cmd,DB2PDF $@,db2pdf -o $(dir $@) $<) $(call cmd,db2pdf)
quiet_cmd_db2html = DB2HTML $@
cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
%.html: %.sgml %.html: %.sgml
@(which db2html > /dev/null 2>&1) || \ @(which db2html > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \ (echo "*** You need to install DocBook stylesheets ***"; \
exit 1) exit 1)
@rm -rf $@ $(patsubst %.html,%,$@) @rm -rf $@ $(patsubst %.html,%,$@)
$(call do_cmd,DB2HTML $@,db2html -o $(patsubst %.html,%,$@) $< && \ $(call cmd,db2html)
echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html">\
Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@)
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \ @if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
### ###
# Rules to generate postscripts and PNG imgages from .fig format files # Rules to generate postscripts and PNG imgages from .fig format files
quiet_cmd_fig2eps = FIG2EPS $@
cmd_fig2eps = fig2dev -Leps $< $@
%.eps: %.fig %.eps: %.fig
$(call do_cmd,FIG2DEV -Leps $@,fig2dev -Leps $< $@) $(call cmd,fig2eps)
quiet_cmd_fig2png = FIG2PNG $@
cmd_fig2png = fig2dev -Lpng $< $@
%.png: %.fig %.png: %.fig
$(call do_cmd,FIG2DEV -Lpng $@,fig2dev -Lpng $< $@) $(call cmd,fig2png)
### ###
# Rule to convert a .c file to inline SGML documentation # Rule to convert a .c file to inline SGML documentation
%.sgml: %.c %.sgml: %.c
@echo ' Generating $@' @echo ' GEN $@'
@( \ @( \
echo "<programlisting>"; \ echo "<programlisting>"; \
expand --tabs=8 < $< | \ expand --tabs=8 < $< | \
......
...@@ -93,7 +93,7 @@ void exec_kernel_doc(char **svec) ...@@ -93,7 +93,7 @@ void exec_kernel_doc(char **svec)
waitpid(pid, &ret ,0); waitpid(pid, &ret ,0);
} }
if (WIFEXITED(ret)) if (WIFEXITED(ret))
exitstatus = WEXITSTATUS(ret); exitstatus |= WEXITSTATUS(ret);
else else
exitstatus = 0xff; exitstatus = 0xff;
} }
......
...@@ -154,6 +154,7 @@ use strict; ...@@ -154,6 +154,7 @@ use strict;
# '%CONST' - name of a constant. # '%CONST' - name of a constant.
my $errors = 0; my $errors = 0;
my $warnings = 0;
# match expressions used to find embedded type information # match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)'; my $type_constant = '\%([-_\w]+)';
...@@ -1352,7 +1353,9 @@ sub create_parameterlist($$$) { ...@@ -1352,7 +1353,9 @@ sub create_parameterlist($$$) {
"or member '$param' not " . "or member '$param' not " .
"described in '$declaration_name'\n"; "described in '$declaration_name'\n";
} }
++$errors; print STDERR "Warning(${file}:$.):".
" No description found for parameter '$param'\n";
++$warnings;
} }
push @parameterlist, $param; push @parameterlist, $param;
...@@ -1456,6 +1459,12 @@ foreach (@ARGV) { ...@@ -1456,6 +1459,12 @@ foreach (@ARGV) {
chomp; chomp;
process_file($_); process_file($_);
} }
if ($verbose && $errors) {
print STDERR "$errors errors\n";
}
if ($verbose && $warnings) {
print STDERR "$warnings warnings\n";
}
exit($errors); exit($errors);
...@@ -1580,7 +1589,7 @@ sub process_file($) { ...@@ -1580,7 +1589,7 @@ sub process_file($) {
} else { } else {
print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.", print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
" - I thought it was a doc line\n"; " - I thought it was a doc line\n";
++$errors; ++$warnings;
$state = 0; $state = 0;
} }
} elsif ($state == 2) { # look for head: lines, and include content } elsif ($state == 2) { # look for head: lines, and include content
...@@ -1633,7 +1642,7 @@ sub process_file($) { ...@@ -1633,7 +1642,7 @@ sub process_file($) {
} else { } else {
# i dont know - bad line? ignore. # i dont know - bad line? ignore.
print STDERR "Warning(${file}:$.): bad line: $_"; print STDERR "Warning(${file}:$.): bad line: $_";
++$errors; ++$warnings;
} }
} elsif ($state == 3) { # scanning for function { (end of prototype) } elsif ($state == 3) { # scanning for function { (end of prototype)
if ($decl_type eq 'function') { if ($decl_type eq 'function') {
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment