mirrors/SDL
0
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2024-11-26 21:33:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

wikiheaders.pl: Migrate in docs that exist only in the wiki.

Browse Source 
This is going to expose some docs that needs cleaning up once
the bridge imports those docs, though.
This commit is contained in:
Ryan C. Gordon 2021-10-08 14:39:28 -04:00
parent 194657a2c6
commit 3970a885a5
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
1 changed files with 75 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
build-scripts/wikiheaders.pl
View File

@ -292,6 +292,7 @@ my %headerfuncs = (); # $headerfuncs{"SDL_OpenAudio"} -> string of header docu
my %headerdecls = ();
my %headerfuncslocation = (); # $headerfuncslocation{"SDL_OpenAudio"} -> name of header holding SDL_OpenAudio define ("SDL_audio.h" in this case).
my %headerfuncschunk = (); # $headerfuncschunk{"SDL_OpenAudio"} -> offset in array in %headers that should be replaced for this function.
my %headerfuncshasdoxygen = (); # $headerfuncschunk{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function.
my $incpath = "$srcpath/include";
opendir(DH, $incpath) or die("Can't opendir '$incpath': $!\n");
@ -304,46 +305,54 @@ while (readdir(DH)) {
while (<FH>) {
chomp;
if (not /\A\/\*\*\s*\Z/) { # not doxygen comment start?
my $decl;
my @templines;
my $str;
my $has_doxygen = 1;
if (/\A\s*extern\s+DECLSPEC/) { # a function declaration without a doxygen comment?
@templines = ();
$decl = $_;
$str = '';
$has_doxygen = 0;
} elsif (not /\A\/\*\*\s*\Z/) { # not doxygen comment start?
push @contents, $_;
next;
}
my @templines = ();
push @templines, $_;
my $str = '';
while (<FH>) {
chomp;
push @templines, $_;
last if /\A\s*\*\/\Z/;
if (s/\A\s*\*\s*\`\`\`/```/) { # this is a hack, but a lot of other code relies on the whitespace being trimmed, but we can't trim it in code blocks...
$str .= "$_\n";
while (<FH>) {
chomp;
push @templines, $_;
s/\A\s*\*\s?//;
if (s/\A\s*\`\`\`/```/) {
$str .= "$_\n";
last;
} else {
$str .= "$_\n";
} else { # Start of a doxygen comment, parse it out.
@templines = ( $_ );
while (<FH>) {
chomp;
push @templines, $_;
last if /\A\s*\*\/\Z/;
if (s/\A\s*\*\s*\`\`\`/```/) { # this is a hack, but a lot of other code relies on the whitespace being trimmed, but we can't trim it in code blocks...
$str .= "$_\n";
while (<FH>) {
chomp;
push @templines, $_;
s/\A\s*\*\s?//;
if (s/\A\s*\`\`\`/```/) {
$str .= "$_\n";
last;
} else {
$str .= "$_\n";
}
}
} else {
s/\A\s*\*\s*//;
$str .= "$_\n";
}
} else {
s/\A\s*\*\s*//;
$str .= "$_\n";
}
}
my $decl = <FH>;
chomp($decl);
if (not $decl =~ /\A\s*extern\s+DECLSPEC/) {
#print "Found doxygen but no function sig:\n$str\n\n";
foreach (@templines) {
push @contents, $_;
$decl = <FH>;
$decl = '' if not defined $decl;
chomp($decl);
if (not $decl =~ /\A\s*extern\s+DECLSPEC/) {
#print "Found doxygen but no function sig:\n$str\n\n";
foreach (@templines) {
push @contents, $_;
}
push @contents, $decl;
next;
}
push @contents, $decl;
next;
}
my @decllines = ( $decl );
@ -397,6 +406,7 @@ while (readdir(DH)) {
$headerdecls{$fn} = $decl;
$headerfuncslocation{$fn} = $dent;
$headerfuncschunk{$fn} = scalar(@contents);
$headerfuncshasdoxygen{$fn} = $has_doxygen;
push @contents, join("\n", @templines);
push @contents, join("\n", @decllines);
@ -522,7 +532,6 @@ if ($copy_direction == 1) { # --copy-to-headers
$wordwrap_mode = 'md'; # the headers use Markdown format.
# if it's not in the headers already, we don't add it, so iterate what we know is already there for changes.
foreach (keys %headerfuncs) {
my $fn = $_;
next if not defined $wikifuncs{$fn}; # don't have a page for that function, skip it.
@ -537,6 +546,8 @@ if ($copy_direction == 1) { # --copy-to-headers
my $addblank = 0;
my $str = '';
$headerfuncshasdoxygen{$fn} = 1; # Added/changed doxygen for this header.
$brief = dewikify($wikitype, $brief);
$brief =~ s/\A(.*?\.) /$1\n/; # \brief should only be one sentence, delimited by a period+space. Split if necessary.
my @briefsplit = split /\n/, $brief;
@ -632,8 +643,15 @@ if ($copy_direction == 1) { # --copy-to-headers
}
}
my $header = $headerfuncslocation{$fn};
my $contentsref = $headers{$header};
my $chunk = $headerfuncschunk{$fn};
my @lines = split /\n/, $str;
my $output = "/**\n";
my $addnewline = (($chunk > 0) && ($$contentsref[$chunk-1] ne '')) ? "\n" : '';
my $output = "$addnewline/**\n";
foreach (@lines) {
chomp;
s/\s*\Z//;
@ -647,9 +665,6 @@ if ($copy_direction == 1) { # --copy-to-headers
#print("$fn:\n$output\n\n");
my $header = $headerfuncslocation{$fn};
my $chunk = $headerfuncschunk{$fn};
my $contentsref = $headers{$header};
$$contentsref[$chunk] = $output;
#$$contentsref[$chunk+1] = $headerdecls{$fn};
@ -657,19 +672,36 @@ if ($copy_direction == 1) { # --copy-to-headers
}
foreach (keys %changed_headers) {
my $contentsref = $headers{$_};
my $path = "$incpath/$_.tmp";
my $header = $_;
# this is kinda inefficient, but oh well.
my @removelines = ();
foreach (keys %headerfuncslocation) {
my $fn = $_;
next if $headerfuncshasdoxygen{$fn};
next if $headerfuncslocation{$fn} ne $header;
# the index of the blank line we put before the function declaration in case we needed to replace it with new content from the wiki.
push @removelines, $headerfuncschunk{$fn};
}
my $contentsref = $headers{$header};
foreach (@removelines) {
delete $$contentsref[$_]; # delete DOES NOT RENUMBER existing elements!
}
my $path = "$incpath/$header.tmp";
open(FH, '>', $path) or die("Can't open '$path': $!\n");
foreach (@$contentsref) {
print FH "$_\n";
print FH "$_\n" if defined $_;
}
close(FH);
rename($path, "$incpath/$_") or die("Can't rename '$path' to '$incpath/$_': $!\n");
rename($path, "$incpath/$header") or die("Can't rename '$path' to '$incpath/$header': $!\n");
}
} elsif ($copy_direction == -1) { # --copy-to-wiki
foreach (keys %headerfuncs) {
my $fn = $_;
next if not $headerfuncshasdoxygen{$fn};
my $wikitype = defined $wikitypes{$fn} ? $wikitypes{$fn} : 'mediawiki'; # default to MediaWiki for new stuff FOR NOW.
die("Unexpected wikitype '$wikitype'\n") if (($wikitype ne 'mediawiki') and ($wikitype ne 'md'));
@ -678,6 +710,7 @@ if ($copy_direction == 1) { # --copy-to-headers
$wordwrap_mode = $wikitype;
my $raw = $headerfuncs{$fn}; # raw doxygen text with comment characters stripped from start/end and start of each line.
next if not defined $raw;
$raw =~ s/\A\s*\\brief\s+//; # Technically we don't need \brief (please turn on JAVADOC_AUTOBRIEF if you use Doxygen), so just in case one is present, strip it.
my @doxygenlines = split /\n/, $raw;