diff -Nru gtk-doc-1.20/configure gtk-doc-1.21/configure --- gtk-doc-1.20/configure 2014-02-15 21:44:58.000000000 +0000 +++ gtk-doc-1.21/configure 2014-07-17 18:29:25.000000000 +0000 @@ -1,6 +1,6 @@ #! /bin/sh # Guess values for system-dependent variables and create Makefiles. -# Generated by GNU Autoconf 2.68 for gtk-doc 1.20. +# Generated by GNU Autoconf 2.68 for gtk-doc 1.21. # # Report bugs to . # @@ -571,8 +571,8 @@ # Identity of this package. PACKAGE_NAME='gtk-doc' PACKAGE_TARNAME='gtk-doc' -PACKAGE_VERSION='1.20' -PACKAGE_STRING='gtk-doc 1.20' +PACKAGE_VERSION='1.21' +PACKAGE_STRING='gtk-doc 1.21' PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc' PACKAGE_URL='' @@ -1351,7 +1351,7 @@ # Omit some internal or obsolete options to make the list less imposing. # This message is too long to be a string in the A/UX 3.1 sh. cat <<_ACEOF -\`configure' configures gtk-doc 1.20 to adapt to many kinds of systems. +\`configure' configures gtk-doc 1.21 to adapt to many kinds of systems. Usage: $0 [OPTION]... [VAR=VALUE]... @@ -1421,7 +1421,7 @@ if test -n "$ac_init_help"; then case $ac_init_help in - short | recursive ) echo "Configuration of gtk-doc 1.20:";; + short | recursive ) echo "Configuration of gtk-doc 1.21:";; esac cat <<\_ACEOF @@ -1544,7 +1544,7 @@ test -n "$ac_init_help" && exit $ac_status if $ac_init_version; then cat <<\_ACEOF -gtk-doc configure 1.20 +gtk-doc configure 1.21 generated by GNU Autoconf 2.68 Copyright (C) 2010 Free Software Foundation, Inc. @@ -1822,7 +1822,7 @@ This file contains any messages produced by compilers while running configure, to aid debugging if configure makes a mistake. -It was created by gtk-doc $as_me 1.20, which was +It was created by gtk-doc $as_me 1.21, which was generated by GNU Autoconf 2.68. Invocation command line was $ $0 $@ @@ -2641,7 +2641,7 @@ # Define the identity of the package. PACKAGE='gtk-doc' - VERSION='1.20' + VERSION='1.21' cat >>confdefs.h <<_ACEOF @@ -12542,8 +12542,8 @@ { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether date can output nanoseconds" >&5 $as_echo_n "checking whether date can output nanoseconds... " >&6; } -date +%s.%N | grep -q '%N' -if test "$?" == "1"; then +date +%s.%N | grep -q 'N' +if test "$?" = "1"; then TS_FMT="+%s.%N" ELAPSED_FMT="+%H:%M:%S.%N" { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5 @@ -12560,7 +12560,7 @@ { $as_echo "$as_me:${as_lineno-$LINENO}: checking whether date can format dates" >&5 $as_echo_n "checking whether date can format dates... " >&6; } date >/dev/null 2>&1 --utc --date @1.1 $ELAPSED_FMT -if test "$?" == "0"; then +if test "$?" = "0"; then DATE_FMT_CMD="date --utc $ELAPSED_FMT --date @0" { $as_echo "$as_me:${as_lineno-$LINENO}: result: yes" >&5 $as_echo "yes" >&6; } @@ -12886,8 +12886,6 @@ ac_config_files="$ac_config_files gtkdoc-scangobj" -ac_config_files="$ac_config_files gtkdoc-scanobj" - ac_config_files="$ac_config_files gtkdocize" ac_config_files="$ac_config_files tests/tools.sh" @@ -13482,7 +13480,7 @@ # report actual input values of CONFIG_FILES etc. instead of their # values after options handling. ac_log=" -This file was extended by gtk-doc $as_me 1.20, which was +This file was extended by gtk-doc $as_me 1.21, which was generated by GNU Autoconf 2.68. Invocation command line was CONFIG_FILES = $CONFIG_FILES @@ -13539,7 +13537,7 @@ cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1 ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`" ac_cs_version="\\ -gtk-doc config.status 1.20 +gtk-doc config.status 1.21 configured by $0, generated by GNU Autoconf 2.68, with options \\"\$ac_cs_config\\" @@ -13972,7 +13970,6 @@ "gtkdoc-rebase") CONFIG_FILES="$CONFIG_FILES gtkdoc-rebase" ;; "gtkdoc-scan") CONFIG_FILES="$CONFIG_FILES gtkdoc-scan" ;; "gtkdoc-scangobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scangobj" ;; - "gtkdoc-scanobj") CONFIG_FILES="$CONFIG_FILES gtkdoc-scanobj" ;; "gtkdocize") CONFIG_FILES="$CONFIG_FILES gtkdocize" ;; "tests/tools.sh") CONFIG_FILES="$CONFIG_FILES tests/tools.sh" ;; @@ -15140,7 +15137,6 @@ "gtkdoc-rebase":F) chmod +x gtkdoc-rebase ;; "gtkdoc-scan":F) chmod +x gtkdoc-scan ;; "gtkdoc-scangobj":F) chmod +x gtkdoc-scangobj ;; - "gtkdoc-scanobj":F) chmod +x gtkdoc-scanobj ;; "gtkdocize":F) chmod +x gtkdocize ;; "tests/tools.sh":F) chmod +x tests/tools.sh ;; diff -Nru gtk-doc-1.20/configure.ac gtk-doc-1.21/configure.ac --- gtk-doc-1.20/configure.ac 2014-02-15 21:42:55.000000000 +0000 +++ gtk-doc-1.21/configure.ac 2014-07-17 18:27:30.000000000 +0000 @@ -5,7 +5,7 @@ dnl Makefile can only cope with that, i.e. use 1.1, 1.2, 1.3 ... 9.9. dnl FIXME: I can't see anything failing (1.14.1), lets try to use a three digit dnl number for the development version -m4_define(gtk_doc_version, 1.20) +m4_define(gtk_doc_version, 1.21) AC_INIT([gtk-doc],[gtk_doc_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=gtk-doc],[gtk-doc]) @@ -210,9 +210,11 @@ AC_SUBST(TRACE) dnl check what date format we can use for the makefile tracing in tests +dnl this is mostly to detect the date command on macosx that is quite cripled +dnl and broken too AC_MSG_CHECKING(whether date can output nanoseconds) -date +%s.%N | grep -q '%N' -if test "$?" == "1"; then +date +%s.%N | grep -q 'N' +if test "$?" = "1"; then TS_FMT="+%s.%N" ELAPSED_FMT="+%H:%M:%S.%N" AC_MSG_RESULT(yes) @@ -226,7 +228,7 @@ AC_MSG_CHECKING(whether date can format dates) date >/dev/null 2>&1 --utc --date @1.1 $ELAPSED_FMT -if test "$?" == "0"; then +if test "$?" = "0"; then DATE_FMT_CMD="date --utc $ELAPSED_FMT --date @0" AC_MSG_RESULT(yes) else @@ -291,7 +293,6 @@ AC_CONFIG_FILES([gtkdoc-rebase], [chmod +x gtkdoc-rebase]) AC_CONFIG_FILES([gtkdoc-scan], [chmod +x gtkdoc-scan]) AC_CONFIG_FILES([gtkdoc-scangobj], [chmod +x gtkdoc-scangobj]) -AC_CONFIG_FILES([gtkdoc-scanobj], [chmod +x gtkdoc-scanobj]) AC_CONFIG_FILES([gtkdocize], [chmod +x gtkdocize]) AC_CONFIG_FILES([tests/tools.sh], [chmod +x tests/tools.sh]) AC_OUTPUT diff -Nru gtk-doc-1.20/debian/changelog gtk-doc-1.21/debian/changelog --- gtk-doc-1.20/debian/changelog 2014-02-19 10:06:19.000000000 +0000 +++ gtk-doc-1.21/debian/changelog 2014-08-05 02:02:24.000000000 +0000 @@ -1,3 +1,21 @@ +gtk-doc (1.21-1ubuntu1) utopic; urgency=medium + + * Merge from debian. Remaining changes: + - debian/control.in: Drop optional highlight dependency, which is in + universe. + + -- Jackson Doak Sun, 03 Aug 2014 06:25:50 +1000 + +gtk-doc (1.21-1) unstable; urgency=medium + + * Team upload. + + [ Jackson Doak ] + * New upstream release + * debian/control: Bump standards-version to 3.9.5 (no changes) + + -- Andreas Henriksson Thu, 31 Jul 2014 20:42:18 +0200 + gtk-doc (1.20-1ubuntu1) trusty; urgency=medium * Merge from debian. Remaining changes: diff -Nru gtk-doc-1.20/debian/control gtk-doc-1.21/debian/control --- gtk-doc-1.20/debian/control 2014-02-19 10:06:22.000000000 +0000 +++ gtk-doc-1.21/debian/control 2014-08-05 02:09:58.000000000 +0000 @@ -7,8 +7,8 @@ Priority: optional Maintainer: Ubuntu Developers XSBC-Original-Maintainer: Debian GNOME Maintainers -Uploaders: Debian GNOME Maintainers , Emilio Pozuelo Monfort , Jeremy Bicha , Martin Pitt , Michael Biebl -Standards-Version: 3.9.4 +Uploaders: Andreas Henriksson , Debian GNOME Maintainers , Emilio Pozuelo Monfort , Jeremy Bicha , Michael Biebl +Standards-Version: 3.9.5 Build-Depends: cdbs, debhelper (>= 8), gnome-pkg-tools (>= 0.10), diff -Nru gtk-doc-1.20/debian/control.in gtk-doc-1.21/debian/control.in --- gtk-doc-1.20/debian/control.in 2014-02-19 10:05:19.000000000 +0000 +++ gtk-doc-1.21/debian/control.in 2014-08-05 02:02:24.000000000 +0000 @@ -4,7 +4,7 @@ Maintainer: Ubuntu Developers XSBC-Original-Maintainer: Debian GNOME Maintainers Uploaders: @GNOME_TEAM@ -Standards-Version: 3.9.4 +Standards-Version: 3.9.5 Build-Depends: cdbs, debhelper (>= 8), gnome-pkg-tools (>= 0.10), diff -Nru gtk-doc-1.20/gtkdoc-fixxref.in gtk-doc-1.21/gtkdoc-fixxref.in --- gtk-doc-1.20/gtkdoc-fixxref.in 2013-08-23 07:04:38.000000000 +0000 +++ gtk-doc-1.21/gtkdoc-fixxref.in 2014-02-17 19:17:45.000000000 +0000 @@ -74,8 +74,6 @@ # This contains all the entities and their relative URLs. my %Links; -# This hold the path entries we already scanned -my @VisitedPaths; # failing link targets we don't warn about even once my %NoLinks = ( @@ -114,12 +112,19 @@ $dir = $dir . "/share/gtk-doc/html"; if (-d $dir && $dir ne $HTML_DIR) { @TRACE@("Scanning GLib directory: $dir"); + + # Some predefined link targets to get links into type hierarchies as these + # have no targets. These are always absolute for now. + $Links{'GBoxed'} = "$dir/gobject/gobject-Boxed-Types.html"; + $Links{'GEnum'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html"; + $Links{'GFlags'} = "$dir/gobject/gobject-Enumeration-and-Flag-Types.html"; + $Links{'GInterface'} = "$dir/gobject/GTypeModule.html"; + if ($dir !~ m%^\Q$path_prefix\E/%) { &ScanIndices ($dir, 1); } else { &ScanIndices ($dir, 0); } - push (@VisitedPaths, $dir); } if (defined ($ENV{"GNOME2_PATH"})) { @@ -132,7 +137,6 @@ } else { &ScanIndices ($dir, 0); } - push (@VisitedPaths, $dir); } # ubuntu started to compress this as index.sgml.gz :/ # https://bugs.launchpad.net/ubuntu/+source/gtk-doc/+bug/77138 @@ -141,25 +145,13 @@ @TRACE@("Scanning HTML_DIR directory: $HTML_DIR"); &ScanIndices ($HTML_DIR, 0); -push (@VisitedPaths, $HTML_DIR); @TRACE@("Scanning HTML_DIR directory: $MODULE_DIR"); &ScanIndices ($MODULE_DIR, 0); -push (@VisitedPaths, $MODULE_DIR); # check all extra dirs, but skip already scanned dirs or subdirs of those foreach my $dir (@EXTRA_DIRS) { my $vdir; - my $skip = 0; - - foreach $vdir (@VisitedPaths) { - if ($dir eq $vdir || $dir =~ m%^\Q$vdir\E/%) { - @TRACE@("Skipping EXTRA_DIR directory: $dir"); - $skip=1; - } - } - next if $skip; @TRACE@("Scanning EXTRA_DIR directory: $dir"); - push (@VisitedPaths, $dir); # If the --extra-dir option is not relative and is not sharing the same # prefix as the target directory of the docs, we need to use absolute @@ -208,7 +200,7 @@ sub ScanIndices { my ($scan_dir, $use_absolute_links) = @_; - + @TRACE@("Scanning source directory: $scan_dir absolute: $use_absolute_links"); # This array holds any subdirectories found. @@ -231,7 +223,7 @@ # Now recursively scan the subdirectories. my $dir; - foreach $dir (@subdirs) { + foreach $dir (sort(@subdirs)) { &ScanIndices ("$scan_dir/$dir", $use_absolute_links); } } diff -Nru gtk-doc-1.20/gtkdoc-mkdb.in gtk-doc-1.21/gtkdoc-mkdb.in --- gtk-doc-1.20/gtkdoc-mkdb.in 2014-02-15 21:03:18.000000000 +0000 +++ gtk-doc-1.21/gtkdoc-mkdb.in 2014-07-10 05:29:11.000000000 +0000 @@ -138,7 +138,7 @@ $OUTPUT_FORMAT = lc($OUTPUT_FORMAT); } -#print "DEBUG: output-format: [$OUTPUT_FORMAT]\n"; +@TRACE@(" output-format: [$OUTPUT_FORMAT]\n"); if ($OUTPUT_FORMAT eq "xml") { if (!$MAIN_SGML_FILE) { @@ -300,10 +300,12 @@ # remember used annotation (to write minimal glossary) my %AnnotationsUsed; -# the annotations are defined at: -# https://live.gnome.org/GObjectIntrospection/Annotations my %AnnotationDefinition = ( - 'allow-none' => "NULL is ok, both for passing and for returning.", + # the GObjectIntrospection annotations are defined at: + # https://live.gnome.org/GObjectIntrospection/Annotations + 'allow-none' => "NULL is OK, both for passing and for returning.", + 'nullable' => "NULL may be passed as the value in, out, in-out; or as a return value.", + 'optional' => "NULL may be passed instead of a pointer to a location.", 'array' => "Parameter points to an array of items.", 'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.", 'attributes' => "Free-form key-value pairs.", @@ -337,7 +339,37 @@ 'type' => "Override the parsed C type with given type.", 'unref-func' => "The specified function is used to unref a struct, must be a GTypeInstance.", 'virtual' => "This is the invoker for a virtual method.", - 'value' => "The specified value overrides the evaluated value of the constant." + 'value' => "The specified value overrides the evaluated value of the constant.", + # Stability Level definition + # https://bugzilla.gnome.org/show_bug.cgi?id=170860 + 'Stable' => < < <(.*)<\/TITLE>/) { $title = $1; - #print "Section: $title\n"; + @TRACE@("Section: $title\n"); # We don't want warnings if object & class structs aren't used. $DeclarationOutput{$title} = 1; @@ -660,7 +692,7 @@ } } elsif (m/^<\/SECTION>/) { - #print "End of section: $title\n"; + @TRACE@("End of section: $title\n"); if ($num_symbols > 0) { # collect documents if ($OUTPUT_FORMAT eq "xml") { @@ -788,12 +820,13 @@ EOF } - $hierarchy_str = &AddTreeLineArt(\@hierarchy) . "\n"; + $hierarchy_str = &AddTreeLineArt(\@hierarchy); if ($hierarchy_str ne "") { $hierarchy_str = < Object Hierarchy -$hierarchy_str +$hierarchy_str + EOF } @@ -1056,7 +1089,7 @@ print (OUTPUT "$header\n"); - #print "generate $basename index (".%apiindex." entries)\n"; + @TRACE@("generate $basename index (".%apiindex." entries)\n"); # do a case insensitive sort while chopping off the prefix foreach my $hash ( @@ -1080,12 +1113,12 @@ $symbol_type = lc($DeclarationTypes{$symbol}); } if ($symbol_type eq "") { - #print "trying symbol $symbol\n"; + @TRACE@("trying symbol $symbol\n"); if ($symbol =~ m/(.*)::(.*)/) { my $oname = $1; my $osym = $2; my $i; - #print " trying object signal ${oname}:$osym in ".$#SignalNames." signals\n"; + @TRACE@(" trying object signal ${oname}:$osym in ".$#SignalNames." signals\n"); for ($i = 0; $i <= $#SignalNames; $i++) { if ($SignalNames[$i] eq $osym) { $symbol_type = "object signal"; @@ -1100,9 +1133,9 @@ my $oname = $1; my $osym = $2; my $i; - #print " trying object property ${oname}::$osym in ".$#ArgNames." properties\n"; + @TRACE@(" trying object property ${oname}::$osym in ".$#ArgNames." properties\n"); for ($i = 0; $i <= $#ArgNames; $i++) { - #print " ".$ArgNames[$i]."\n"; + @TRACE@(" ".$ArgNames[$i]."\n"); if ($ArgNames[$i] eq $osym) { $symbol_type = "object property"; if (defined($SymbolSection{$oname})) { @@ -1130,7 +1163,7 @@ my $curletter = uc(substr($short_symbol,0,1)); my $id = $apiindex{$symbol}; - #print " add symbol $symbol with $id to index in section $curletter\n"; + @TRACE@(" add symbol $symbol with $id to index in section $curletter\n"); if ($curletter ne $lastletter) { $lastletter = $curletter; @@ -1189,7 +1222,7 @@ my @sinces = keys %{{ map { $_ => 1 } values %Since }}; foreach my $version (@sinces) { - #print "Since : [$version]\n"; + @TRACE@("Since : [$version]\n"); # TODO make filtered hash #my %index = grep { $Since{$_} eq $version } %IndexEntriesSince; my %index = map { $_ => $IndexEntriesSince{$_} } grep { $Since{$_} eq $version } keys %IndexEntriesSince; @@ -1239,7 +1272,7 @@ Annotation Glossary EOF - foreach my $annotation (sort(keys(%AnnotationsUsed))) { + foreach my $annotation (sort({lc $a cmp lc $b} keys(%AnnotationsUsed))) { if(defined($AnnotationDefinition{$annotation})) { my $def = $AnnotationDefinition{$annotation}; my $curletter = uc(substr($annotation,0,1)); @@ -1287,7 +1320,7 @@ my $subsection = ""; - #print "Reading: $file\n"; + @TRACE@("Reading: $file\n"); open (INPUT, $file) || die "Can't open $file: $!"; @@ -1381,7 +1414,9 @@ $desc .= "Since $Since{$symbol}"; } if (exists $StabilityLevel{$symbol}) { - $desc .= "Stability Level: $StabilityLevel{$symbol}"; + my $stability = $StabilityLevel{$symbol}; + $AnnotationsUsed{$stability} = 1; + $desc .= "Stability Level: $stability"; } return $desc; } @@ -1490,23 +1525,13 @@ $desc .= &MakeDeprecationNote($symbol); my $parameters = &OutputParamDescriptions ("MACRO", $symbol, @fields); - my $parameters_output = 0; if (defined ($SymbolDocs{$symbol})) { my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - - # Try to insert the parameter table at the author's desired position. - # Otherwise we need to tag it onto the end. - if ($symbol_docs =~ s//$parameters/) { - $parameters_output = 1; - } $desc .= $symbol_docs; } - if ($parameters_output == 0) { - $desc .= $parameters; - } - + $desc .= $parameters; $desc .= OutputSymbolTraits ($symbol); $desc .= "\n"; return ($synop, $desc); @@ -1565,7 +1590,7 @@ my $is_gtype = 0; my $default_to_public = 1; if (&CheckIsObject ($symbol)) { - #print "Found struct gtype: $symbol\n"; + @TRACE@("Found struct gtype: $symbol\n"); $is_gtype = 1; $default_to_public = $ObjectRoots{$symbol} eq 'GBoxed'; } @@ -1606,10 +1631,10 @@ my $decl_out = ""; if ($declaration =~ m/^\s*$/) { - #print "Found opaque struct: $symbol\n"; + @TRACE@("Found opaque struct: $symbol\n"); $decl_out = "typedef struct _$symbol $symbol;"; } elsif ($declaration =~ m/^\s*struct\s+\w+\s*;\s*$/) { - #print "Found opaque struct: $symbol\n"; + @TRACE@("Found opaque struct: $symbol\n"); $decl_out = "struct $symbol;"; } else { my $public = $default_to_public; @@ -1621,7 +1646,7 @@ my $struct_contents = $2; foreach $decl_line (split (/\n/, $struct_contents)) { - #print "Struct line: $decl_line\n"; + @TRACE@("Struct line: $decl_line\n"); if ($decl_line =~ m%/\*\s*<\s*public\s*>\s*\*/%) { $public = 1; } elsif ($decl_line =~ m%/\*\s*<\s*(private|protected)\s*>\s*\*/%) { @@ -1942,7 +1967,7 @@ my $is_gtype = 0; if (&CheckIsObject ($symbol)) { - #print "Found enum gtype: $symbol\n"; + @TRACE@("Found enum gtype: $symbol\n"); $is_gtype = 1; } @@ -2199,25 +2224,13 @@ $desc .= &MakeDeprecationNote($symbol); my $parameters = &OutputParamDescriptions ("FUNCTION", $symbol, @fields); - my $parameters_output = 0; if (defined ($SymbolDocs{$symbol})) { my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - - # Try to insert the parameter table at the author's desired position. - # Otherwise we need to tag it onto the end. - # FIXME: document that in the user manual and make it useable for other - # types too - if ($symbol_docs =~ s//$parameters/) { - $parameters_output = 1; - } $desc .= $symbol_docs; } - if ($parameters_output == 0) { - $desc .= $parameters; - } - + $desc .= $parameters; $desc .= OutputSymbolTraits ($symbol); $desc .= "\n"; return ($synop, $desc); @@ -2268,7 +2281,8 @@ if ($param_name eq "Returns") { $returns = "$param_desc\n$param_annotations"; } elsif ($param_name eq "void") { - #print "!!!! void in params for $symbol?\n"; + # FIXME: &LogWarning()? + @TRACE@("!!!! void in params for $symbol?\n"); } else { if (@fields) { if (!defined $field_descrs{$param_name}) { @@ -2404,13 +2418,13 @@ sub OutputSGMLFile { my ($file, $title, $section_id, $includes, $functions_synop, $other_synop, $functions_details, $other_details, $signals_synop, $signals_desc, $args_synop, $args_desc, $hierarchy, $interfaces, $implementations, $prerequisites, $derived, $file_objects) = @_; - #print "Output sgml for file $file with title '$title'\n"; + @TRACE@("Output sgml for file $file with title '$title'\n"); # The edited title overrides the one from the sections file. my $new_title = $SymbolDocs{"$TMPL_DIR/$file:Title"}; if (defined ($new_title) && $new_title !~ m/^\s*$/) { $title = $new_title; - #print "Found title: $title\n"; + @TRACE@("Found title: $title\n"); } my $short_desc = $SymbolDocs{"$TMPL_DIR/$file:Short_Description"}; if (!defined ($short_desc) || $short_desc =~ m/^\s*$/) { @@ -2419,7 +2433,7 @@ # Don't use ConvertMarkDown here for now since we don't want blocks $short_desc = &ExpandAbbreviations("$title:Short_description", $short_desc); - #print "Found short_desc: $short_desc"; + @TRACE@("Found short_desc: $short_desc"); } my $long_desc = $SymbolDocs{"$TMPL_DIR/$file:Long_Description"}; if (!defined ($long_desc) || $long_desc =~ m/^\s*$/) { @@ -2427,14 +2441,14 @@ } else { $long_desc = &ConvertMarkDown("$title:Long_description", $long_desc); - #print "Found long_desc: $long_desc"; + @TRACE@("Found long_desc: $long_desc"); } my $see_also = $SymbolDocs{"$TMPL_DIR/$file:See_Also"}; if (!defined ($see_also) || $see_also =~ m%^\s*()?\s*()?\s*$%) { $see_also = ""; } else { $see_also = &ConvertMarkDown("$title:See_Also", $see_also); - #print "Found see_also: $see_also"; + @TRACE@("Found see_also: $see_also"); } if ($see_also) { $see_also = "\nSee Also\n$see_also\n\n"; @@ -2444,12 +2458,14 @@ $stability = ""; } else { $stability = &ParseStabilityLevel($stability, $file, $., "Section stability level"); - #print "Found stability: $stability"; + @TRACE@("Found stability: $stability"); } if ($stability) { - $stability = "\nStability Level\n$stability, unless otherwise indicated\n\n"; + $AnnotationsUsed{$stability} = 1; + $stability = "\nStability Level\n$stability, unless otherwise indicated\n\n"; } elsif ($DEFAULT_STABILITY) { - $stability = "\nStability Level\n$DEFAULT_STABILITY, unless otherwise indicated\n\n"; + $AnnotationsUsed{$DEFAULT_STABILITY} = 1; + $stability = "\nStability Level\n$DEFAULT_STABILITY, unless otherwise indicated\n\n"; } my $image = $SymbolDocs{"$TMPL_DIR/$file:Image"}; @@ -2507,7 +2523,7 @@ foreach my $object (@$file_objects) { next if ($object eq $section_id); my $id = CreateValidSGMLID($object); - #print "Debug: Adding anchor for $object\n"; + @TRACE@("Adding anchor for $object\n"); $object_anchors .= "/>/g; + # Allow ">" at beginning of string for blockquote markdown + $text =~ s/(?<=[^\w\n"'\/-])>/>/g; + return $text; } } @@ -3075,7 +3095,7 @@ return "$text"; } - #print "Getting type link for $symbol -> $text\n"; + @TRACE@("Getting type link for $symbol -> $text\n"); my $symbol_id = &CreateValidSGMLID ($symbol); return "$text"; @@ -3201,7 +3221,7 @@ my $cond = $desc; $cond =~ s/\"/"/g; $desc=" condition=\"".$cond."\""; - #print "condition for '$symbol' = '$desc'\n"; + @TRACE@("condition for '$symbol' = '$desc'\n"); } return $desc; } @@ -3248,13 +3268,13 @@ # Walk up the hierarchy, pushing ancestors onto the ancestors array. my @ancestors = (); push (@ancestors, $object); - #print "Level: $level\n"; + @TRACE@("Level: $level\n"); while ($level > 1) { $j--; if ($ObjectLevels[$j] < $level) { push (@ancestors, $Objects[$j]); $level = $ObjectLevels[$j]; - #print "Level: $level\n"; + @TRACE@("Level: $level\n"); } } @@ -3505,7 +3525,7 @@ my $i; for ($i = 0; $i <= $#SignalObjects; $i++) { if ($SignalObjects[$i] eq $object) { - #print "Found signal: $SignalNames[$i]\n"; + @TRACE@("Found signal: $SignalNames[$i]\n"); my $name = $SignalNames[$i]; my $symbol = "${object}::${name}"; my $id = &CreateValidSGMLID ("$object-$name"); @@ -3613,17 +3633,11 @@ $synop .= "${ret_type_output}${name}${flags_string}\n"; my $parameters = &OutputParamDescriptions ("SIGNAL", $symbol); - my $parameters_output = 0; $AllSymbols{$symbol} = 1; if (defined ($SymbolDocs{$symbol})) { my $symbol_docs = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - # Try to insert the parameter table at the author's desired - # position. Otherwise we need to tag it onto the end. - if ($symbol_docs =~ s//$parameters/) { - $parameters_output = 1; - } $desc .= $symbol_docs; if (!IsEmptyDoc($SymbolDocs{$symbol})) { @@ -3632,9 +3646,7 @@ } $desc .= &MakeDeprecationNote($symbol); - if ($parameters_output == 0) { - $desc .= $parameters; - } + $desc .= $parameters; if ($flags_string) { $desc .= "Flags: $flags_string\n"; } @@ -3665,7 +3677,7 @@ my $i; for ($i = 0; $i <= $#ArgObjects; $i++) { if ($ArgObjects[$i] eq $object) { - #print "Found arg: $ArgNames[$i]\n"; + @TRACE@("Found arg: $ArgNames[$i]\n"); my $name = $ArgNames[$i]; my $flags = $ArgFlags[$i]; my $flags_string = ""; @@ -3730,7 +3742,7 @@ if (defined($SymbolDocs{$symbol}) && !IsEmptyDoc($SymbolDocs{$symbol})) { $blurb = &ConvertMarkDown($symbol, $SymbolDocs{$symbol}); - #print ".. [$SymbolDocs{$symbol}][$blurb]\n"; + @TRACE@(".. [$SymbolDocs{$symbol}][$blurb]\n"); $AllDocumentedSymbols{$symbol} = 1; } else { @@ -3738,7 +3750,7 @@ $AllDocumentedSymbols{$symbol} = 1; } else { # FIXME: print a warning? - #print ".. no description\n"; + @TRACE@(".. no description\n"); } $blurb = "" . &CreateValidSGML ($ArgBlurbs[$i]) . ""; } @@ -3891,10 +3903,9 @@ my $in_comment_block = 0; my $symbol; my $in_part = ""; - my ($description, $return_desc, $return_start, $return_style); + my ($description, $return_desc); my ($since_desc, $stability_desc, $deprecated_desc); my $current_param; - my $ignore_broken_returns; my @params; while () { # Look for the start of a comment block. @@ -3902,7 +3913,7 @@ if (m%^\s*/\*.*\*/%) { #one-line comment - not gtkdoc } elsif (m%^\s*/\*\*\s%) { - #print "Found comment block start\n"; + @TRACE@("Found comment block start\n"); $in_comment_block = 1; @@ -3911,12 +3922,10 @@ $in_part = ""; $description = ""; $return_desc = ""; - $return_style = ""; $since_desc = ""; $deprecated_desc = ""; $stability_desc = ""; $current_param = -1; - $ignore_broken_returns = 0; @params = (); } next; @@ -3930,11 +3939,10 @@ } else { # Add the return value description onto the end of the params. if ($return_desc) { + # TODO(ensonic): check for duplicated Return docs + # &LogWarning ($file, $., "Multiple Returns for $symbol."); push (@params, "Returns"); push (@params, $return_desc); - if ($return_style eq 'broken') { - &LogWarning ($file, $., "Free-form return value description in $symbol. Use `Returns:' to avoid ambiguities."); - } } # Convert special SGML characters $description = &ConvertSGMLChars ($symbol, $description); @@ -3954,10 +3962,9 @@ } } - #print "SECTION DOCS found in source for : '$real_symbol'\n"; - $ignore_broken_returns = 1; + @TRACE@("SECTION DOCS found in source for : '$real_symbol'\n"); for ($k = 0; $k <= $#params; $k += $PARAM_FIELD_COUNT) { - #print " '".$params[$k]."'\n"; + @TRACE@(" '".$params[$k]."'\n"); $params[$k] = "\L$params[$k]"; undef $key; if ($params[$k] eq "short_description") { @@ -3986,7 +3993,7 @@ $SourceSymbolSourceLine{"$TMPL_DIR/$real_symbol:Long_Description"} = $.; #$SourceSymbolTypes{$symbol} = "SECTION"; } else { - #print "SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n"; + @TRACE@("SYMBOL DOCS found in source for : '$symbol' ",length($description), "\n"); $SourceSymbolDocs{$symbol} = $description; $SourceSymbolParams{$symbol} = [ @params ]; # FIXME $SourceSymbolTypes{$symbol} = "STRUCT,SIGNAL,ARG,FUNCTION,MACRO"; @@ -4001,7 +4008,7 @@ ($since_desc, my @extra_lines) = split ("\n", $since_desc); $since_desc =~ s/^\s+//; $since_desc =~ s/\s+$//; - #print "Since($symbol) : [$since_desc]\n"; + @TRACE@("Since($symbol) : [$since_desc]\n"); $Since{$symbol} = &ConvertSGMLChars ($symbol, $since_desc); if(scalar @extra_lines) { &LogWarning ($file, $., "multi-line since docs found"); @@ -4037,17 +4044,16 @@ if (!$_) { $_ = "\n"; } - #print "DEBUG: scanning :$_"; + @TRACE@("scanning :$_"); # If we haven't found the symbol name yet, look for it. if (!$symbol) { if (m%^\s*(SECTION:\s*\S+)%) { $symbol = $1; - #print "SECTION DOCS found in source for : '$symbol'\n"; - $ignore_broken_returns = 1; + @TRACE@("SECTION DOCS found in source for : '$symbol'\n"); } elsif (m%^\s*([\w:-]*\w)\s*:?\s*(\([-a-z0-9_ ]+\)\s*)*$%) { $symbol = $1; - #print "SYMBOL DOCS found in source for : '$symbol'\n"; + @TRACE@("SYMBOL DOCS found in source for : '$symbol'\n"); } next; } @@ -4057,25 +4063,13 @@ s%^\s*Description:%%; } - if (m/^\s*(returns:|return\s+value:)/i) { - if ($return_style eq 'broken') { - $description .= $return_start . $return_desc; - } - $return_start = $1; - if ($return_style eq 'sane') { - &LogWarning ($file, $., "Multiple Returns for $symbol."); - } - $return_style = 'sane'; - $ignore_broken_returns = 1; - $return_desc = $'; - $in_part = "return"; - next; - } elsif (!$ignore_broken_returns && m/^\s*(returns\b\s*)/i) { - $return_start = $1; - $return_style = 'broken'; - $return_desc = $'; - $in_part = "return"; - next; + if (m%^\s*(returns|return\s+value):%i) { + # we're in param section and have not seen the blank line + if($in_part ne "") { + $return_desc = $'; + $in_part = "return"; + next; + } } elsif (m%^\s*since:%i) { # we're in param section and have not seen the blank line if($in_part ne "") { @@ -4124,15 +4118,11 @@ my $param_name = $1; my $param_desc = $'; - #print "Found parameter: $param_name\n"; + @TRACE@("Found parameter: $param_name\n"); # Allow varargs variations if ($param_name =~ m/^\.\.\.$/) { $param_name = "..."; } - if ("\L$param_name" eq "returns") { - $return_style = 'sane'; - $ignore_broken_returns = 1; - } @TRACE@("Found param for symbol $symbol : '$param_name'= '$_'"); push (@params, $param_name); @@ -4213,9 +4203,6 @@ } } elsif ($symbol =~ /:(Long_Description|Short_Description)/) { $total++; - #my $len1=(exists($SymbolDocs{$symbol}))?length($SymbolDocs{$symbol}):-1; - #my $len2=(exists($AllDocumentedSymbols{$symbol}))?length($AllDocumentedSymbols{$symbol}):-1; - #print "%%%% $symbol : $len1,$len2\n"; if (((exists ($SymbolDocs{$symbol})) && (length ($SymbolDocs{$symbol}) > 0)) || ((exists ($AllDocumentedSymbols{$symbol})) && (length ($AllDocumentedSymbols{$symbol}) > 0))) { $n_documented++; @@ -4381,8 +4368,7 @@ if (scalar %SymbolDocs) { @Symbols=keys (%SymbolDocs); - #print "num existing entries: ".(scalar @Symbols)."\n"; - #print " ",$Symbols[0], " ",$Symbols[1],"\n"; + @TRACE@("num existing entries: ".(scalar @Symbols)."\n"); } else { # filter scanned declarations, with what we suppress from -sections.txt @@ -4403,7 +4389,7 @@ $tmp{$symbol}=1; } @Symbols = keys (%tmp); - #print "num source entries: ".(scalar @Symbols)."\n"; + @TRACE@("num source entries: ".(scalar @Symbols)."\n"); } foreach $symbol (@Symbols) { $AllSymbols{$symbol} = 1; @@ -4419,7 +4405,6 @@ # anything left ? if ($check_tmpl_doc ne "") { $have_tmpl_docs = 1; - #print "## [$check_tmpl_doc]\n"; } else { # if the docs have just an empty para, don't merge that. $check_tmpl_doc = $tmpl_doc; @@ -4432,7 +4417,7 @@ if (exists ($SourceSymbolDocs{$symbol})) { my $type = $DeclarationTypes {$symbol}; - #print "merging [$symbol] from source\n"; + @TRACE@("merging [$symbol] from source\n"); my $item = "Parameter"; if (defined ($type)) { @@ -4468,10 +4453,6 @@ $AllDocumentedSymbols{$symbol} = 1; } - # Convert with any blank lines around it to - # a followed by followed by . - $src_doc =~ s%\n+\s*\s*\n+%\n\n\n\n%g; - # Do not add to nothing, it breaks missing docs checks. my $src_doc_para = ""; if ($src_doc ne "") { @@ -4500,7 +4481,7 @@ # so we will not change that. We only override the actual text. my $tmpl_params = $SymbolParams{$symbol}; if (!defined ($tmpl_params)) { - #print "No merge needed for $symbol\n"; + @TRACE@("No merge needed for $symbol\n"); $SymbolParams{$symbol} = $SourceSymbolParams{$symbol}; # FIXME: we still like to get the number of params and merge # 1) we would noticed that params have been removed/renamed @@ -4510,19 +4491,19 @@ } else { my $params = $SourceSymbolParams{$symbol}; my $j; - #print "Merge needed for $symbol, tmpl_params: ",$#$tmpl_params,", source_params: ",$#$params," \n"; + @TRACE@("Merge needed for $symbol, tmpl_params: ",$#$tmpl_params,", source_params: ",$#$params," \n"); for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) { my $tmpl_param_name = $$tmpl_params[$j]; # Try to find the param in the source comment documentation. my $found = 0; my $k; - #print " try merge param $tmpl_param_name\n"; + @TRACE@(" try merge param $tmpl_param_name\n"); for ($k = 0; $k <= $#$params; $k += $PARAM_FIELD_COUNT) { my $param_name = $$params[$k]; my $param_desc = $$params[$k + 1]; - #print " test param $param_name\n"; + @TRACE@(" test param $param_name\n"); # We accept changes in case, since the Gnome source # docs contain a lot of these. if ("\L$param_name" eq "\L$tmpl_param_name") { @@ -4555,7 +4536,7 @@ if(($type eq "MACRO") && ($param_name eq "Returns")) { # FIXME: do we need to add it then to tmpl_params[] ? my $num=$#$tmpl_params; - #print " adding Returns: to macro docs for $symbol.\n"; + @TRACE@(" adding Returns: to macro docs for $symbol.\n"); $$tmpl_params[$num+1]="Returns"; $$tmpl_params[$num+2]=$$params[$j+1]; next; @@ -4569,10 +4550,10 @@ } else { if ($have_tmpl_docs) { $AllDocumentedSymbols{$symbol} = 1; - #print "merging [$symbol] from template\n"; + @TRACE@("merging [$symbol] from template\n"); } else { - #print "[$symbol] undocumented\n"; + @TRACE@("[$symbol] undocumented\n"); } } @@ -4599,7 +4580,7 @@ $type="SIGNAL"; } - #print "Check param docs for $symbol, tmpl_params: ",$#$tmpl_params," entries, type=$type\n"; + @TRACE@("Check param docs for $symbol, tmpl_params: ",$#$tmpl_params," entries, type=$type\n"); if ($#$tmpl_params > 0) { my $j; @@ -4631,7 +4612,7 @@ } } } - #print "num doc entries: ".(scalar %SymbolDocs)."\n"; + @TRACE@("num doc entries: ".(scalar %SymbolDocs)."\n"); } ############################################################################# @@ -4740,7 +4721,7 @@ # a heading is ended by any level less than or equal if ($md_block->{"level"} == 1) { if ($line =~ /^={4,}[ \t]*$/) { - my $text = pop $md_block->{"lines"}; + my $text = pop @{$md_block->{"lines"}}; $md_block->{"interrupted"} = 0; push @md_blocks, $md_block; @@ -4761,12 +4742,12 @@ next OUTER; } else { # push lines into the block until the end is reached - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; next OUTER; } } else { if ($line =~ /^[=]{4,}[ \t]*$/) { - my $text = pop $md_block->{"lines"}; + my $text = pop @{$md_block->{"lines"}}; $md_block->{"interrupted"} = 0; push @md_blocks, $md_block; @@ -4776,7 +4757,7 @@ level => 1 }; next OUTER; } elsif ($line =~ /^[-]{4,}[ \t]*$/) { - my $text = pop $md_block->{"lines"}; + my $text = pop @{$md_block->{"lines"}}; $md_block->{"interrupted"} = 0; push @md_blocks, $md_block; @@ -4797,7 +4778,7 @@ next OUTER; } else { # push lines into the block until the end is reached - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; next OUTER; } } @@ -4808,7 +4789,7 @@ text => "", lines => [] }; } else { - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; } next OUTER; } @@ -4821,7 +4802,7 @@ if ($md_block->{"type"} eq "quote") { if (!$md_block->{"interrupted"}) { $line =~ s/^[ ]*>[ ]?//; - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; next OUTER; } } elsif ($md_block->{"type"} eq "li") { @@ -4829,7 +4810,7 @@ if ($line =~ /^([ ]{0,3})($marker)[ ](.*)/) { my $indentation = $1; if ($md_block->{"indentation"} ne $indentation) { - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; } else { my $lines = $3; my $ordered = $md_block->{"ordered"}; @@ -4849,15 +4830,15 @@ if ($md_block->{"interrupted"}) { if ($first_char eq " ") { - push $md_block->{"lines"}, ""; + push @{$md_block->{"lines"}}, ""; $line =~ s/^[ ]{0,4}//; - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; $md_block->{"interrupted"} = 0; next OUTER; } } else { $line =~ s/^[ ]{0,4}//; - push $md_block->{"lines"}, $line; + push @{$md_block->{"lines"}}, $line; next OUTER; } } @@ -4908,7 +4889,6 @@ } # indentation insensitive types - if ($line =~ /^[ ]*{"interrupted"}) { - push $block->{"lines"}, ""; + push @{$block->{"lines"}}, ""; } $text = &MarkDownParseLines ($block->{"lines"}, $symbol, "li"); @@ -5441,7 +5421,7 @@ if (m/^<([^>]+)>/) { $declaration_type = $1; $declaration_name = ""; - #print "Found declaration: $declaration_type\n"; + @TRACE@("Found declaration: $declaration_type\n"); $declaration = ""; } } else { @@ -5450,17 +5430,17 @@ } elsif (m%^%) { $is_deprecated = 1; } elsif (m%^%) { - #print "Found end of declaration: $declaration_name\n"; + @TRACE@("Found end of declaration: $declaration_name\n"); # Check that the declaration has a name if ($declaration_name eq "") { - print "ERROR: $declaration_type has no name $file:$.\n"; + &LogWarning ($file, $., "$declaration_type has no name.\n"); } # If the declaration is an empty typedef struct _XXX XXX # set the flag to indicate the struct has a typedef. if ($declaration_type eq 'STRUCT' && $declaration =~ m/^\s*$/) { - #print "Struct has typedef: $declaration_name\n"; + @TRACE@("Struct has typedef: $declaration_name\n"); $StructHasTypedef{$declaration_name} = 1; } @@ -5570,7 +5550,7 @@ if ($signal_name =~ m/^(.*)::(.*)$/) { $signal_object = $1; ($signal_name = $2) =~ s/_/-/g; - #print "Found signal: $signal_name\n"; + @TRACE@("Found signal: $signal_name\n"); } else { &LogWarning ($file, $., "Invalid signal name: $signal_name."); } @@ -5579,7 +5559,7 @@ } elsif (m/^(.*)<\/FLAGS>/) { $signal_flags = $1; } elsif (m%^%) { - #print "Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}"; + @TRACE@("Found end of signal: ${signal_object}::${signal_name}\nReturns: ${signal_returns}\n${signal_prototype}"); push (@SignalObjects, $signal_object); push (@SignalNames, $signal_name); push (@SignalReturns, $signal_returns); @@ -5614,7 +5594,7 @@ my $template = "$docsfile.sgml"; if (! -f $template) { - #print "File doesn't exist: $template\n"; + @TRACE@("File doesn't exist: $template\n"); return 0; } @@ -5657,7 +5637,7 @@ $symbol = $docsfile . ":" . $symbol; } - #print "Found symbol: $symbol\n"; + @TRACE@("Found symbol: $symbol\n"); # Remember file and line for the symbol $SymbolSourceFile{$symbol} = $template; $SymbolSourceLine{$symbol} = $.; @@ -5692,13 +5672,13 @@ @params = (); } elsif (m/^/) { - #print "DEBUG: Found unused parameters\n"; + @TRACE@("Found unused parameters\n"); $in_unused_params = 1; next; } elsif ($in_unused_params && $skip_unused_params) { # When outputting the DocBook we skip unused parameters. - #print "DEBUG: Skipping unused param: $_"; + @TRACE@("Skipping unused param: $_"); next; } else { @@ -6009,7 +5989,7 @@ if ($arg_name =~ m/^(.*)::(.*)$/) { $arg_object = $1; ($arg_name = $2) =~ s/_/-/g; - #print "Found arg: $arg_name\n"; + @TRACE@("Found arg: $arg_name\n"); } else { &LogWarning ($file, $., "Invalid argument name: $arg_name"); } @@ -6030,7 +6010,7 @@ } elsif (m/^(.*)<\/DEFAULT>/) { $arg_default = $1; } elsif (m%^%) { - #print "Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n"; + @TRACE@("Found end of arg: ${arg_object}::${arg_name}\n${arg_type} : ${arg_flags}\n"); push (@ArgObjects, $arg_object); push (@ArgNames, $arg_name); push (@ArgTypes, $arg_type); diff -Nru gtk-doc-1.20/gtkdoc-scan.in gtk-doc-1.21/gtkdoc-scan.in --- gtk-doc-1.20/gtkdoc-scan.in 2014-02-10 09:09:25.000000000 +0000 +++ gtk-doc-1.21/gtkdoc-scan.in 2014-07-09 13:36:00.000000000 +0000 @@ -381,9 +381,12 @@ # If we find a line containing _DEPRECATED, we hope that this is # attribute based deprecation and also treat this as a deprecation - # guard. + # guard, unless it's a macro definition. if ($deprecated_conditional_nest == 0 and m/_DEPRECATED/) { - $deprecated_conditional_nest += 0.1; + unless (m/^\s*#\s*(if*|define)/ or $in_declaration eq "enum") { + @TRACE@("Found deprecation annotation (decl: '$in_declaration'): $_"); + $deprecated_conditional_nest += 0.1; + } } # set global that is used later when we do AddSymbolToList @@ -484,7 +487,7 @@ # ENUMS - } elsif (s/^\s*enum\s+_(\w+)\s+\{/enum $1 {/) { + } elsif (s/^\s*enum\s+_?(\w+)\s+\{/enum $1 {/) { # We assume that 'enum _ {' is really the # declaration of enum . $symbol = $1; @@ -555,7 +558,7 @@ # VARIABLES (extern'ed variables) - } elsif (m/^\s*(extern|[A-Za-z_]+VAR|${IGNORE_DECORATORS})\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;/) { + } elsif (m/^\s*(extern|[A-Za-z_]+VAR|${IGNORE_DECORATORS})\s+((const\s+|signed\s+|unsigned\s+|long\s+|short\s+)*\w+)(\s+\*+|\*+|\s)\s*(const\s+)*([A-Za-z]\w*)\s*;/o) { $symbol = $6; s/^\s*([A-Za-z_]+VAR)\b/extern/; $decl = $_; @@ -682,11 +685,11 @@ # STRUCTS - } elsif (m/^\s*struct\s+_(\w+)\s*\*/) { + } elsif (m/^\s*struct\s+_?(\w+)\s*\*/) { # Skip 'struct _ *', since it could be a # return type on its own line. - } elsif (m/^\s*struct\s+_(\w+)/) { + } elsif (m/^\s*struct\s+_?(\w+)/) { # We assume that 'struct _' is really the # declaration of struct . $symbol = $1; diff -Nru gtk-doc-1.20/gtkdoc-scanobj.in gtk-doc-1.21/gtkdoc-scanobj.in --- gtk-doc-1.20/gtkdoc-scanobj.in 2013-05-31 11:51:45.000000000 +0000 +++ gtk-doc-1.21/gtkdoc-scanobj.in 1970-01-01 00:00:00.000000000 +0000 @@ -1,580 +0,0 @@ -#!@PERL@ -w -# -*- cperl -*- -# -# gtk-doc - GTK DocBook documentation generator. -# Copyright (C) 1998 Damon Chaplin -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2 of the License, or -# (at your option) any later version. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with this program; if not, write to the Free Software -# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. -# - -# -# This gets information about object heirarchies and signals -# by compiling a small C program. CFLAGS and LDFLAGS must be -# set appropriately before running this script. -# - -use Getopt::Long; - -push @INC, '@PACKAGE_DATA_DIR@'; -require "gtkdoc-common.pl"; - -# Options - -# name of documentation module -my $MODULE; -my $OUTPUT_DIR; -my $PRINT_VERSION; - -my $CC; -my $LD; -my $CFLAGS; -my $LDFLAGS; -my $RUN; - -%optctl = (module => \$MODULE, - types => \$TYPES_FILE, - nogtkinit => \$NO_GTK_INIT, - 'output-dir' => \$OUTPUT_DIR, - 'cc' => \$CC, - 'ld' => \$LD, - 'cflags' => \$CFLAGS, - 'ldflags' => \$LDFLAGS, - 'run' => \$RUN, - 'version' => \$PRINT_VERSION, - 'help' => \$PRINT_HELP); - -GetOptions(\%optctl, "module=s", "types:s", "output-dir:s", "nogtkinit", "cc:s", "ld:s", "run:s", "cflags:s", "ldflags:s", "version", "help"); - -if ($PRINT_VERSION) { - print "@VERSION@\n"; - exit 0; -} - -if (!$MODULE) { - $PRINT_HELP = 1; -} - -if ($PRINT_HELP) { - print <$MODULE-scan.c") || die "Cannot open $MODULE-scan.c: $!\n"; - -my $old_signals_filename = "$OUTPUT_DIR/$MODULE.signals"; -my $new_signals_filename = "$OUTPUT_DIR/$MODULE.signals.new"; -my $old_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy"; -my $new_hierarchy_filename = "$OUTPUT_DIR/$MODULE.hierarchy.new"; -my $old_args_filename = "$OUTPUT_DIR/$MODULE.args"; -my $new_args_filename = "$OUTPUT_DIR/$MODULE.args.new"; - -# write a C program to scan the types - -$includes = ""; -@types = (); - -for () { - if (/^#include/) { - $includes .= $_; - } elsif (/^%/) { - next; - } elsif (/^\s*$/) { - next; - } else { - chomp; - push @types, $_; - } -} - -$ntypes = @types + 1; - -print OUTPUT < -#include -#include -#include - -$includes -GtkType object_types[$ntypes]; - -GtkType * -get_object_types (void) -{ - gint i = 0; -EOT - -for (@types) { - print OUTPUT " object_types[i++] = $_ ();\n"; -} - -print OUTPUT <nsignals == 0) - return; - - object_class_name = gtk_type_name (object_type); - - for (sig = 0; sig < class->nsignals; sig++) - { - if (!class->signals[sig]) - { - /*g_print ("Signal slot [%u] is empty\\n", sig);*/ - continue; - } - - output_widget_signal (fp, object_type, object_class_name, - class->signals[sig]); - } -} - - -/* This outputs one signal. */ -static void -output_widget_signal (FILE *fp, - GtkType object_type, - gchar *object_name, - guint signal_id) -{ - GtkSignalQuery *query_info; - gchar *ret_type, *pos, *type_name, *arg_name, *object_arg, *object_arg_start; - gboolean is_pointer; - gchar buffer[1024]; - guint i, param; - gint param_num, widget_num, event_num, callback_num; - gint *arg_num; - gchar signal_name[128]; - - /* g_print ("Object: %s Type: %i Signal: %u\\n", object_name, object_type, - signal_id);*/ - - param_num = 1; - widget_num = event_num = callback_num = 0; - - query_info = gtk_signal_query (signal_id); - if (query_info == NULL) - { - g_warning ("Couldn't query signal"); - return; - } - - /* Output the signal object type and the argument name. We assume the - type is a pointer - I think that is OK. We remove "Gtk" or "Gnome" and - convert to lower case for the argument name. */ - pos = buffer; - sprintf (pos, "%s ", object_name); - pos += strlen (pos); - - /* Try to come up with a sensible variable name for the first arg - * I chops off 2 know prefixes :/ and makes the name lowercase - * It should replace lowercase -> uppercase with '_' - * see gtkdoc-scangobject.in for better algorithm - */ - if (!strncmp (object_name, "Gtk", 3)) - object_arg = object_name + 3; - else if (!strncmp (object_name, "Gnome", 5)) - object_arg = object_name + 5; - else - object_arg = object_name; - - object_arg_start = pos; - sprintf (pos, "*%s\\n", object_arg); - pos += strlen (pos); - g_strdown (object_arg_start); - if (!strcmp (object_arg_start, "widget")) - widget_num++; - - /* Convert signal name to use underscores rather than dashes '-'. */ - strncpy (signal_name, query_info->signal_name, 127); - signal_name[127] = '\\0'; - for (i = 0; signal_name[i]; i++) - { - if (signal_name[i] == '-') - signal_name[i] = '_'; - } - - /* Output the signal parameters. */ - for (param = 0; param < query_info->nparams; param++) - { - type_name = get_type_name (query_info->params[param], &is_pointer); - - /* Most arguments to the callback are called "arg1", "arg2", etc. - GtkWidgets are called "widget", "widget2", ... - GtkCallbacks are called "callback", "callback2", ... */ - if (!strcmp (type_name, "GtkWidget")) - { - arg_name = "widget"; - arg_num = &widget_num; - } - else if (!strcmp (type_name, "GtkCallback") - || !strcmp (type_name, "GtkCCallback")) - { - arg_name = "callback"; - arg_num = &callback_num; - } - else - { - arg_name = "arg"; - arg_num = ¶m_num; - } - sprintf (pos, "%s ", type_name); - pos += strlen (pos); - - if (!arg_num || *arg_num == 0) - sprintf (pos, "%s%s\\n", is_pointer ? "*" : " ", arg_name); - else - sprintf (pos, "%s%s%i\\n", is_pointer ? "*" : " ", arg_name, - *arg_num); - pos += strlen (pos); - - if (arg_num) - *arg_num += 1; - } - - /* Output the return type and function name. */ - ret_type = get_type_name (query_info->return_val, &is_pointer); - - fprintf (fp, - "\\n%s::%s\\n%s%s\\n%s\\n\\n", - object_name, query_info->signal_name, ret_type, is_pointer ? "*" : "", buffer); - g_free (query_info); -} - - -/* Returns the type name to use for a signal argument or return value, given - the GtkType from the signal info. It also sets is_pointer to TRUE if the - argument needs a '*' since it is a pointer. */ -static gchar * -get_type_name (GtkType type, gboolean * is_pointer) -{ - gchar *type_name; - - *is_pointer = FALSE; - type_name = gtk_type_name (type); - - switch (type) { - case GTK_TYPE_NONE: - case GTK_TYPE_CHAR: - case GTK_TYPE_UCHAR: - case GTK_TYPE_BOOL: - case GTK_TYPE_INT: - case GTK_TYPE_UINT: - case GTK_TYPE_LONG: - case GTK_TYPE_ULONG: - case GTK_TYPE_FLOAT: - case GTK_TYPE_DOUBLE: - case GTK_TYPE_POINTER: - /* These all have normal C type names so they are OK. */ - return type_name; - - case GTK_TYPE_STRING: - /* A GtkString is really a gchar*. */ - *is_pointer = TRUE; - return "gchar"; - - case GTK_TYPE_ENUM: - case GTK_TYPE_FLAGS: - /* We use a gint for both of these. Hopefully a subtype with a decent - name will be registered and used instead, as GTK+ does itself. */ - return "gint"; - - case GTK_TYPE_BOXED: - /* A boxed value is just an opaque pointer, I think. */ - return "gpointer"; - - case GTK_TYPE_SIGNAL: - case GTK_TYPE_ARGS: - case GTK_TYPE_FOREIGN: - case GTK_TYPE_CALLBACK: - case GTK_TYPE_C_CALLBACK: - /* FIXME: These are wrong. I think they expand into more than 1 argument. - See the GtkArg struct in gtktypeutils.h and gtkargcollector.c. - Fortunately I doubt anything uses these as signal args. */ - return "gpointer"; - - default: - break; - } - - /* For all GtkObject subclasses we can use the class name with a "*", - e.g. 'GtkWidget *'. */ - if (gtk_type_is_a (type, GTK_TYPE_OBJECT)) - *is_pointer = TRUE; - - return type_name; -} - - -/* This outputs the hierarchy of all widgets which have been initialized, - i.e. by calling their XXX_get_type() initialization function. */ -static void -output_widget_hierarchy (void) -{ - FILE *fp; - - fp = fopen (hierarchy_filename, "w"); - if (fp == NULL) - { - g_warning ("Couldn't open output file: %s : %s", hierarchy_filename, g_strerror(errno)); - return; - } - output_hierarchy (fp, GTK_TYPE_OBJECT, 0); - fclose (fp); -} - - -/* This is called recursively to output the hierarchy of a widget. */ -static void -output_hierarchy (FILE *fp, - GtkType type, - guint level) -{ - GList *list; - guint i; - - if (!type) - return; - - for (i = 0; i < level; i++) - fprintf (fp, " "); - fprintf (fp, "%s\\n", gtk_type_name (type)); - - list = gtk_type_children_types (type); - - while (list) - { - GtkType child = (GtkType) list->data; - output_hierarchy (fp, child, level + 1); - list = list->next; - } -} - - -static void -output_args (void) -{ - FILE *fp; - gint i; - - fp = fopen (args_filename, "w"); - if (fp == NULL) - { - g_warning ("Couldn't open output file: %s : %s", args_filename, g_strerror(errno)); - return; - } - - for (i = 0; object_types[i]; i++) - output_widget_args (fp, object_types[i]); - - fclose (fp); -} - - -static void -output_widget_args (FILE *fp, GtkType object_type) -{ - GtkObjectClass *class; - gchar *object_class_name; - GtkArg *args; - guint32 *arg_flags; - guint n_args; - guint arg; - gchar flags[16], *pos; - - class = gtk_type_class (object_type); - if (!class) - return; - - object_class_name = gtk_type_name (object_type); - - args = gtk_object_query_args (class->type, &arg_flags, &n_args); - - for (arg = 0; arg < n_args; arg++) - { - pos = flags; - /* We use one-character flags for simplicity. */ - if (arg_flags[arg] & GTK_ARG_READABLE) - *pos++ = 'r'; - if (arg_flags[arg] & GTK_ARG_WRITABLE) - *pos++ = 'w'; - if (arg_flags[arg] & GTK_ARG_CONSTRUCT) - *pos++ = 'x'; - if (arg_flags[arg] & GTK_ARG_CONSTRUCT_ONLY) - *pos++ = 'X'; - if (arg_flags[arg] & GTK_ARG_CHILD_ARG) - *pos++ = 'c'; - *pos = 0; - - fprintf (fp, "\\n%s\\n%s\\n%s\\n\\n\\n", - args[arg].name, gtk_type_name (args[arg].type), flags); - } - - g_free (args); - g_free (arg_flags); -} -EOT - -close OUTPUT; - -# Compile and run our file - -unless ($CC) { - $CC = $ENV{CC} ? $ENV{CC} : "gcc"; -} -unless ($LD) { - $LD = $ENV{LD} ? $ENV{LD} : $CC; -} -unless ($CFLAGS) { - $CFLAGS = $ENV{CFLAGS} ? $ENV{CFLAGS} : ""; -} -unless ($LDFLAGS) { - $LDFLAGS = $ENV{LDFLAGS} ? $ENV{LDFLAGS} : ""; -} -unless ($RUN) { - $RUN = $ENV{RUN} ? $ENV{RUN} : ""; -} - -my $o_file; -if ($CC =~ /libtool/) { - $o_file = "$MODULE-scan.lo" -} else { - $o_file = "$MODULE-scan.o" -} - -# Compiling scanner -$command = "$CC $CFLAGS -c -o $o_file $MODULE-scan.c"; -system("($command)") == 0 or die "Compilation of scanner failed: $!\n"; - -# Linking scanner -# FIXME: Can we turn off as-needed for the docs (or better fix it?) -#$command = "$LD -Wl,--no-as-needed $o_file $LDFLAGS -o $MODULE-scan"; -$command = "$LD $o_file $LDFLAGS -o $MODULE-scan"; -system("($command)") == 0 or die "Linking of scanner failed: $!\n"; - -# Running scanner $MODULE-scan "; -system("($RUN ./$MODULE-scan)") == 0 or die "Scan failed: $!\n"; - -if (!defined($ENV{"GTK_DOC_KEEP_INTERMEDIATE"})) { - unlink "./$MODULE-scan.c", "./$MODULE-scan.o", "./$MODULE-scan.lo", "./$MODULE-scan"; -} - -&UpdateFileIfChanged ($old_signals_filename, $new_signals_filename, 0); -&UpdateFileIfChanged ($old_hierarchy_filename, $new_hierarchy_filename, 0); -&UpdateFileIfChanged ($old_args_filename, $new_args_filename, 0); - diff -Nru gtk-doc-1.20/gtk-doc.spec gtk-doc-1.21/gtk-doc.spec --- gtk-doc-1.20/gtk-doc.spec 2014-02-15 21:45:01.000000000 +0000 +++ gtk-doc-1.21/gtk-doc.spec 2014-07-17 18:29:28.000000000 +0000 @@ -2,7 +2,7 @@ Summary: GTK+ DocBook Documentation Generator Name: gtk-doc -Version: 1.20 +Version: 1.21 Release: 1 License: GPL Group: Utilities/Text diff -Nru gtk-doc-1.20/gtk-doc.xsl gtk-doc-1.21/gtk-doc.xsl --- gtk-doc-1.20/gtk-doc.xsl 2014-02-13 08:01:27.000000000 +0000 +++ gtk-doc-1.21/gtk-doc.xsl 2014-02-27 17:29:44.000000000 +0000 @@ -467,7 +467,7 @@ + summary = "Navigation header" cellpadding="2" cellspacing="5">