From b52735336857be24206e062b0a00501b1f0c597d Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Tue, 25 Sep 2018 13:06:57 +0200 Subject: manpage generation: cleanup Recognize parameters of the form unsigned char name[8], and do not print obscure warnings. Furthermore gdoc will fail when a function parameter is not described or when no function is found. This addresses the generation of undetected errors in generated manpages. Signed-off-by: Nikos Mavrogiannopoulos --- .gitlab-ci.yml | 2 +- doc/Makefile.am | 26 +++++++++++++------------- doc/doc.mk | 2 +- doc/manpages/Makefile.am | 34 +++++++++++++++++----------------- doc/scripts/gdoc | 22 +++++++++++++++++----- 5 files changed, 49 insertions(+), 37 deletions(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 5c8a297ead..561fcbf349 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -43,7 +43,7 @@ doc-dist.Fedora: script: - SUBMODULE_NOFETCH=1 ./bootstrap - CFLAGS="-std=c99 -O2 -g" dash ./configure --disable-gcc-warnings --cache-file cache/config.cache --prefix=/usr --libdir=/usr/lib64 --disable-cxx --disable-non-suiteb-curves --enable-gtk-doc --disable-maintainer-mode - - make -C doc stamp-vti && make -C doc stamp-1 && make -j$(nproc) + - make -C doc stamp-vti && make -C doc stamp-1 && make -C doc stamp_enums && make -j$(nproc) - make -C doc gnutls.html - PATH="$PATH:/usr/share/sgml/docbook/xsl-stylesheets-1.79.1/epub/bin/" make -C doc gnutls.epub && make -C doc/latex gnutls.pdf diff --git a/doc/Makefile.am b/doc/Makefile.am index 782b3cf55f..1e72f63adb 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -225,7 +225,7 @@ gnutls-api.texi: $(top_srcdir)/lib/includes/gnutls/gnutls.h.in echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -236,7 +236,7 @@ socket-api.texi: $(top_srcdir)/lib/includes/gnutls/socket.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -247,7 +247,7 @@ dane-api.texi: $(top_srcdir)/libdane/includes/gnutls/dane.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -259,7 +259,7 @@ x509-api.texi: $(top_srcdir)/lib/includes/gnutls/x509.h $(top_srcdir)/lib/includ echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done rm -f $@-tmp2 @@ -271,7 +271,7 @@ pkcs12-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs12.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_X509_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_X509_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -282,7 +282,7 @@ pkcs11-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs11.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -293,7 +293,7 @@ pkcs7-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs7.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_X509_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_X509_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -304,7 +304,7 @@ tpm-api.texi: $(top_srcdir)/lib/includes/gnutls/tpm.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -316,7 +316,7 @@ abstract-api.texi: $(top_srcdir)/lib/includes/gnutls/abstract.h $(top_srcdir)/li echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done rm -f $@-headers-tmp @@ -328,7 +328,7 @@ compat-api.texi: $(top_srcdir)/lib/includes/gnutls/compat.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -339,7 +339,7 @@ dtls-api.texi: $(top_srcdir)/lib/includes/gnutls/dtls.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -350,7 +350,7 @@ crypto-api.texi: $(top_srcdir)/lib/includes/gnutls/crypto.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ @@ -361,7 +361,7 @@ ocsp-api.texi: $(top_srcdir)/lib/includes/gnutls/ocsp.h echo $(ECHO_N) "Creating documentation for $$i... " && \ $(srcdir)/scripts/gdoc -texinfo \ -function $$i \ - $(C_X509_SOURCE_FILES) >> $@-tmp 2>/dev/null && \ + $(C_X509_SOURCE_FILES) >> $@-tmp && \ echo "ok"; \ done mv -f $@-tmp $@ diff --git a/doc/doc.mk b/doc/doc.mk index 89a643c6c6..21636f6951 100644 --- a/doc/doc.mk +++ b/doc/doc.mk @@ -29,4 +29,4 @@ HEADER_FILES = $(top_srcdir)/lib/includes/gnutls/gnutls.h.in \ $(top_srcdir)/lib/includes/gnutls/pkcs7.h $(top_srcdir)/lib/includes/gnutls/socket.h C_SOURCE_FILES = $(top_srcdir)/lib/*/*.c $(top_srcdir)/lib/*.c $(top_srcdir)/libdane/*.c -C_X509_SOURCE_FILES = $(top_srcdir)/lib/x509/*.c $(top_srcdir)/lib/*.c $(top_srcdir)/lib/system/cert.c +C_X509_SOURCE_FILES = $(top_srcdir)/lib/x509/*.c $(top_srcdir)/lib/*.c $(top_srcdir)/lib/system/certs.c diff --git a/doc/manpages/Makefile.am b/doc/manpages/Makefile.am index 241d9870af..76a73ae057 100644 --- a/doc/manpages/Makefile.am +++ b/doc/manpages/Makefile.am @@ -1235,7 +1235,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1249,7 +1249,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1263,7 +1263,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1277,7 +1277,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1291,7 +1291,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_X509_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_X509_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1305,7 +1305,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_X509_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_X509_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1319,7 +1319,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_X509_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_X509_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1333,7 +1333,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_X509_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_X509_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1347,7 +1347,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1361,7 +1361,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_X509_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_X509_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1375,7 +1375,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1389,7 +1389,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1403,7 +1403,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1417,7 +1417,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1431,7 +1431,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2001-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1445,7 +1445,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2014-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" @@ -1459,7 +1459,7 @@ stamp_mans: $(HEADER_FILES) -seeinfo $(PACKAGE) -verbatimcopying \ -copyright "2014-$(YEAR) Free Software Foundation, Inc., and others" \ -function $$i \ - $(C_SOURCE_FILES) > $$i.3 2>/dev/null && \ + $(C_SOURCE_FILES) > $$i.3 && \ echo $(ECHO_N) "."; \ done @echo "" diff --git a/doc/scripts/gdoc b/doc/scripts/gdoc index 224b83e22a..25aa1beebb 100755 --- a/doc/scripts/gdoc +++ b/doc/scripts/gdoc @@ -196,6 +196,8 @@ $blankline_man = ""; $blankline_text = ""; my $lineprefix = ""; +my $function_found = 0; + sub usage { print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex | -texinfo -listfunc ]\n"; print " [ -sourceversion verno ] [ -include file | -includefuncprefix ]\n"; @@ -797,6 +799,10 @@ sub dump_function { $function_name = $2; $args = $3; + if ($return_type eq 'typedef') { + return; + } + # print STDERR "ARGS = '$args'\n"; foreach $arg (split ',', $args) { @@ -813,7 +819,7 @@ sub dump_function { $param = $2; push @args, $1; } - if ($param =~ m/^(.*)(\[\])$/) { + if ($param =~ m/^(.*)(\[[0-9]*\])$/) { $param = $1; push @args, $2; } @@ -822,7 +828,8 @@ sub dump_function { if ((!defined($parameters{$param}) || $parameters{$param} eq "") && $param ne "void") { $parameters{$param} = "-- undescribed --"; - print STDERR "warning: $lineno: Function parameter '$param' not described in '$function_name'\n"; + print STDERR "error: $lineno: Function parameter '$param' not described in '$function_name'\n"; + exit 1; } push @parameterlist, $param; @@ -831,11 +838,12 @@ sub dump_function { # print STDERR "param = '$param', type = '$type'\n"; } } else { - print STDERR "warning: $lineno: Cannot understand prototype: '$prototype'\n"; - return; + print STDERR "error: $lineno: Cannot understand prototype: '$prototype'\n"; + exit 1; } if ($function_only==0 || defined($function_table{$function_name})) { + $function_found=1; output_function({'function' => $function_name, 'module' => $modulename, 'sourceversion' => $sourceversion, @@ -1008,7 +1016,7 @@ foreach $file (@ARGV) { } } else { # i dont know - bad line? ignore. - print STDERR "warning: $lineno: Bad line: $_"; + #print STDERR "warning: $lineno: Bad line: $_"; } } elsif ($state == 3) { # scanning for function { (end of prototype) if ($line =~ /([a-zA-Z\s]+)enum(.*)$/) { @@ -1066,5 +1074,9 @@ foreach $file (@ARGV) { } } +} +if ($function_only != 0 && $function_found == 0) { + print STDERR "error: could not find the expected function\n"; + exit 1; } -- cgit v1.2.1