From 21f93e127bad2b6ba3ec88684ddae47782c36eeb Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Tue, 25 Nov 2025 23:11:13 -0500 Subject: [PATCH] wikiheaders: generalize some previously-SDL-specific things Now other projects can use it with their headers, if they provide an options file with specifics and are willing to follow some SDLish header conventions. This shouldn't affect SDL satellite projects, etc, since they literally use the SDL symbols, like `SDLCALL` and such, which are the defaults in the script if a .wikiheaders-options file doesn't override them. --- build-scripts/wikiheaders.pl | 54 ++++++++++++++++++++++-------------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl index 6e4654760..bd843de5d 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.