From 21f93e127bad2b6ba3ec88684ddae47782c36eeb Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
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 6e46547608810..bd843de5d7d87 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -37,6 +37,11 @@
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 @@
$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 @@ sub generate_envvar_wiki_page {
} 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 @@ sub generate_envvar_wiki_page {
#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 @@ sub generate_envvar_wiki_page {
$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 @@ sub generate_envvar_wiki_page {
}
$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 @@ sub generate_envvar_wiki_page {
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 @@ sub generate_envvar_wiki_page {
$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 @@ sub generate_envvar_wiki_page {
$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 @@ sub generate_envvar_wiki_page {
}
$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 @@ sub generate_envvar_wiki_page {
} 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 @@ sub generate_envvar_wiki_page {
$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.