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

@@ -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();

build-scripts/wikiheaders.pl

@@ -622,7 +622,7 @@ my %headersymschunk = ();   # $headersymschunk{"SDL_OpenAudio"} -> offset in arr
 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 @@ while (my $d = readdir(DH)) {
     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 @@ while (my $d = readdir(DH)) {
             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 @@ while (my $d = readdir(DH)) {
                         }
                     }
                 } 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 @@ while (my $d = readdir(DH)) {
                 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 @@ while (my $d = readdir(DH)) {
             $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 @@ while (my $d = readdir(DH)) {
     # 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 @@ if ($copy_direction == 1) {  # --copy-to-headers
         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 @@ if ($copy_direction == 1) {  # --copy-to-headers
         }
         $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 @@ if ($copy_direction == 1) {  # --copy-to-headers
             closedir(DH);
         }
     }
+
 } elsif ($copy_direction == -1) { # --copy-to-wiki
 
     if (defined $changeformat) {
@@ -1579,6 +1648,7 @@ if ($copy_direction == 1) {  # --copy-to-headers
     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 @@ if ($copy_direction == 1) {  # --copy-to-headers
             $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 @@ if ($copy_direction == 1) {  # --copy-to-headers
             }
         }
 
-        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 @@ if ($copy_direction == 1) {  # --copy-to-headers
                     }
                 }
 
-                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 @@ if ($copy_direction == 1) {  # --copy-to-headers
         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 @@ if ($copy_direction == 1) {  # --copy-to-headers
     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 @@ __EOF__
     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};

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_

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.
  */

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.
  *

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 functions, and structures aligned at 4-byte alignment.
+ * If you don't like ugly C preprocessor code, don't look at this file. :)
  */
 
 /* This shouldn't be nested -- included it around code only. */

include/SDL3/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_

include/SDL3/SDL_blendmode.h

@@ -20,9 +20,11 @@
 */
 
 /**
- *  \file SDL_blendmode.h
+ * # CategoryBlendmode
  *
- *  Header file declaring the SDL_BlendMode enumeration
+ * Blend modes decide how two colors will mix together. There are both
+ * standard modes for basic needs and a means to create custom modes,
+ * dictating what sort of math to do what on what color components.
  */
 
 #ifndef SDL_blendmode_h_

include/SDL3/SDL_camera.h

@@ -20,9 +20,14 @@
 */
 
 /**
- *  \file SDL_camera.h
+ * # CategoryCamera
  *
- *  Video Capture for the SDL library.
+ * Video capture for the SDL library.
+ *
+ * This API lets apps read input from video sources, like webcams. Camera
+ * devices can be enumerated, queried, and opened. Once opened, it will
+ * provide SDL_Surface objects as new frames of video come in. These surfaces
+ * can be uploaded to an SDL_Texture or processed as pixels in memory.
  */
 
 #ifndef SDL_camera_h_

include/SDL3/SDL_clipboard.h

@@ -20,9 +20,12 @@
 */
 
 /**
- * \file SDL_clipboard.h
+ * # CategoryClipboard
  *
- * Include file for SDL clipboard handling
+ * SDL provides access to the system clipboard, both for reading information
+ * from other processes and publishing information of its own.
+ *
+ * This is not just text! SDL apps can access and publish data by mimetype.
  */
 
 #ifndef SDL_clipboard_h_

include/SDL3/SDL_close_code.h

@@ -19,11 +19,9 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_close_code.h
- *
- *  This file reverses the effects of SDL_begin_code.h and should be included
- *  after you finish any function and structure declarations in your headers
+/*
+ * This file reverses the effects of SDL_begin_code.h and should be included
+ * after you finish any function and structure declarations in your headers
  */
 
 #ifndef SDL_begin_code_h

include/SDL3/SDL_copying.h

@@ -19,8 +19,4 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_copying.h
- *
- *  Header file containing SDL's license.
- */
+/* Header file containing SDL's license. */

include/SDL3/SDL_cpuinfo.h

@@ -22,9 +22,13 @@
 /* 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 system RAM size and number of logical CPU cores.
  */
 
 #ifndef SDL_cpuinfo_h_

include/SDL3/SDL_dialog.h

@@ -19,6 +19,12 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/**
+ * # CategoryDialog
+ *
+ * File dialog support.
+ */
+
 #ifndef SDL_dialog_h_
 #define SDL_dialog_h_
 

include/SDL3/SDL_egl.h

@@ -19,10 +19,8 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_egl.h
- *
- *  This is a simple file to encapsulate the EGL API headers.
+/*
+ * This is a simple file to encapsulate the EGL API headers.
  */
 
 #include <SDL3/SDL_platform_defines.h>

include/SDL3/SDL_endian.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_endian.h
+ * # CategoryEndian
  *
- *  Functions for reading and writing endian-specific values
+ * Functions for reading and writing endian-specific values.
  */
 
 #ifndef SDL_endian_h_

include/SDL3/SDL_error.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_error.h
+ * # CategoryError
  *
- *  Simple error message routines for SDL.
+ * Simple error message routines for SDL.
  */
 
 #ifndef SDL_error_h_

include/SDL3/SDL_events.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_events.h
+ * # CategoryEvents
  *
- *  Include file for SDL event handling.
+ * Event queue management.
  */
 
 #ifndef SDL_events_h_

include/SDL3/SDL_filesystem.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_filesystem.h
+ * # CategoryFilesystem
  *
- *  Include file for filesystem SDL API functions
+ * SDL Filesystem API.
  */
 
 #ifndef SDL_filesystem_h_

include/SDL3/SDL_gamepad.h

@@ -20,9 +20,37 @@
 */
 
 /**
- *  \file SDL_gamepad.h
+ * # CategoryGamepad
  *
- *  Include file for SDL gamepad event handling
+ * SDL provides a low-level joystick API, which just treats joysticks as an
+ * arbitrary pile of buttons, axes, and hat switches. If you're planning to
+ * write your own control configuration screen, this can give you a lot of
+ * flexibility, but that's a lot of work, and most things that we consider
+ * "joysticks" now are actually console-style gamepads. So SDL provides the
+ * gamepad API on top of the lower-level joystick functionality.
+ *
+ * The difference betweena joystick and a gamepad is that a gamepad tells you
+ * _where_ a button or axis is on the device. You don't speak to gamepads in
+ * terms of arbitrary numbers like "button 3" or "axis 2" but in standard
+ * locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or
+ * X/O/Square/Triangle, if you will).
+ *
+ * One turns a joystick into a gamepad by providing a magic configuration
+ * string, which tells SDL the details of a specific device: when you see this
+ * specific hardware, if button 2 gets pressed, this is actually D-Pad Up,
+ * etc.
+ *
+ * SDL has many popular controllers configured out of the box, and users can
+ * add their own controller details through an environment variable if it's
+ * otherwise unknown to SDL.
+ *
+ * In order to use these functions, SDL_Init() must have been called with the
+ * SDL_INIT_GAMEPAD flag. This causes SDL to scan the system for gamepads, and
+ * load appropriate drivers.
+ *
+ * If you would like to receive gamepad updates while the application is in
+ * the background, you should set the following hint before calling
+ * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
  */
 
 #ifndef SDL_gamepad_h_
@@ -41,18 +69,6 @@
 extern "C" {
 #endif
 
-/**
- *  \file SDL_gamepad.h
- *
- *  In order to use these functions, SDL_Init() must have been called
- *  with the ::SDL_INIT_GAMEPAD flag.  This causes SDL to scan the system
- *  for gamepads, and load appropriate drivers.
- *
- *  If you would like to receive gamepad updates while the application
- *  is in the background, you should set the following hint before calling
- *  SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS
- */
-
 /**
  * The structure used to identify an SDL gamepad
  *

include/SDL3/SDL_guid.h

@@ -22,9 +22,10 @@
 /* WIKI CATEGORY: GUID */
 
 /**
- *  \file SDL_guid.h
+ * # CategoryGUID
  *
- *  Include file for handling ::SDL_GUID values.
+ * A GUID is a 128-bit value that represents something that is uniquely
+ * identifiable by this value: "globally unique."
  */
 
 #ifndef SDL_guid_h_

include/SDL3/SDL_haptic.h

@@ -20,21 +20,21 @@
 */
 
 /**
- *  \file SDL_haptic.h
+ * # CategoryHaptic
  *
- *  The SDL haptic subsystem manages haptic (force feedback) devices.
+ * The SDL haptic subsystem manages haptic (force feedback) devices.
  *
- *  The basic usage is as follows:
+ * The basic usage is as follows:
  *
- *   - Initialize the subsystem (SDL_INIT_HAPTIC).
- *   - Open a haptic device.
- *    - SDL_OpenHaptic() to open from index.
- *    - SDL_OpenHapticFromJoystick() to open from an existing joystick.
- *   - Create an effect (SDL_HapticEffect).
- *   - Upload the effect with SDL_CreateHapticEffect().
- *   - Run the effect with SDL_RunHapticEffect().
- *   - (optional) Free the effect with SDL_DestroyHapticEffect().
- *   - Close the haptic device with SDL_CloseHaptic().
+ * - Initialize the subsystem (SDL_INIT_HAPTIC).
+ * - Open a haptic device.
+ * - SDL_OpenHaptic() to open from index.
+ * - SDL_OpenHapticFromJoystick() to open from an existing joystick.
+ * - Create an effect (SDL_HapticEffect).
+ * - Upload the effect with SDL_CreateHapticEffect().
+ * - Run the effect with SDL_RunHapticEffect().
+ * - (optional) Free the effect with SDL_DestroyHapticEffect().
+ * - Close the haptic device with SDL_CloseHaptic().
  *
  * Simple rumble example:
  *
@@ -113,6 +113,7 @@
  * Note that the SDL haptic subsystem is not thread-safe.
  */
 
+
 #ifndef SDL_haptic_h_
 #define SDL_haptic_h_
 

include/SDL3/SDL_hidapi.h

@@ -22,43 +22,46 @@
 /* WIKI CATEGORY: HIDAPI */
 
 /**
- *  \file SDL_hidapi.h
- *
- *  Header file for SDL HIDAPI functions.
- *
- *  This is an adaptation of the original HIDAPI interface by Alan Ott,
- *  and includes source code licensed under the following BSD license:
- *
-    Copyright (c) 2010, Alan Ott, Signal 11 Software
-    All rights reserved.
-
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
-
-    * Redistributions of source code must retain the above copyright notice,
-      this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
-    * Neither the name of Signal 11 Software nor the names of its
-      contributors may be used to endorse or promote products derived from
-      this software without specific prior written permission.
-
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-    ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
-    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
-    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
-    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
-    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
-    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-    POSSIBILITY OF SUCH DAMAGE.
+ * # CategoryHIDAPI
+ *
+ * Header file for SDL HIDAPI functions.
+ *
+ * This is an adaptation of the original HIDAPI interface by Alan Ott, and
+ * includes source code licensed under the following BSD license:
+ *
+ * ```
+ *  Copyright (c) 2010, Alan Ott, Signal 11 Software
+ *  All rights reserved.
+ *
+ *  Redistribution and use in source and binary forms, with or without
+ *  modification, are permitted provided that the following conditions are met:
+ *
+ *  * Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ *  * Neither the name of Signal 11 Software nor the names of its
+ *    contributors may be used to endorse or promote products derived from
+ *    this software without specific prior written permission.
+ *
+ *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ *  POSSIBILITY OF SUCH DAMAGE.
+ * ```
  *
  * If you would like a version of SDL without this code, you can build SDL
- * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for example
- * on iOS or tvOS to avoid a dependency on the CoreBluetooth framework.
+ * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for
+ * example on iOS or tvOS to avoid a dependency on the CoreBluetooth
+ * framework.
  */
 
 #ifndef SDL_hidapi_h_

include/SDL3/SDL_hints.h

@@ -20,20 +20,20 @@
 */
 
 /**
- *  \file SDL_hints.h
+ * # CategoryHints
  *
- *  Official documentation for SDL configuration variables
+ * Official documentation for SDL configuration variables
  *
- *  This file contains functions to set and get configuration hints,
- *  as well as listing each of them alphabetically.
+ * This file contains functions to set and get configuration hints, as well as
+ * listing each of them alphabetically.
  *
- *  The convention for naming hints is SDL_HINT_X, where "SDL_X" is
- *  the environment variable that can be used to override the default.
+ * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the
+ * environment variable that can be used to override the default.
  *
- *  In general these hints are just that - they may or may not be
- *  supported or applicable on any given platform, but they provide
- *  a way for an application or user to give the library a hint as
- *  to how they would like the library to work.
+ * In general these hints are just that - they may or may not be supported or
+ * applicable on any given platform, but they provide a way for an application
+ * or user to give the library a hint as to how they would like the library to
+ * work.
  */
 
 #ifndef SDL_hints_h_

include/SDL3/SDL_init.h

@@ -20,11 +20,12 @@
 */
 
 /**
- *  \file SDL_init.h
+ * # CategoryInit
  *
- *  Init and quit header for the SDL library
+ * SDL subsystem init and quit functions.
  */
 
+
 #ifndef SDL_init_h_
 #define SDL_init_h_
 

include/SDL3/SDL_intrin.h

@@ -19,9 +19,7 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_intrin.h
- *
+/*
  *  Header file for CPU intrinsics for SDL
  */
 

include/SDL3/SDL_iostream.h

@@ -22,13 +22,14 @@
 /* WIKI CATEGORY: IOStream */
 
 /**
- *  \file SDL_iostream.h
+ * # CategoryIOStream
  *
- *  This file provides a general interface for SDL to read and write
- *  data streams.  It can easily be extended to files, memory, etc.
+ * SDL provides an abstract interface for reading and writing data streams. It
+ * offers implementations for files, memory, etc, and the app can provideo
+ * their own implementations, too.
  *
- *  SDL_IOStream is not related to the standard C++ iostream class, other
- *  than both are abstract interfaces to read/write data.
+ * SDL_IOStream is not related to the standard C++ iostream class, other than
+ * both are abstract interfaces to read/write data.
  */
 
 #ifndef SDL_iostream_h_

include/SDL3/SDL_joystick.h

@@ -20,19 +20,26 @@
 */
 
 /**
- *  \file SDL_joystick.h
+ * # CategoryJoystick
+ *
+ * SDL joystick support.
  *
- *  Include file for SDL joystick event handling
+ * This is the lower-level joystick handling. If you want the simpler option,
+ * where what buttons does what is well-defined, you should use the gamepad
+ * API instead.
  *
- *  The term "instance_id" is the current instantiation of a joystick device in the system, if the joystick is removed and then re-inserted
- *    then it will get a new instance_id, instance_id's are monotonically increasing identifiers of a joystick plugged in.
+ * The term "instance_id" is the current instantiation of a joystick device in
+ * the system, if the joystick is removed and then re-inserted then it will
+ * get a new instance_id, instance_id's are monotonically increasing
+ * identifiers of a joystick plugged in.
  *
- *  The term "player_index" is the number assigned to a player on a specific
- *    controller. For XInput controllers this returns the XInput user index.
- *    Many joysticks will not be able to supply this information.
+ * The term "player_index" is the number assigned to a player on a specific
+ * controller. For XInput controllers this returns the XInput user index. Many
+ * joysticks will not be able to supply this information.
  *
- *  The term JoystickGUID is a stable 128-bit identifier for a joystick device that does not change over time, it identifies class of
- *    the device (a X360 wired controller for example). This identifier is platform dependent.
+ * The term SDL_JoystickGUID is a stable 128-bit identifier for a joystick
+ * device that does not change over time, it identifies class of the device (a
+ * X360 wired controller for example). This identifier is platform dependent.
  */
 
 #ifndef SDL_joystick_h_

include/SDL3/SDL_keyboard.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_keyboard.h
+ * # CategoryKeyboard
  *
- *  Include file for SDL keyboard event handling
+ * SDL keyboard management.
  */
 
 #ifndef SDL_keyboard_h_

include/SDL3/SDL_keycode.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_keycode.h
+ * # CategoryKeycode
  *
- *  Defines constants which identify keyboard keys and modifiers.
+ * Defines constants which identify keyboard keys and modifiers.
  */
 
 #ifndef SDL_keycode_h_

include/SDL3/SDL_loadso.h

@@ -22,22 +22,22 @@
 /* WIKI CATEGORY: SharedObject */
 
 /**
- *  \file SDL_loadso.h
- *
- *  System dependent library loading routines
- *
- *  Some things to keep in mind:
- *  \li These functions only work on C function names.  Other languages may
- *      have name mangling and intrinsic language support that varies from
- *      compiler to compiler.
- *  \li Make sure you declare your function pointers with the same calling
- *      convention as the actual library function.  Your code will crash
- *      mysteriously if you do not do this.
- *  \li Avoid namespace collisions.  If you load a symbol from the library,
- *      it is not defined whether or not it goes into the global symbol
- *      namespace for the application.  If it does and it conflicts with
- *      symbols in your code or other shared libraries, you will not get
- *      the results you expect. :)
+ * # CategorySharedObject
+ *
+ * System-dependent library loading routines.
+ *
+ * Some things to keep in mind:
+ *
+ * - These functions only work on C function names. Other languages may have
+ *   name mangling and intrinsic language support that varies from compiler to
+ *   compiler.
+ * - Make sure you declare your function pointers with the same calling
+ *   convention as the actual library function. Your code will crash
+ *   mysteriously if you do not do this.
+ * - Avoid namespace collisions. If you load a symbol from the library, it is
+ *   not defined whether or not it goes into the global symbol namespace for
+ *   the application. If it does and it conflicts with symbols in your code or
+ *   other shared libraries, you will not get the results you expect. :)
  */
 
 #ifndef SDL_loadso_h_

include/SDL3/SDL_locale.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_locale.h
+ * # CategoryLocale
  *
- *  Include file for SDL locale services
+ * SDL locale services.
  */
 
 #ifndef SDL_locale_h

include/SDL3/SDL_log.h

@@ -20,18 +20,19 @@
 */
 
 /**
- *  \file SDL_log.h
+ * # CategoryLog
  *
- *  Simple log messages with categories and priorities.
+ * Simple log messages with categories and priorities.
  *
- *  By default logs are quiet, but if you're debugging SDL you might want:
+ * By default logs are quiet, but if you're debugging SDL you might want:
  *
- *      SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
+ * SDL_LogSetAllPriority(SDL_LOG_PRIORITY_WARN);
  *
- *  Here's where the messages go on different platforms:
- *      Windows: debug output stream
- *      Android: log output
- *      Others: standard error output (stderr)
+ * Here's where the messages go on different platforms:
+ *
+ * - Windows: debug output stream
+ * - Android: log output
+ * - Others: standard error output (stderr)
  */
 
 #ifndef SDL_log_h_

include/SDL3/SDL_main.h

@@ -19,15 +19,11 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-#ifndef SDL_main_h_
-#define SDL_main_h_
-
-#include <SDL3/SDL_platform_defines.h>
-#include <SDL3/SDL_stdinc.h>
-#include <SDL3/SDL_error.h>
-#include <SDL3/SDL_events.h>
-
-/*
+/**
+ * # CategoryMain
+ *
+ * Redefine main() on some platforms so that it is called by SDL.
+ *
  * For details on how SDL_main works, and how to use it, please refer to:
  *
  * https://wiki.libsdl.org/SDL3/README/main-functions
@@ -35,11 +31,13 @@
  * (or docs/README-main-functions.md in the SDL source tree)
  */
 
-/**
- *  \file SDL_main.h
- *
- *  Redefine main() on some platforms so that it is called by SDL.
- */
+#ifndef SDL_main_h_
+#define SDL_main_h_
+
+#include <SDL3/SDL_platform_defines.h>
+#include <SDL3/SDL_stdinc.h>
+#include <SDL3/SDL_error.h>
+#include <SDL3/SDL_events.h>
 
 #ifndef SDL_MAIN_HANDLED
     #ifdef SDL_PLATFORM_WIN32

include/SDL3/SDL_messagebox.h

@@ -19,6 +19,12 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/**
+ * # CategoryMessagebox
+ *
+ * Message box support routines.
+ */
+
 #ifndef SDL_messagebox_h_
 #define SDL_messagebox_h_
 

include/SDL3/SDL_metal.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_metal.h
+ * # CategoryMetal
  *
- *  Header file for functions to creating Metal layers and views on SDL windows.
+ * Functions to creating Metal layers and views on SDL windows.
  */
 
 #ifndef SDL_metal_h_

include/SDL3/SDL_misc.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_misc.h
+ * # CategoryMisc
  *
- *  Include file for SDL API functions that don't fit elsewhere.
+ * SDL API functions that don't fit elsewhere.
  */
 
 #ifndef SDL_misc_h_

include/SDL3/SDL_mouse.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_mouse.h
+ * # CategoryMouse
  *
- *  Include file for SDL mouse event handling.
+ * SDL mouse handling.
  */
 
 #ifndef SDL_mouse_h_

include/SDL3/SDL_mutex.h

@@ -23,9 +23,9 @@
 #define SDL_mutex_h_
 
 /**
- *  \file SDL_mutex.h
+ * # CategoryMutex
  *
- *  Functions to provide thread synchronization primitives.
+ * Functions to provide thread synchronization primitives.
  */
 
 #include <SDL3/SDL_stdinc.h>

include/SDL3/SDL_oldnames.h

@@ -19,10 +19,8 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_oldnames.h
- *
- *  Definitions to ease transition from SDL2 code
+/*
+ * Definitions to ease transition from SDL2 code
  */
 
 #ifndef SDL_oldnames_h_

include/SDL3/SDL_opengl.h

@@ -19,17 +19,11 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_opengl.h
- *
- *  This is a simple file to encapsulate the OpenGL API headers.
- */
-
-/**
- *  \def NO_SDL_GLEXT
+/*
+ * This is a simple file to encapsulate the OpenGL API headers.
  *
- *  Define this if you have your own version of glext.h and want to disable the
- *  version included in SDL_opengl.h.
+ * Define NO_SDL_GLEXT if you have your own version of glext.h and want
+ * to disable the version included in SDL_opengl.h.
  */
 
 #ifndef SDL_opengl_h_

include/SDL3/SDL_opengles.h

@@ -19,11 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_opengles.h
- *
- *  This is a simple file to encapsulate the OpenGL ES 1.X API headers.
+/*
+ * This is a simple file to encapsulate the OpenGL ES 1.X API headers.
  */
+
 #include <SDL3/SDL_platform_defines.h>
 
 #ifdef SDL_PLATFORM_IOS

include/SDL3/SDL_opengles2.h

@@ -19,11 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_opengles2.h
- *
- *  This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
+/*
+ * This is a simple file to encapsulate the OpenGL ES 2.0 API headers.
  */
+
 #include <SDL3/SDL_platform_defines.h>
 
 #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS)

include/SDL3/SDL_pen.h

@@ -20,26 +20,26 @@
 */
 
 /**
- *  \file SDL_pen.h
+ * # CategoryPen
  *
- *  Include file for SDL pen event handling.
+ * Include file for SDL pen event handling.
  *
- *  This file describes operations for pressure-sensitive pen (stylus and/or eraser) handling, e.g., for input
- *    and drawing tablets or suitably equipped mobile / tablet devices.
+ * This file describes operations for pressure-sensitive pen (stylus and/or
+ * eraser) handling, e.g., for input and drawing tablets or suitably equipped
+ * mobile / tablet devices.
  *
- *  To get started with pens:
- *  - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
- *  - To avoid treating pen events as mouse events, ignore  SDL_MouseMotionEvent and SDL_MouseButtonEvent
- *    whenever "which" == SDL_PEN_MOUSEID.
+ * To get started with pens:
  *
- *  This header file describes advanced functionality that can be useful for managing user configuration
- *    and understanding the capabilities of the attached pens.
+ * - Listen to SDL_PenMotionEvent and SDL_PenButtonEvent
+ * - To avoid treating pen events as mouse events, ignore SDL_MouseMotionEvent
+ *   and SDL_MouseButtonEvent whenever `which` == SDL_PEN_MOUSEID.
  *
- *  We primarily identify pens by SDL_PenID.  The implementation makes a best effort to relate each :SDL_PenID
- *    to the same physical device during a session.  Formerly valid SDL_PenID values remain valid
- *    even if a device disappears.
+ * We primarily identify pens by SDL_PenID. The implementation makes a best
+ * effort to relate each SDL_PenID to the same physical device during a
+ * session. Formerly valid SDL_PenID values remain valid even if a device
+ * disappears.
  *
- *  For identifying pens across sessions, the API provides the type SDL_GUID .
+ * For identifying pens across sessions, the API provides the type SDL_GUID .
  */
 
 #ifndef SDL_pen_h_

include/SDL3/SDL_pixels.h

@@ -19,6 +19,12 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
+/**
+ * # CategoryPixels
+ *
+ * Pixel management.
+ */
+
 #ifndef SDL_pixels_h_
 #define SDL_pixels_h_
 

include/SDL3/SDL_platform.h

@@ -20,9 +20,10 @@
 */
 
 /**
- *  \file SDL_platform.h
+ * # CategoryPlatform
  *
- *  Header file for platform functions.
+ * SDL provides a means to identify the app's platform, both at compile time
+ * and runtime.
  */
 
 #ifndef SDL_platform_h_

include/SDL3/SDL_platform_defines.h

@@ -19,12 +19,10 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/* WIKI CATEGORY: PlatformDefines */
+/* WIKI CATEGORY: Platform */
 
-/**
- *  \file SDL_platform_defines.h
- *
- *  Try to get a standard set of platform defines.
+/*
+ * SDL_platform_defines.h tries to get a standard set of platform defines.
  */
 
 #ifndef SDL_platform_defines_h_

include/SDL3/SDL_power.h

@@ -23,9 +23,9 @@
 #define SDL_power_h_
 
 /**
- *  \file SDL_power.h
+ * # CategoryPower
  *
- *  Header for the SDL power management routines.
+ * SDL power management routines.
  */
 
 #include <SDL3/SDL_stdinc.h>

include/SDL3/SDL_properties.h

@@ -20,11 +20,12 @@
 */
 
 /**
- *  \file SDL_properties.h
+ * # CategoryProperties
  *
- *  Header file for SDL properties.
+ * SDL properties.
  */
 
+
 #ifndef SDL_properties_h_
 #define SDL_properties_h_
 

include/SDL3/SDL_rect.h

@@ -20,9 +20,10 @@
 */
 
 /**
- *  \file SDL_rect.h
+ * # CategoryRect
  *
- *  Header file for SDL_rect definition and management functions.
+ * Some helper functions for managing rectangles and 2D points, in both
+ * interger and floating point versions.
  */
 
 #ifndef SDL_rect_h_

include/SDL3/SDL_render.h

@@ -20,29 +20,31 @@
 */
 
 /**
- *  \file SDL_render.h
+ * # CategoryRender
  *
- *  Header file for SDL 2D rendering functions.
+ * Header file for SDL 2D rendering functions.
  *
- *  This API supports the following features:
- *      * single pixel points
- *      * single pixel lines
- *      * filled rectangles
- *      * texture images
+ * This API supports the following features:
  *
- *  The primitives may be drawn in opaque, blended, or additive modes.
+ * - single pixel points
+ * - single pixel lines
+ * - filled rectangles
+ * - texture images
+ * - 2D polygons
  *
- *  The texture images may be drawn in opaque, blended, or additive modes.
- *  They can have an additional color tint or alpha modulation applied to
- *  them, and may also be stretched with linear interpolation.
+ * The primitives may be drawn in opaque, blended, or additive modes.
  *
- *  This API is designed to accelerate simple 2D operations. You may
- *  want more functionality such as polygons and particle effects and
- *  in that case you should use SDL's OpenGL/Direct3D support or one
- *  of the many good 3D engines.
+ * The texture images may be drawn in opaque, blended, or additive modes. They
+ * can have an additional color tint or alpha modulation applied to them, and
+ * may also be stretched with linear interpolation.
  *
- *  These functions must be called from the main thread.
- *  See this bug for details: https://github.com/libsdl-org/SDL/issues/986
+ * This API is designed to accelerate simple 2D operations. You may want more
+ * functionality such as polygons and particle effects and in that case you
+ * should use SDL's OpenGL/Direct3D support or one of the many good 3D
+ * engines.
+ *
+ * These functions must be called from the main thread. See this bug for
+ * details: https://github.com/libsdl-org/SDL/issues/986
  */
 
 #ifndef SDL_render_h_

include/SDL3/SDL_revision.h

@@ -19,14 +19,14 @@
   3. This notice may not be removed or altered from any source distribution.
 */
 
-/**
- *  \file SDL_revision.h
- *
- *  Header file containing the SDL revision
- */
-
 /* WIKI CATEGORY: Version */
 
+/*
+ * SDL_revision.h contains the SDL revision, which might be defined on the
+ * compiler command line, or generated right into the header itself by the
+ * build system.
+ */
+
 #ifndef SDL_revision_h_
 #define SDL_revision_h_
 

include/SDL3/SDL_scancode.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_scancode.h
+ * # CategoryScancode
  *
- *  Defines keyboard scancodes.
+ * Defines keyboard scancodes.
  */
 
 #ifndef SDL_scancode_h_

include/SDL3/SDL_sensor.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_sensor.h
+ * # CategorySensor
  *
- *  Include file for SDL sensor event handling
+ * SDL sensor management.
  */
 
 #ifndef SDL_sensor_h_

include/SDL3/SDL_stdinc.h

@@ -20,11 +20,11 @@
 */
 
 /**
- *  \file SDL_stdinc.h
+ * # CategoryStdinc
  *
- *  This is a general header that includes C language support. It implements
- *  a subset of the C runtime: these should all behave the same way as their
- *  C runtime equivalents, but with an SDL_ prefix.
+ * This is a general header that includes C language support. It implements a
+ * subset of the C runtime: these should all behave the same way as their C
+ * runtime equivalents, but with an SDL_ prefix.
  */
 
 #ifndef SDL_stdinc_h_

include/SDL3/SDL_storage.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_storage.h
+ * # CategoryStorage
  *
- *  Include file for storage container SDL API functions
+ * SDL storage container management.
  */
 
 #ifndef SDL_storage_h_

include/SDL3/SDL_surface.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_surface.h
+ * # CategorySurface
  *
- *  Header file for ::SDL_Surface definition and management functions.
+ * SDL_Surface definition and management functions.
  */
 
 #ifndef SDL_surface_h_

include/SDL3/SDL_system.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_system.h
+ * # CategorySystem
  *
- *  Include file for platform specific SDL API functions
+ * Platform-specific SDL API functions.
  */
 
 #ifndef SDL_system_h_

include/SDL3/SDL_test_assert.h

@@ -20,8 +20,6 @@
 */
 
 /**
- *  \file SDL_test_assert.h
- *
  *  Assertion functions of SDL test framework.
  *
  *  This code is a part of the SDL test library, not the main SDL library.

include/SDL3/SDL_test_crc32.h

@@ -20,8 +20,6 @@
 */
 
 /**
- *  \file SDL_test_crc32.h
- *
  *  CRC32 functions of SDL test framework.
  *
  *  This code is a part of the SDL test library, not the main SDL library.

include/SDL3/SDL_test_fuzzer.h

@@ -20,8 +20,6 @@
 */
 
 /**
- *  \file SDL_test_fuzzer.h
- *
  *  Fuzzer functions of SDL test framework.
  *
  *  This code is a part of the SDL test library, not the main SDL library.
@@ -49,7 +47,6 @@ extern "C" {
 
 
 /**
- * \file
  * Note: The fuzzer implementation uses a static instance of random context
  * internally which makes it thread-UNsafe.
  */

include/SDL3/SDL_thread.h

@@ -23,9 +23,9 @@
 #define SDL_thread_h_
 
 /**
- *  \file SDL_thread.h
+ * # CategoryThread
  *
- *  Header for the SDL thread management routines.
+ * SDL thread management routines.
  */
 
 #include <SDL3/SDL_stdinc.h>

include/SDL3/SDL_time.h

@@ -23,9 +23,9 @@ freely, subject to the following restrictions:
 #define SDL_time_h_
 
 /**
- *  \file SDL_time.h
+ * # CategoryTime
  *
- *  Header for the SDL realtime clock and date/time routines.
+ * SDL realtime clock and date/time routines.
  */
 
 #include <SDL3/SDL_error.h>

include/SDL3/SDL_timer.h

@@ -23,9 +23,9 @@
 #define SDL_timer_h_
 
 /**
- *  \file SDL_timer.h
+ * # CategoryTimer
  *
- *  Header for the SDL time management routines.
+ * SDL time management routines.
  */
 
 #include <SDL3/SDL_stdinc.h>

include/SDL3/SDL_touch.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_touch.h
+ * # CategoryTouch
  *
- *  Include file for SDL touch event handling.
+ * SDL touch management.
  */
 
 #ifndef SDL_touch_h_

include/SDL3/SDL_version.h

@@ -20,9 +20,10 @@
 */
 
 /**
- *  \file SDL_version.h
+ * # CategoryVersion
  *
- *  This header defines the current SDL version.
+ * Functionality to query the current SDL version, both as headers the app was
+ * compiled against, and a library the app is linked to.
  */
 
 #ifndef SDL_version_h_

include/SDL3/SDL_video.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_video.h
+ * # CategoryVideo
  *
- *  Header file for SDL video functions.
+ * SDL video functions.
  */
 
 #ifndef SDL_video_h_

include/SDL3/SDL_vulkan.h

@@ -20,9 +20,9 @@
 */
 
 /**
- *  \file SDL_vulkan.h
+ * # CategoryVulkan
  *
- *  Header file for functions to creating Vulkan surfaces on SDL windows.
+ * Functions for creating Vulkan surfaces on SDL windows.
  */
 
 #ifndef SDL_vulkan_h_