From 1c3a1e113914a749d71193da41feb0506dd595ab Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 16 May 2024 11:41:54 -0400
Subject: [PATCH] wikiheaders: Updated to latest, cleaned up category
documentation a little.
This documentation needs a LOT of work--maybe someday--but it's definitely not
_broken_ right now, which is good enough for now.
---
.wikiheaders-options | 4 +-
build-scripts/wikiheaders.pl | 310 +++++++++++++++++++++++++----------
include/SDL_atomic.h | 41 ++---
include/SDL_audio.h | 4 +-
include/SDL_bits.h | 4 +-
include/SDL_blendmode.h | 4 +-
include/SDL_clipboard.h | 2 +-
include/SDL_config.h | 4 +-
include/SDL_cpuinfo.h | 12 +-
include/SDL_egl.h | 7 +-
include/SDL_endian.h | 4 +-
include/SDL_error.h | 4 +-
include/SDL_events.h | 4 +-
include/SDL_filesystem.h | 4 +-
include/SDL_gamecontroller.h | 8 +-
include/SDL_gesture.h | 4 +-
include/SDL_guid.h | 9 +-
include/SDL_haptic.h | 34 ++--
include/SDL_hidapi.h | 77 ++++-----
include/SDL_hints.h | 20 +--
include/SDL_joystick.h | 24 +--
include/SDL_keyboard.h | 4 +-
include/SDL_keycode.h | 4 +-
include/SDL_loadso.h | 36 ++--
include/SDL_locale.h | 4 +-
include/SDL_log.h | 17 +-
include/SDL_main.h | 4 +-
include/SDL_metal.h | 5 +-
include/SDL_misc.h | 4 +-
include/SDL_mouse.h | 4 +-
include/SDL_mutex.h | 4 +-
include/SDL_opengl.h | 14 +-
include/SDL_opengles.h | 7 +-
include/SDL_opengles2.h | 7 +-
include/SDL_pixels.h | 4 +-
include/SDL_platform.h | 4 +-
include/SDL_power.h | 4 +-
include/SDL_quit.h | 22 +--
include/SDL_rect.h | 4 +-
include/SDL_render.h | 35 ++--
include/SDL_rwops.h | 10 +-
include/SDL_scancode.h | 4 +-
include/SDL_sensor.h | 5 +-
include/SDL_stdinc.h | 8 +-
include/SDL_surface.h | 4 +-
include/SDL_system.h | 4 +-
include/SDL_syswm.h | 24 ++-
include/SDL_thread.h | 4 +-
include/SDL_timer.h | 4 +-
include/SDL_touch.h | 4 +-
include/SDL_types.h | 7 +-
include/SDL_version.h | 4 +-
include/SDL_video.h | 4 +-
include/SDL_vulkan.h | 4 +-
include/begin_code.h | 12 +-
55 files changed, 496 insertions(+), 377 deletions(-)
diff --git a/.wikiheaders-options b/.wikiheaders-options
index 9e6716ac56633..eb8737519db05 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -19,6 +19,6 @@ wikiheaderfiletext = Defined in [%fname%](https://github.com/libsdl-org/SDL/blob
manpageheaderfiletext = Defined in %fname%
# All SDL_config_*.h headers are uncategorized, in case something slips in from them.
-# All SDL_test_* headers become "Test" categories, everything else just converts like SDL_audio.h -> Audio
+# All SDL_test_* headers become uncategorized, everything else just converts like SDL_audio.h -> Audio
# A handful of others we fix up in the header itself with /* WIKI CATEGORY: x */ comments.
-headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z/Test/; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();
+headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z//; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 185701b479dcf..2669e33a0fa98 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -16,7 +16,7 @@
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 $versionpatchregex = '\A\#define\s+SDL_PATCHLEVEL\s+(\d+)\Z';
+my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z';
my $mainincludefname = 'SDL.h';
my $selectheaderregex = '\ASDL.*?\.h\Z';
my $projecturl = 'https://libsdl.org/';
@@ -92,7 +92,7 @@
$readmesubdir = $val, next if $key eq 'readmesubdir';
$versionmajorregex = $val, next if $key eq 'versionmajorregex';
$versionminorregex = $val, next if $key eq 'versionminorregex';
- $versionpatchregex = $val, next if $key eq 'versionpatchregex';
+ $versionmicroregex = $val, next if $key eq 'versionmicroregex';
$versionfname = $val, next if $key eq 'versionfname';
$mainincludefname = $val, next if $key eq 'mainincludefname';
$selectheaderregex = $val, next if $key eq 'selectheaderregex';
@@ -622,7 +622,7 @@ sub usage {
my %headersymshasdoxygen = (); # $headersymshasdoxygen{"SDL_OpenAudio"} -> 1 if there was no existing doxygen for this function.
my %headersymstype = (); # $headersymstype{"SDL_OpenAudio"} -> 1 (function), 2 (macro), 3 (struct), 4 (enum), 5 (other typedef)
my %headersymscategory = (); # $headersymscategory{"SDL_OpenAudio"} -> 'Audio' ... this is set with a `/* WIKI CATEGEORY: Audio */` comment in the headers that sets it on all symbols until a new comment changes it. So usually, once at the top of the header file.
-
+my %headercategorydocs = (); # $headercategorydocs{"Audio"} -> (fake) symbol for this category's documentation. Undefined if not documented.
my %wikitypes = (); # contains string of wiki page extension, like $wikitypes{"SDL_OpenAudio"} == 'mediawiki'
my %wikisyms = (); # contains references to hash of strings, each string being the full contents of a section of a wiki page, like $wikisyms{"SDL_OpenAudio"}{"Remarks"}.
my %wikisectionorder = (); # contains references to array, each array item being a key to a wikipage section in the correct order, like $wikisectionorder{"SDL_OpenAudio"}[2] == 'Remarks'
@@ -710,6 +710,7 @@ sub print_undocumented_section {
my @contents = ();
my $ignoring_lines = 0;
my $header_comment = -1;
+ my $saw_category_doxygen = -1;
my $lineno = 0;
while (<FH>) {
chomp;
@@ -762,6 +763,8 @@ sub print_undocumented_section {
add_coverage_gap($_, $dent, $lineno) if ($header_comment == 0);
next;
} else { # Start of a doxygen comment, parse it out.
+ my $is_category_doxygen = 0;
+
@templines = ( $_ );
while (<FH>) {
chomp;
@@ -783,43 +786,76 @@ sub print_undocumented_section {
}
}
} else {
- s/\A\s*\*\s*//;
+ s/\A\s*\*\s*//; # Strip off the " * " at the start of the comment line.
+
+ # To add documentation to Category Pages, the rule is it has to
+ # be the first Doxygen comment in the header, and it must start with `# CategoryX`
+ # (otherwise we'll treat it as documentation for whatever's below it). `X` is
+ # the category name, which doesn't _necessarily_ have to match
+ # $current_wiki_category, but it probably should.
+ #
+ # For compatibility with Doxygen, if there's a `\file` here instead of
+ # `# CategoryName`, we'll accept it and use the $current_wiki_category if set.
+ if ($saw_category_doxygen == -1) {
+ $saw_category_doxygen = defined($current_wiki_category) && /\A\\file\s+/;
+ if ($saw_category_doxygen) {
+ $_ = "# Category$current_wiki_category";
+ } else {
+ $saw_category_doxygen = /\A\# Category/;
+ }
+ $is_category_doxygen = $saw_category_doxygen;
+ }
+
$str .= "$_\n";
}
}
- $decl = <FH>;
- $lineno++ if defined $decl;
- $decl = '' if not defined $decl;
- chomp($decl);
- if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC/) {
- $symtype = 1; # function declaration
- } elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) {
- $symtype = 1; # (forced-inline) function declaration
- } elsif ($decl =~ /\A\s*\#\s*define\s+/) {
- $symtype = 2; # macro
- } elsif ($decl =~ /\A\s*(typedef\s+|)(struct|union)/) {
- $symtype = 3; # struct or union
- } elsif ($decl =~ /\A\s*(typedef\s+|)enum/) {
- $symtype = 4; # enum
- } elsif ($decl =~ /\A\s*typedef\s+.*\Z/) {
- $symtype = 5; # other typedef
+ if ($is_category_doxygen) {
+ $str =~ s/\s*\Z//;
+ $decl = '';
+ $symtype = -1; # not a symbol at all.
} else {
- #print "Found doxygen but no function sig:\n$str\n\n";
- foreach (@templines) {
- push @contents, $_;
- add_coverage_gap($_, $dent, $lineno);
+ $decl = <FH>;
+ $lineno++ if defined $decl;
+ $decl = '' if not defined $decl;
+ chomp($decl);
+ if ($decl =~ /\A\s*extern\s+(SDL_DEPRECATED\s+|)(SDLMAIN_)?DECLSPEC/) {
+ $symtype = 1; # function declaration
+ } elsif ($decl =~ /\A\s*SDL_FORCE_INLINE/) {
+ $symtype = 1; # (forced-inline) function declaration
+ } elsif ($decl =~ /\A\s*\#\s*define\s+/) {
+ $symtype = 2; # macro
+ } elsif ($decl =~ /\A\s*(typedef\s+|)(struct|union)/) {
+ $symtype = 3; # struct or union
+ } elsif ($decl =~ /\A\s*(typedef\s+|)enum/) {
+ $symtype = 4; # enum
+ } elsif ($decl =~ /\A\s*typedef\s+.*\Z/) {
+ $symtype = 5; # other typedef
+ } else {
+ #print "Found doxygen but no function sig:\n$str\n\n";
+ foreach (@templines) {
+ push @contents, $_;
+ add_coverage_gap($_, $dent, $lineno);
+ }
+ push @contents, $decl;
+ add_coverage_gap($decl, $dent, $lineno);
+ next;
}
- push @contents, $decl;
- add_coverage_gap($decl, $dent, $lineno);
- next;
}
}
my @decllines = ( $decl );
my $sym = '';
- if ($symtype == 1) { # a function
+ if ($symtype == -1) { # category documentation with no symbol attached.
+ @decllines = ();
+ if ($str =~ /^#\s*Category(.*?)\s*$/m) {
+ $sym = "[category documentation] $1"; # make a fake, unique symbol that's not valid C.
+ } else {
+ die("Unexpected category documentation line '$str' in '$incpath/$dent' ...?");
+ }
+ $headercategorydocs{$current_wiki_category} = $sym;
+ } elsif ($symtype == 1) { # a function
my $is_forced_inline = ($decl =~ /\A\s*SDL_FORCE_INLINE/);
if ($is_forced_inline) {
@@ -1128,7 +1164,7 @@ sub print_undocumented_section {
if ($has_doxygen) {
print STDERR "WARNING: Symbol '$sym' appears to be documented in multiple locations. Only keeping the first one we saw!\n";
}
- push @contents, join("\n", @decllines); # just put the existing declation in as-is.
+ push @contents, join("\n", @decllines) if (scalar(@decllines) > 0); # just put the existing declation in as-is.
}
}
@@ -1141,7 +1177,7 @@ sub print_undocumented_section {
$headersymshasdoxygen{$sym} = $has_doxygen;
$headersymstype{$sym} = $symtype;
push @contents, join("\n", @templines);
- push @contents, join("\n", @decllines);
+ push @contents, join("\n", @decllines) if (scalar(@decllines) > 0);
}
}
@@ -1168,11 +1204,41 @@ sub print_undocumented_section {
# Ignore FrontPage.
next if $sym eq 'FrontPage';
- # Ignore "Category*" pages.
- next if ($sym =~ /\ACategory/);
-
open(FH, '<', "$wikipath/$dent") or die("Can't open '$wikipath/$dent': $!\n");
+ if ($sym =~ /\ACategory(.*?)\Z/) { # Special case for Category pages.
+ # Find the end of the category documentation in the existing file and append everything else to the new file.
+ my $cat = $1;
+ my $docstr = '';
+ my $notdocstr = '';
+ my $docs = 1;
+ while (<FH>) {
+ chomp;
+ if ($docs) {
+ $docs = 0 if /\A\-\-\-\-\Z/; # Hit a footer? We're done.
+ $docs = 0 if /\A<!\-\-/; # Hit an HTML comment? We're done.
+ }
+ if ($docs) {
+ $docstr .= "$_\n";
+ } else {
+ $notdocstr .= "$_\n";
+ }
+ }
+ close(FH);
+
+ $docstr =~ s/\s*\Z//;
+
+ $sym = "[category documentation] $cat"; # make a fake, unique symbol that's not valid C.
+ $wikitypes{$sym} = $type;
+ my %sections = ();
+ $sections{'Remarks'} = $docstr;
+ $sections{'[footer]'} = $notdocstr;
+ $wikisyms{$sym} = \%sections;
+ my @section_order = ( 'Remarks', '[footer]' );
+ $wikisectionorder{$sym} = \@section_order;
+ next;
+ }
+
my $current_section = '[start]';
my @section_order = ( $current_section );
my %sections = ();
@@ -1325,7 +1391,9 @@ sub print_undocumented_section {
my $params = undef;
my $paramstr = undef;
- if (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef.
+ if ($symtype == -1) { # category documentation block.
+ # nothing to be done here.
+ } elsif (($symtype == 1) || (($symtype == 5))) { # we'll assume a typedef (5) with a \param is a function pointer typedef.
$params = $sectionsref->{'Function Parameters'};
$paramstr = '\param';
} elsif ($symtype == 2) {
@@ -1520,7 +1588,7 @@ sub print_undocumented_section {
}
$output .= " */";
- #print("$sym:\n$output\n\n");
+ #print("$sym:\n[$output]\n\n");
$$contentsref[$chunk] = $output;
#$$contentsref[$chunk+1] = $headerdecls{$sym};
@@ -1569,6 +1637,7 @@ sub print_undocumented_section {
closedir(DH);
}
}
+
} elsif ($copy_direction == -1) { # --copy-to-wiki
if (defined $changeformat) {
@@ -1579,6 +1648,7 @@ sub print_undocumented_section {
foreach (keys %headersyms) {
my $sym = $_;
next if not $headersymshasdoxygen{$sym};
+ next if $sym =~ /\A\[category documentation\]/; # not real symbols, we handle this elsewhere.
my $symtype = $headersymstype{$sym};
my $origwikitype = defined $wikitypes{$sym} ? $wikitypes{$sym} : 'md'; # default to MarkDown for new stuff.
my $wikitype = (defined $changeformat) ? $changeformat : $origwikitype;
@@ -1812,7 +1882,7 @@ sub print_undocumented_section {
$sections{'Function Parameters'} = $str;
}
- my $path = "$wikipath/$_.${wikitype}.tmp";
+ my $path = "$wikipath/$sym.${wikitype}.tmp";
open(FH, '>', $path) or die("Can't open '$path': $!\n");
my $sectionsref = $wikisyms{$sym};
@@ -1848,44 +1918,46 @@ sub print_undocumented_section {
}
}
- my $footer = $$sectionsref{'[footer]'};
-
- my $symtypename;
- if ($symtype == 1) {
- $symtypename = 'Function';
- } elsif ($symtype == 2) {
- $symtypename = 'Macro';
- } elsif ($symtype == 3) {
- $symtypename = 'Struct';
- } elsif ($symtype == 4) {
- $symtypename = 'Enum';
- } elsif ($symtype == 5) {
- $symtypename = 'Datatype';
- } else {
- die("Unexpected symbol type $symtype!");
- }
+ if ($symtype != -1) { # Don't do these in category documentation block
+ my $footer = $$sectionsref{'[footer]'};
- my $symcategory = $headersymscategory{$sym};
- if ($wikitype eq 'mediawiki') {
- $footer =~ s/\[\[CategoryAPI\]\],?\s*//g;
- $footer =~ s/\[\[CategoryAPI${symtypename}\]\],?\s*//g;
- $footer =~ s/\[\[Category${symcategory}\]\],?\s*//g if defined $symcategory;
- $footer = "[[CategoryAPI]], [[CategoryAPI$symtypename]]" . (defined $symcategory ? ", [[Category$symcategory]]" : '') . (($footer eq '') ? "\n" : ", $footer");
- } elsif ($wikitype eq 'md') {
- $footer =~ s/\[CategoryAPI\]\(CategoryAPI\),?\s*//g;
- $footer =~ s/\[CategoryAPI${symtypename}\]\(CategoryAPI${symtypename}\),?\s*//g;
- $footer =~ s/\[Category${symcategory}\]\(Category${symcategory}\),?\s*//g if defined $symcategory;
- $footer = "[CategoryAPI](CategoryAPI), [CategoryAPI$symtypename](CategoryAPI$symtypename)" . (defined $symcategory ? ", [Category$symcategory](Category$symcategory)" : '') . (($footer eq '') ? '' : ', ') . $footer;
- } else { die("Unexpected wikitype '$wikitype'"); }
- $$sectionsref{'[footer]'} = $footer;
+ my $symtypename;
+ if ($symtype == 1) {
+ $symtypename = 'Function';
+ } elsif ($symtype == 2) {
+ $symtypename = 'Macro';
+ } elsif ($symtype == 3) {
+ $symtypename = 'Struct';
+ } elsif ($symtype == 4) {
+ $symtypename = 'Enum';
+ } elsif ($symtype == 5) {
+ $symtypename = 'Datatype';
+ } else {
+ die("Unexpected symbol type $symtype!");
+ }
- if (defined $wikipreamble) {
- my $wikified_preamble = wikify($wikitype, $wikipreamble);
+ my $symcategory = $headersymscategory{$sym};
if ($wikitype eq 'mediawiki') {
- print FH "====== $wikified_preamble ======\n";
+ $footer =~ s/\[\[CategoryAPI\]\],?\s*//g;
+ $footer =~ s/\[\[CategoryAPI${symtypename}\]\],?\s*//g;
+ $footer =~ s/\[\[Category${symcategory}\]\],?\s*//g if defined $symcategory;
+ $footer = "[[CategoryAPI]], [[CategoryAPI$symtypename]]" . (defined $symcategory ? ", [[Category$symcategory]]" : '') . (($footer eq '') ? "\n" : ", $footer");
} elsif ($wikitype eq 'md') {
- print FH "###### $wikified_preamble\n";
+ $footer =~ s/\[CategoryAPI\]\(CategoryAPI\),?\s*//g;
+ $footer =~ s/\[CategoryAPI${symtypename}\]\(CategoryAPI${symtypename}\),?\s*//g;
+ $footer =~ s/\[Category${symcategory}\]\(Category${symcategory}\),?\s*//g if defined $symcategory;
+ $footer = "[CategoryAPI](CategoryAPI), [CategoryAPI$symtypename](CategoryAPI$symtypename)" . (defined $symcategory ? ", [Category$symcategory](Category$symcategory)" : '') . (($footer eq '') ? '' : ', ') . $footer;
} else { die("Unexpected wikitype '$wikitype'"); }
+ $$sectionsref{'[footer]'} = $footer;
+
+ if (defined $wikipreamble) {
+ my $wikified_preamble = wikify($wikitype, $wikipreamble);
+ if ($wikitype eq 'mediawiki') {
+ print FH "====== $wikified_preamble ======\n";
+ } elsif ($wikitype eq 'md') {
+ print FH "###### $wikified_preamble\n";
+ } else { die("Unexpected wikitype '$wikitype'"); }
+ }
}
my $prevsectstr = '';
@@ -1925,11 +1997,13 @@ sub print_undocumented_section {
}
}
- if ($wikitype eq 'mediawiki') {
- print FH "\n== $sectname ==\n\n";
- } elsif ($wikitype eq 'md') {
- print FH "\n## $sectname\n\n";
- } else { die("Unexpected wikitype '$wikitype'"); }
+ if ($symtype != -1) { # Not for category documentation block
+ if ($wikitype eq 'mediawiki') {
+ print FH "\n== $sectname ==\n\n";
+ } elsif ($wikitype eq 'md') {
+ print FH "\n## $sectname\n\n";
+ } else { die("Unexpected wikitype '$wikitype'"); }
+ }
}
my $sectstr = defined $sections{$sect} ? $sections{$sect} : $$sectionsref{$sect};
@@ -1973,6 +2047,74 @@ sub print_undocumented_section {
close(FH);
}
+ # Write out Category pages...
+ foreach (keys %headercategorydocs) {
+ my $cat = $_;
+ my $sym = $headercategorydocs{$cat}; # fake symbol
+ my $raw = $headersyms{$sym}; # raw doxygen text with comment characters stripped from start/end and start of each line.
+ my $wikitype = defined($wikitypes{$sym}) ? $wikitypes{$sym} : 'md';
+ my $path = "$wikipath/Category$cat.$wikitype";
+
+ $raw = wordwrap(wikify($wikitype, $raw));
+
+ my $tmppath = "$path.tmp";
+ open(FH, '>', $tmppath) or die("Can't open '$tmppath': $!\n");
+ print FH "$raw\n\n";
+
+ if (! -f $path) { # Doesn't exist at all? Write out a template file.
+ # If writing from scratch, it's always a Markdown file.
+ die("Unexpected wikitype '$wikitype'!") if $wikitype ne 'md';
+ print FH <<__EOF__
+
+<!-- END CATEGORY DOCUMENTATION -->
+
+## Functions
+
+<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
+<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIFunction -->
+<!-- END CATEGORY LIST -->
+
+## Datatypes
+
+<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
+<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIDatatype -->
+<!-- END CATEGORY LIST -->
+
+## Structs
+
+<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
+<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIStruct -->
+<!-- END CATEGORY LIST -->
+
+## Enums
+
+<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
+<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIEnum -->
+<!-- END CATEGORY LIST -->
+
+## Macros
+
+<!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. -->
+<!-- BEGIN CATEGORY LIST: Category$cat, CategoryAPIMacro -->
+<!-- END CATEGORY LIST -->
+
+----
+[CategoryAPICategory](CategoryAPICategory)
+
+__EOF__
+;
+ } else {
+ my $endstr = $wikisyms{$sym}->{'[footer]'};
+ if (defined($endstr)) {
+ print FH $endstr;
+ }
+ }
+
+ close(FH);
+ rename($tmppath, $path) or die("Can't rename '$tmppath' to '$path': $!\n");
+ }
+
+ # Write out READMEs...
if (defined $readmepath) {
if ( -d $readmepath ) {
mkdir($wikireadmepath); # just in case
@@ -2036,23 +2178,24 @@ sub print_undocumented_section {
open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n");
my $majorver = 0;
my $minorver = 0;
- my $patchver = 0;
+ my $microver = 0;
while (<FH>) {
chomp;
if (/$versionmajorregex/) {
$majorver = int($1);
} elsif (/$versionminorregex/) {
$minorver = int($1);
- } elsif (/$versionpatchregex/) {
- $patchver = int($1);
+ } elsif (/$versionmicroregex/) {
+ $microver = int($1);
}
}
close(FH);
- my $fullversion = "$majorver.$minorver.$patchver";
+ my $fullversion = "$majorver.$minorver.$microver";
foreach (keys %headersyms) {
my $sym = $_;
next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it.
+ next if $sym =~ /\A\[category documentation\]/; # not real symbols
my $symtype = $headersymstype{$sym};
my $wikitype = $wikitypes{$sym};
my $sectionsref = $wikisyms{$sym};
@@ -2318,19 +2461,19 @@ sub print_undocumented_section {
open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n");
my $majorver = 0;
my $minorver = 0;
- my $patchver = 0;
+ my $microver = 0;
while (<FH>) {
chomp;
if (/$versionmajorregex/) {
$majorver = int($1);
} elsif (/$versionminorregex/) {
$minorver = int($1);
- } elsif (/$versionpatchregex/) {
- $patchver = int($1);
+ } elsif (/$versionmicroregex/) {
+ $microver = int($1);
}
}
close(FH);
- my $fullversion = "$majorver.$minorver.$patchver";
+ my $fullversion = "$majorver.$minorver.$microver";
my $latex_fname = "$srcpath/$projectshortname.tex";
my $latex_tmpfname = "$latex_fname.tmp";
@@ -2369,7 +2512,7 @@ sub print_undocumented_section {
\\begin{document}
\\frontmatter
-\\title{$projectfullname $majorver.$minorver.$patchver Reference Manual}
+\\title{$projectfullname $majorver.$minorver.$microver Reference Manual}
\\author{The $projectshortname Developers}
\\maketitle
@@ -2399,6 +2542,7 @@ sub print_undocumented_section {
foreach (@headersymskeys) {
my $sym = $_;
next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it.
+ next if $sym =~ /\A\[category documentation\]/; # not real symbols.
my $symtype = $headersymstype{$sym};
my $wikitype = $wikitypes{$sym};
my $sectionsref = $wikisyms{$sym};
diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h
index 79ec2006c77ce..d8cb3c0dafaba 100644
--- a/include/SDL_atomic.h
+++ b/include/SDL_atomic.h
@@ -20,38 +20,29 @@
*/
/**
- * \file SDL_atomic.h
+ * # CategoryAtomic
*
* Atomic operations.
*
- * IMPORTANT:
- * If you are not an expert in concurrent lockless programming, you should
- * only be using the atomic lock and reference counting functions in this
- * file. In all other cases you should be protecting your data structures
- * with full mutexes.
+ * IMPORTANT: If you are not an expert in concurrent lockless programming, you
+ * should not be using any functions in this file. You should be protecting
+ * your data structures with full mutexes instead.
*
- * The list of "safe" functions to use are:
- * SDL_AtomicLock()
- * SDL_AtomicUnlock()
- * SDL_AtomicIncRef()
- * SDL_AtomicDecRef()
+ * ***Seriously, here be dragons!***
*
- * Seriously, here be dragons!
- * ^^^^^^^^^^^^^^^^^^^^^^^^^^^
- *
- * You can find out a little more about lockless programming and the
- * subtle issues that can arise here:
- * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx
+ * You can find out a little more about lockless programming and the subtle
+ * issues that can arise here:
+ * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming
*
* There's also lots of good information here:
- * http://www.1024cores.net/home/lock-free-algorithms
- * http://preshing.com/
- *
- * These operations may or may not actually be implemented using
- * processor specific atomic operations. When possible they are
- * implemented as true processor specific atomic operations. When that
- * is not possible the are implemented using locks that *do* use the
- * available atomic operations.
+ *
+ * - https://www.1024cores.net/home/lock-free-algorithms
+ * - https://preshing.com/
+ *
+ * These operations may or may not actually be implemented using processor
+ * specific atomic operations. When possible they are implemented as true
+ * processor specific atomic operations. When that is not possible the are
+ * implemented using locks that *do* use the available atomic operations.
*
* All of the atomic operations that modify memory are full memory barriers.
*/
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 5f5d681865d3c..e09a37554f29f 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -22,9 +22,9 @@
/* !!! FIXME: several functions in here need Doxygen comments. */
/**
- * \file SDL_audio.h
+ * # CategoryAudio
*
- * Access to the raw audio mixing buffer for the SDL library.
+ * Access to the raw audio mixing buffer for the SDL library.
*/
#ifndef SDL_audio_h_
diff --git a/include/SDL_bits.h b/include/SDL_bits.h
index 77f258804e2e7..0b22131c314a4 100644
--- a/include/SDL_bits.h
+++ b/include/SDL_bits.h
@@ -20,9 +20,9 @@
*/
/**
- * \file SDL_bits.h
+ * # CategoryBits
*
- * Functions for fiddling with bits and bitmasks.
+ * Functions for fiddling with bits and bitmasks.
*/
#ifndef SDL_bits_h_
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 5ac3e7d0c9453..75d21fe631797 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -20,9 +20,9 @@
*/
/**
- * \file SDL_blendmode.h
+ * # CategoryBlendmode
*
- * Header file declaring the SDL_BlendMode enumeration
+ * Header file declaring the SDL_BlendMode enumeration
*/
#ifndef SDL_blendmode_h_
diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h
index bd4b044c6dd4e..3a02774615ab0 100644
--- a/include/SDL_clipboard.h
+++ b/include/SDL_clipboard.h
@@ -20,7 +20,7 @@
*/
/**
- * \file SDL_clipboard.h
+ * # CategoryClipboard
*
* Include file for SDL clipboard handling
*/
diff --git a/include/SDL_config.h b/include/SDL_config.h
index 49605b1e8a8c1..dde6edd77b3c9 100644
--- a/include/SDL_config.h
+++ b/include/SDL_config.h
@@ -24,9 +24,7 @@
#include "SDL_platform.h"
-/**
- * \file SDL_config.h
- */
+/* WIKI CATEGORY: - */
/* Add any platform that doesn't build using the configure system. */
#if defined(__WIN32__)
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index e8ac85dab6d73..b9d0958ff026f 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -19,10 +19,16 @@
3. This notice may not be removed or altered from any source distribution.
*/
+/* WIKI CATEGORY: CPUInfo */
+
/**
- * \file SDL_cpuinfo.h
+ * # CategoryCPUInfo
+ *
+ * CPU feature detection for SDL.
*
- * CPU feature detection for SDL.
+ * These functions are largely concerned with reporting if the system has
+ * access to various SIMD instruction sets, but also has other important info
+ * to share, such as number of logical CPU cores.
*/
#ifndef SDL_cpuinfo_h_
@@ -30,8 +36,6 @@
#include "SDL_stdinc.h"
-/* WIKI CATEGORY: CPUInfo */
-
/* Need to do this here because intrin.h has C++ code in it */
/* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */
#if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64))
diff --git a/include/SDL_egl.h b/include/SDL_egl.h
index a4276e6810b2f..84c1f1b31f496 100644
--- a/include/SDL_egl.h
+++ b/include/SDL_egl.h
@@ -19,11 +19,10 @@
3. This notice may not be removed or altered from
(Patch may be truncated, please check the link at the top of this post.)