diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl index 6e46547608..bd843de5d7 100755 --- a/build-scripts/wikiheaders.pl +++ b/build-scripts/wikiheaders.pl @@ -37,6 +37,11 @@ my $versionfname = 'include/SDL_version.h'; my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z'; my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z'; my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z'; +my $wikidocsectionsym = 'SDL_WIKI_DOCUMENTATION_SECTION'; +my $forceinlinesym = 'SDL_FORCE_INLINE'; +my $deprecatedsym = 'SDL_DEPRECATED'; +my $declspecsym = '(?:SDLMAIN_|SDL_)?DECLSPEC'; +my $callconvsym = 'SDLCALL'; my $mainincludefname = 'SDL.h'; my $selectheaderregex = '\ASDL.*?\.h\Z'; my $projecturl = 'https://libsdl.org/'; @@ -147,6 +152,12 @@ if (defined $optionsfname) { $envvardesc = $val, next if $key eq 'envvardesc'; $envvarsymregex = $val, next if $key eq 'envvarsymregex'; $envvarsymreplace = $val, next if $key eq 'envvarsymreplace'; + $wikidocsectionsym = $val, next if $key eq 'wikidocsectionsym'; + $forceinlinesym = $val, next if $key eq 'forceinlinesym'; + $deprecatedsym = $val, next if $key eq 'deprecatedsym'; + $declspecsym = $val, next if $key eq 'declspecsym'; + $callconvsym = $val, next if $key eq 'callconvsym'; + } } close(OPTIONS); @@ -750,6 +761,7 @@ sub print_undocumented_section { } } +# !!! FIXME: generalize this for other libraries to use. sub strip_fn_declaration_metadata { my $decl = shift; $decl =~ s/SDL_(PRINTF|SCANF)_FORMAT_STRING\s*//; # don't want this metadata as part of the documentation. @@ -1153,7 +1165,7 @@ while (my $d = readdir(DH)) { } elsif ($ignoring_lines) { push @contents, $_; next; - } elsif (/\A\s*\#\s*ifndef\s+SDL_WIKI_DOCUMENTATION_SECTION\s*\Z/) { + } elsif (/\A\s*\#\s*ifndef\s+$wikidocsectionsym\s*\Z/) { $ignoring_lines = 1; push @contents, $_; next; @@ -1162,13 +1174,13 @@ while (my $d = readdir(DH)) { #print("CATEGORY FOR '$dent' CHANGED TO " . (defined($current_wiki_category) ? "'$current_wiki_category'" : '(undef)') . "\n"); push @contents, $_; next; - } elsif (/\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) { # a function declaration without a doxygen comment? + } elsif (/\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym/) { # a function declaration without a doxygen comment? $symtype = 1; # function declaration @templines = (); $decl = $_; $str = ''; $has_doxygen = 0; - } elsif (/\A\s*SDL_FORCE_INLINE/) { # a (forced-inline) function declaration without a doxygen comment? + } elsif (/\A\s*$forceinlinesym/) { # a (forced-inline) function declaration without a doxygen comment? $symtype = 1; # function declaration @templines = (); $decl = $_; @@ -1235,9 +1247,9 @@ while (my $d = readdir(DH)) { $lineno++ if defined $decl; $decl = '' if not defined $decl; chomp($decl); - if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC/) { + if ($decl =~ /\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym/) { $symtype = 1; # function declaration - } elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) { + } elsif ($decl =~ /\A\s*$forceinlinesym/) { $symtype = 1; # (forced-inline) function declaration } elsif ($decl =~ /\A\s*\#\s*define\s+/) { $symtype = 2; # macro @@ -1274,7 +1286,7 @@ while (my $d = readdir(DH)) { } $headercategorydocs{$current_wiki_category} = $sym; } elsif ($symtype == 1) { # a function - my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/); + my $is_forced_inline = ($decl =~ /\A\s*$forceinlinesym/); if ($is_forced_inline) { if (not $decl =~ /\)\s*(\{.*|)\s*\Z/) { @@ -1311,14 +1323,14 @@ while (my $d = readdir(DH)) { my $paramsstr = undef; - if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*SDLCALL\s+(.*?)\s*\((.*?)\);/) { - $sym = $8; - $rettype = "$3$4$5$6"; - $paramsstr = $9; - } elsif ($is_forced_inline && $decl =~ /\A\s*SDL_FORCE_INLINE\s+(SDL_DEPRECATED\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) { + if (!$is_forced_inline && $decl =~ /\A\s*extern\s+(?:$deprecatedsym\s+|)$declspecsym\w*\s+(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(\*?)\s*$callconvsym\s+(.*?)\s*\((.*?)\);/) { $sym = $6; - $rettype = "$2$3$4$5"; + $rettype = "$1$2$3$4$5"; $paramsstr = $7; + } elsif ($is_forced_inline && $decl =~ /\A\s*$forceinlinesym\s+(?:$deprecatedsym\s+|)(const\s+|)(unsigned\s+|)(.*?)([\*\s]+)(.*?)\s*\((.*?)\);/) { + $sym = $5; + $rettype = "$1$2$3$4"; + $paramsstr = $6; } else { #print "Found doxygen but no function sig:\n$str\n\n"; foreach (@templines) { @@ -1384,7 +1396,7 @@ while (my $d = readdir(DH)) { $decl = $_; $temp = $decl; - $temp =~ s/\Aextern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_|SDL_)?DECLSPEC\w*\s+(.*?)\s+(\*?)SDLCALL\s+/$3$4 /; + $temp =~ s/\Aextern\s+(?:$deprecatedsym\s+|)$declspecsym\w*\s+(.*?)\s+(\*?)$callconvsym\s+/$1$2 /; $shrink_length = length($decl) - length($temp); $decl = $temp; } else { @@ -2259,10 +2271,10 @@ if ($copy_direction == 1) { # --copy-to-headers $desc =~ s/[\s\n]+\Z//ms; - if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful. - if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) { - print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a capital letter: '$desc'. Fixing.\n"; - $desc = lcfirst($desc); + if (0) { + if (($desc =~ /\A[a-z]/) && (not $desc =~ /$apiprefixregex/)) { + print STDERR "WARNING: $sym\'s '\\param $arg' text starts with a lowercase letter: '$desc'. Fixing.\n"; + $desc = ucfirst($desc); } } @@ -2306,8 +2318,8 @@ if ($copy_direction == 1) { # --copy-to-headers } $desc =~ s/[\s\n]+\Z//ms; - if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful. - if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) { + if (0) { + if (($desc =~ /\A[A-Z]/) && (not $desc =~ /$apiprefixregex/)) { print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n"; $desc = lcfirst($desc); } @@ -2451,7 +2463,7 @@ if ($copy_direction == 1) { # --copy-to-headers } else { die("Unexpected symbol type $symtype!"); } - my $str = "This $symtypename is available since SDL 3.0.0."; + my $str = "This $symtypename is available since $projectshortname 3.0.0."; $sections{'Version'} = wordwrap(wikify($wikitype, $str)) . "\n"; } } @@ -2916,7 +2928,7 @@ __EOF__ $str .= ".\\\" Please report issues in this manpage's content at:\n"; $str .= ".\\\" $bugreporturl\n"; $str .= ".\\\" Please report issues in the generation of this manpage from the wiki at:\n"; - $str .= ".\\\" https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20$sym\n"; + $str .= ".\\\" https://github.com/libsdl-org/SDL/issues/new?title=Misgenerated%20manpage%20for%20$sym\n"; # !!! FIXME: if this becomes a problem for other projects, we'll generalize this. $str .= ".\\\" $projectshortname can be found at $projecturl\n"; # Define a .URL macro. The "www.tmac" thing decides if we're using GNU roff (which has a .URL macro already), and if so, overrides the macro we just created.