SDL: wikiheaders: bridge wiki Category docs to the headers!

From 5e6d85b8f0fee45571f9374886bb4e1898269289 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 16 May 2024 10:44:37 -0400
Subject: [PATCH] wikiheaders: bridge wiki Category docs to the headers!

Did an initial cleanup on the headers and wrote a few pieces of documentation,
but this needs more work to fill out the documentation.
---
 .wikiheaders-options                |   4 +-
 build-scripts/wikiheaders.pl        | 288 +++++++++++++++++++++-------
 include/SDL3/SDL_assert.h           |  36 +++-
 include/SDL3/SDL_atomic.h           |  32 ++--
 include/SDL3/SDL_audio.h            |  47 +++--
 include/SDL3/SDL_begin_code.h       |   8 +-
 include/SDL3/SDL_bits.h             |   4 +-
 include/SDL3/SDL_blendmode.h        |   6 +-
 include/SDL3/SDL_camera.h           |   9 +-
 include/SDL3/SDL_clipboard.h        |   7 +-
 include/SDL3/SDL_close_code.h       |   8 +-
 include/SDL3/SDL_copying.h          |   6 +-
 include/SDL3/SDL_cpuinfo.h          |   8 +-
 include/SDL3/SDL_dialog.h           |   6 +
 include/SDL3/SDL_egl.h              |   6 +-
 include/SDL3/SDL_endian.h           |   4 +-
 include/SDL3/SDL_error.h            |   4 +-
 include/SDL3/SDL_events.h           |   4 +-
 include/SDL3/SDL_filesystem.h       |   4 +-
 include/SDL3/SDL_gamepad.h          |  44 +++--
 include/SDL3/SDL_guid.h             |   5 +-
 include/SDL3/SDL_haptic.h           |  25 +--
 include/SDL3/SDL_hidapi.h           |  73 +++----
 include/SDL3/SDL_hints.h            |  20 +-
 include/SDL3/SDL_init.h             |   5 +-
 include/SDL3/SDL_intrin.h           |   4 +-
 include/SDL3/SDL_iostream.h         |  11 +-
 include/SDL3/SDL_joystick.h         |  25 ++-
 include/SDL3/SDL_keyboard.h         |   4 +-
 include/SDL3/SDL_keycode.h          |   4 +-
 include/SDL3/SDL_loadso.h           |  32 ++--
 include/SDL3/SDL_locale.h           |   4 +-
 include/SDL3/SDL_log.h              |  17 +-
 include/SDL3/SDL_main.h             |  26 ++-
 include/SDL3/SDL_messagebox.h       |   6 +
 include/SDL3/SDL_metal.h            |   4 +-
 include/SDL3/SDL_misc.h             |   4 +-
 include/SDL3/SDL_mouse.h            |   4 +-
 include/SDL3/SDL_mutex.h            |   4 +-
 include/SDL3/SDL_oldnames.h         |   6 +-
 include/SDL3/SDL_opengl.h           |  14 +-
 include/SDL3/SDL_opengles.h         |   7 +-
 include/SDL3/SDL_opengles2.h        |   7 +-
 include/SDL3/SDL_pen.h              |  28 +--
 include/SDL3/SDL_pixels.h           |   6 +
 include/SDL3/SDL_platform.h         |   5 +-
 include/SDL3/SDL_platform_defines.h |   8 +-
 include/SDL3/SDL_power.h            |   4 +-
 include/SDL3/SDL_properties.h       |   5 +-
 include/SDL3/SDL_rect.h             |   5 +-
 include/SDL3/SDL_render.h           |  36 ++--
 include/SDL3/SDL_revision.h         |  12 +-
 include/SDL3/SDL_scancode.h         |   4 +-
 include/SDL3/SDL_sensor.h           |   4 +-
 include/SDL3/SDL_stdinc.h           |   8 +-
 include/SDL3/SDL_storage.h          |   4 +-
 include/SDL3/SDL_surface.h          |   4 +-
 include/SDL3/SDL_system.h           |   4 +-
 include/SDL3/SDL_test_assert.h      |   2 -
 include/SDL3/SDL_test_crc32.h       |   2 -
 include/SDL3/SDL_test_fuzzer.h      |   3 -
 include/SDL3/SDL_thread.h           |   4 +-
 include/SDL3/SDL_time.h             |   4 +-
 include/SDL3/SDL_timer.h            |   4 +-
 include/SDL3/SDL_touch.h            |   4 +-
 include/SDL3/SDL_version.h          |   5 +-
 include/SDL3/SDL_video.h            |   4 +-
 include/SDL3/SDL_vulkan.h           |   4 +-
 68 files changed, 624 insertions(+), 395 deletions(-)

diff --git a/.wikiheaders-options b/.wikiheaders-options
index 2f74ee75044d7..a6c85fb985f5a 100644
--- a/.wikiheaders-options
+++ b/.wikiheaders-options
@@ -18,6 +18,6 @@ wikipreamble = (This is the documentation for SDL3, which is under heavy develop
 wikiheaderfiletext = Defined in [<SDL3/%fname%>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/%fname%)
 manpageheaderfiletext = Defined in SDL3/%fname%
 
-# All SDL_test_* headers become "Test" categories, everything else just converts like SDL_audio.h -> Audio
+# All SDL_test_* headers become undefined categories, 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_test_.*?\.h\Z/Test/; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();
+headercategoryeval = s/\ASDL_test_?.*?\.h\Z//; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst();
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 6e4219702fb52..2669e33a0fa98 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -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
@@ -2053,6 +2195,7 @@ sub print_undocumented_section {
     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};
@@ -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/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index a583599443809..4254d0f7e6e6c 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -20,9 +20,39 @@
 */
 
 /**
- *  \file SDL_assert.h
- *
- *  Header file for assertion SDL API functions
+ * # CategoryAssert
+ *
+ * A helpful assertion macro!
+ *
+ * SDL assertions operate like your usual `assert` macro, but with some added
+ * features:
+ *
+ * - It uses a trick with the `sizeof` operator, so disabled assertions
+ *   vaporize out of the compiled code, but variables only referenced in the
+ *   assertion won't trigger compiler warnings about being unused.
+ * - It is safe to use with a dangling-else: `if (x) SDL_assert(y); else
+ *   do_something();`
+ * - It works the same everywhere, instead of counting on various platforms'
+ *   compiler and C runtime to behave.
+ * - It provides multiple levels of assertion (SDL_assert, SDL_assert_release,
+ *   SDL_assert_paranoid) instead of a single all-or-nothing option.
+ * - It offers a variety of responses when an assertion fails (retry, trigger
+ *   the debugger, abort the program, ignore the failure once, ignore it for
+ *   the rest of the program's run).
+ * - It tries to show the user a dialog by default, if possible, but the app
+ *   can provide a callback to handle assertion failures however they like.
+ * - It lets failed assertions be retried. Perhaps you had a network failure
+ *   and just want to retry the test after plugging your network cable back
+ *   in? You can.
+ * - It lets the user ignore an assertion failure, if there's a harmless
+ *   problem that one can continue past.
+ * - It lets the user mark an assertion as ignored for the rest of the
+ *   program's run; if there's a harmless problem that keeps popping up.
+ * - It provides statistics and data on all failed assertions to the app.
+ * - It allows the default assertion handler to be controlled with environment
+ *   variables, in case an automated script needs to control it.
+ *
+ * To use it: do a debug build and just sprinkle around tests check your code!
  */
 
 #ifndef SDL_assert_h_
diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index df1160e260b86..9d2c27b8e3a9e 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/include/SDL3/SDL_atomic.h
@@ -20,31 +20,29 @@
 */
 
 /**
- * \file SDL_atomic.h
+ * # CategoryAtomic
  *
  * Atomic operations.
  *
- * 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.
+ * 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.
  *
- * 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:
+ * 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/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index f5c1a8568a663..a055a6c03e15e 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -20,11 +20,43 @@
 */
 
 /**
- *  \file SDL_audio.h
+ * # CategoryAudio
  *
- *  Audio functionality for the SDL library.
+ * Audio functionality for the SDL library.
+ *
+ * All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play
+ * or record audio, convert it, stream it, buffer it, or mix it, you're going
+ * to be passing it through an audio stream.
+ *
+ * Audio streams are quite flexible; they can accept any amount of data at a
+ * time, in any supported format, and output it as needed in any other format,
+ * even if the data format changes on either side halfway through.
+ *
+ * An app opens an audio device and binds any number of audio streams to it,
+ * feeding more data to it as available. When the devices needs more data, it
+ * will pull it from all bound streams and mix them together for playback.
+ *
+ * Audio streams can also use an app-provided callback to supply data
+ * on-demand, which maps pretty closely to the SDL2 audio model.
+ *
+ * SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO
+ * if you aren't reading from a file) as a basic means to load sound data into
+ * your program.
+ *
+ * For multi-channel audio, the default SDL channel mapping is:
+ *
+ * ```
+ * 2:  FL  FR                          (stereo)
+ * 3:  FL  FR LFE                      (2.1 surround)
+ * 4:  FL  FR  BL  BR                  (quad)
+ * 5:  FL  FR LFE  BL  BR              (4.1 surround)
+ * 6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
+ * 7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
+ * 8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
+ * ```
  */
 
+
 #ifndef SDL_audio_h_
 #define SDL_audio_h_
 
@@ -42,17 +74,6 @@
 extern "C" {
 #endif
 
-/*
- *  For multi-channel audio, the default SDL channel mapping is:
- *  2:  FL  FR                          (stereo)
- *  3:  FL  FR LFE                      (2.1 surround)
- *  4:  FL  FR  BL  BR                  (quad)
- *  5:  FL  FR LFE  BL  BR              (4.1 surround)
- *  6:  FL  FR  FC LFE  SL  SR          (5.1 surround - last two can also be BL BR)
- *  7:  FL  FR  FC LFE  BC  SL  SR      (6.1 surround)
- *  8:  FL  FR  FC LFE  BL  BR  SL  SR  (7.1 surround)
- */
-
 /**
  * Audio format flags.
  *
diff --git a/include/SDL3/SDL_begin_code.h b/include/SDL3/SDL_begin_code.h
index e4ff27a11f7c0..e2a7ce48a39b1 100644
--- a/include/SDL3/SDL_begin_code.h
+++ b/include/SDL3/SDL_begin_code.h
@@ -22,11 +22,9 @@
 /* WIKI CATEGORY: BeginCode */
 
 /**
- *  \file SDL_begin_code.h
- *
- *  This file sets things up for C dynamic library function definitions,
- *  static inlined functions, and structures aligned at 4-byte alignment.
- *  If you don't like ugly C preprocessor code, don't look at this file. :)
+ * SDL_begin_code.h sets things up for C dynamic library function definitions,
+ * static inlined functi

(Patch may be truncated, please check the link at the top of this post.)