From 5e6d85b8f0fee45571f9374886bb4e1898269289 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" 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 | 34 +++- include/SDL3/SDL_atomic.h | 30 ++- 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 | 67 +++---- 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 | 28 +-- 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, 617 insertions(+), 388 deletions(-) diff --git a/.wikiheaders-options b/.wikiheaders-options index 2f74ee750..a6c85fb98 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 [](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 6e4219702..2669e33a0 100755 --- a/build-scripts/wikiheaders.pl +++ b/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 () { 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 () { 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 = ; - $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 = ; + $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 () { + chomp; + if ($docs) { + $docs = 0 if /\A\-\-\-\-\Z/; # Hit a footer? We're done. + $docs = 0 if /\A{'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]'}; + if ($symtype != -1) { # Don't do these in category documentation block + 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!"); - } + 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!"); + } - 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; - - 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__ + + + +## Functions + + + + + +## Datatypes + + + + + +## Structs + + + + + +## Enums + + + + + +## Macros + + + + + +---- +[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}; diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index a58359944..4254d0f7e 100644 --- a/include/SDL3/SDL_assert.h +++ b/include/SDL3/SDL_assert.h @@ -20,9 +20,39 @@ */ /** - * \file SDL_assert.h + * # CategoryAssert * - * Header file for assertion SDL API functions + * 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 df1160e26..9d2c27b8e 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 f5c1a8568..a055a6c03 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 e4ff27a11..e2a7ce48a 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 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. */ diff --git a/include/SDL3/SDL_bits.h b/include/SDL3/SDL_bits.h index 7b137b091..6547a96c3 100644 --- a/include/SDL3/SDL_bits.h +++ b/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_ diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h index 3c89bcb07..5b26f537e 100644 --- a/include/SDL3/SDL_blendmode.h +++ b/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_ diff --git a/include/SDL3/SDL_camera.h b/include/SDL3/SDL_camera.h index 6d2e1e7af..56ef270af 100644 --- a/include/SDL3/SDL_camera.h +++ b/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_ diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h index b082666b3..d588e61cc 100644 --- a/include/SDL3/SDL_clipboard.h +++ b/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_ diff --git a/include/SDL3/SDL_close_code.h b/include/SDL3/SDL_close_code.h index 7e51e665f..fa4d3d17b 100644 --- a/include/SDL3/SDL_close_code.h +++ b/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 diff --git a/include/SDL3/SDL_copying.h b/include/SDL3/SDL_copying.h index 6f6ade5e9..dcbdcea82 100644 --- a/include/SDL3/SDL_copying.h +++ b/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. */ diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h index 29410ffa6..ccb0db180 100644 --- a/include/SDL3/SDL_cpuinfo.h +++ b/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_ diff --git a/include/SDL3/SDL_dialog.h b/include/SDL3/SDL_dialog.h index 336dc2f24..6526f7748 100644 --- a/include/SDL3/SDL_dialog.h +++ b/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_ diff --git a/include/SDL3/SDL_egl.h b/include/SDL3/SDL_egl.h index 6234a74a3..cc557d60e 100644 --- a/include/SDL3/SDL_egl.h +++ b/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 diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h index f1c03e512..8beed28d0 100644 --- a/include/SDL3/SDL_endian.h +++ b/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_ diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h index b46749eb0..e5908d0ef 100644 --- a/include/SDL3/SDL_error.h +++ b/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_ diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h index 6757f036e..d4ace8077 100644 --- a/include/SDL3/SDL_events.h +++ b/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_ diff --git a/include/SDL3/SDL_filesystem.h b/include/SDL3/SDL_filesystem.h index e750677c0..f9791389a 100644 --- a/include/SDL3/SDL_filesystem.h +++ b/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_ diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h index 142a40072..9c129c6b0 100644 --- a/include/SDL3/SDL_gamepad.h +++ b/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 * diff --git a/include/SDL3/SDL_guid.h b/include/SDL3/SDL_guid.h index f1e21e5fb..4faffe4f5 100644 --- a/include/SDL3/SDL_guid.h +++ b/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_ diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h index 7f8832581..959e12bbe 100644 --- a/include/SDL3/SDL_haptic.h +++ b/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_ diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h index 5e3fd8ae7..127c94064 100644 --- a/include/SDL3/SDL_hidapi.h +++ b/include/SDL3/SDL_hidapi.h @@ -22,43 +22,46 @@ /* WIKI CATEGORY: HIDAPI */ /** - * \file SDL_hidapi.h + * # CategoryHIDAPI * - * Header file for SDL HIDAPI functions. + * 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: + * 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. + * ``` + * 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_ diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index 75f00bbcd..ab6d11d93 100644 --- a/include/SDL3/SDL_hints.h +++ b/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_ diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index 926a33e27..d871fc079 100644 --- a/include/SDL3/SDL_init.h +++ b/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_ diff --git a/include/SDL3/SDL_intrin.h b/include/SDL3/SDL_intrin.h index f907df9ce..70a156340 100644 --- a/include/SDL3/SDL_intrin.h +++ b/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 */ diff --git a/include/SDL3/SDL_iostream.h b/include/SDL3/SDL_iostream.h index 2618cab8f..7f624a217 100644 --- a/include/SDL3/SDL_iostream.h +++ b/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_ diff --git a/include/SDL3/SDL_joystick.h b/include/SDL3/SDL_joystick.h index 79b551708..85207471f 100644 --- a/include/SDL3/SDL_joystick.h +++ b/include/SDL3/SDL_joystick.h @@ -20,19 +20,26 @@ */ /** - * \file SDL_joystick.h + * # CategoryJoystick * - * Include file for SDL joystick event handling + * SDL joystick support. * - * 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. + * 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 "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 "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 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 "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 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_ diff --git a/include/SDL3/SDL_keyboard.h b/include/SDL3/SDL_keyboard.h index c065af641..3a1b6c10d 100644 --- a/include/SDL3/SDL_keyboard.h +++ b/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_ diff --git a/include/SDL3/SDL_keycode.h b/include/SDL3/SDL_keycode.h index 2e10edfc2..76d53f88d 100644 --- a/include/SDL3/SDL_keycode.h +++ b/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_ diff --git a/include/SDL3/SDL_loadso.h b/include/SDL3/SDL_loadso.h index 65910a37b..b74922e78 100644 --- a/include/SDL3/SDL_loadso.h +++ b/include/SDL3/SDL_loadso.h @@ -22,22 +22,22 @@ /* WIKI CATEGORY: SharedObject */ /** - * \file SDL_loadso.h + * # CategorySharedObject * - * System dependent library loading routines + * 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. :) + * 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_ diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h index 16caf2096..ae5b5ce7a 100644 --- a/include/SDL3/SDL_locale.h +++ b/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 diff --git a/include/SDL3/SDL_log.h b/include/SDL3/SDL_log.h index a58cef6c0..5fe930c86 100644 --- a/include/SDL3/SDL_log.h +++ b/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_ diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index 8552a8e7d..ee46e2b78 100644 --- a/include/SDL3/SDL_main.h +++ b/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 -#include -#include -#include - -/* +/** + * # 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 +#include +#include +#include #ifndef SDL_MAIN_HANDLED #ifdef SDL_PLATFORM_WIN32 diff --git a/include/SDL3/SDL_messagebox.h b/include/SDL3/SDL_messagebox.h index 4755d4c49..20f76a417 100644 --- a/include/SDL3/SDL_messagebox.h +++ b/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_ diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h index 8dd2ce16c..56ce76a3b 100644 --- a/include/SDL3/SDL_metal.h +++ b/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_ diff --git a/include/SDL3/SDL_misc.h b/include/SDL3/SDL_misc.h index e87319989..17e7c4206 100644 --- a/include/SDL3/SDL_misc.h +++ b/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_ diff --git a/include/SDL3/SDL_mouse.h b/include/SDL3/SDL_mouse.h index f8155953c..cccf90da2 100644 --- a/include/SDL3/SDL_mouse.h +++ b/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_ diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index 67fe633de..4fcec2138 100644 --- a/include/SDL3/SDL_mutex.h +++ b/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 diff --git a/include/SDL3/SDL_oldnames.h b/include/SDL3/SDL_oldnames.h index d0e5c800d..b98536230 100644 --- a/include/SDL3/SDL_oldnames.h +++ b/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_ diff --git a/include/SDL3/SDL_opengl.h b/include/SDL3/SDL_opengl.h index 575f64616..6bdcbe008 100644 --- a/include/SDL3/SDL_opengl.h +++ b/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. * - * This is a simple file to encapsulate the OpenGL API headers. - */ - -/** - * \def NO_SDL_GLEXT - * - * 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_ diff --git a/include/SDL3/SDL_opengles.h b/include/SDL3/SDL_opengles.h index d17346393..bde4d74f1 100644 --- a/include/SDL3/SDL_opengles.h +++ b/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 #ifdef SDL_PLATFORM_IOS diff --git a/include/SDL3/SDL_opengles2.h b/include/SDL3/SDL_opengles2.h index 85abf2b81..ba1960105 100644 --- a/include/SDL3/SDL_opengles2.h +++ b/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 #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) diff --git a/include/SDL3/SDL_pen.h b/include/SDL3/SDL_pen.h index 1a96d07a3..5c57dc69d 100644 --- a/include/SDL3/SDL_pen.h +++ b/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_ diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index 87dee8686..4731858af 100644 --- a/include/SDL3/SDL_pixels.h +++ b/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_ diff --git a/include/SDL3/SDL_platform.h b/include/SDL3/SDL_platform.h index 289d02dac..928f57681 100644 --- a/include/SDL3/SDL_platform.h +++ b/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_ diff --git a/include/SDL3/SDL_platform_defines.h b/include/SDL3/SDL_platform_defines.h index 2fa435f33..72b1ef260 100644 --- a/include/SDL3/SDL_platform_defines.h +++ b/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_ diff --git a/include/SDL3/SDL_power.h b/include/SDL3/SDL_power.h index d452b2a3b..d7b36ae64 100644 --- a/include/SDL3/SDL_power.h +++ b/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 diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index 37f777ea5..814e2c654 100644 --- a/include/SDL3/SDL_properties.h +++ b/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_ diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index c925281b7..ee9f0a6d6 100644 --- a/include/SDL3/SDL_rect.h +++ b/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_ diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h index ae233cbfd..137a3f198 100644 --- a/include/SDL3/SDL_render.h +++ b/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_ diff --git a/include/SDL3/SDL_revision.h b/include/SDL3/SDL_revision.h index e282129fa..f78e5d9d0 100644 --- a/include/SDL3/SDL_revision.h +++ b/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_ diff --git a/include/SDL3/SDL_scancode.h b/include/SDL3/SDL_scancode.h index 3e919c05e..1adeff5f2 100644 --- a/include/SDL3/SDL_scancode.h +++ b/include/SDL3/SDL_scancode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_scancode.h + * # CategoryScancode * - * Defines keyboard scancodes. + * Defines keyboard scancodes. */ #ifndef SDL_scancode_h_ diff --git a/include/SDL3/SDL_sensor.h b/include/SDL3/SDL_sensor.h index d729d02bf..d2cb3c7b3 100644 --- a/include/SDL3/SDL_sensor.h +++ b/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_ diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 6d8713876..3a68f0689 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/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_ diff --git a/include/SDL3/SDL_storage.h b/include/SDL3/SDL_storage.h index 4c4e72d21..3f3ec2708 100644 --- a/include/SDL3/SDL_storage.h +++ b/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_ diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h index 3b0d6d608..8d0ffc013 100644 --- a/include/SDL3/SDL_surface.h +++ b/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_ diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 333739e13..6423e92bb 100644 --- a/include/SDL3/SDL_system.h +++ b/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_ diff --git a/include/SDL3/SDL_test_assert.h b/include/SDL3/SDL_test_assert.h index 1c00bc157..98d8680c2 100644 --- a/include/SDL3/SDL_test_assert.h +++ b/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. diff --git a/include/SDL3/SDL_test_crc32.h b/include/SDL3/SDL_test_crc32.h index 72e96e563..e6316bcf5 100644 --- a/include/SDL3/SDL_test_crc32.h +++ b/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. diff --git a/include/SDL3/SDL_test_fuzzer.h b/include/SDL3/SDL_test_fuzzer.h index 14c5dc9b9..89606ef3b 100644 --- a/include/SDL3/SDL_test_fuzzer.h +++ b/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. */ diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index 5aa7766c9..29c2121a9 100644 --- a/include/SDL3/SDL_thread.h +++ b/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 diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index 69d3dae56..adb53ed20 100644 --- a/include/SDL3/SDL_time.h +++ b/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 diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h index 00a84895f..bbd9249c5 100644 --- a/include/SDL3/SDL_timer.h +++ b/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 diff --git a/include/SDL3/SDL_touch.h b/include/SDL3/SDL_touch.h index 18aab0d7d..43dceea4c 100644 --- a/include/SDL3/SDL_touch.h +++ b/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_ diff --git a/include/SDL3/SDL_version.h b/include/SDL3/SDL_version.h index f9d67f894..545a5b284 100644 --- a/include/SDL3/SDL_version.h +++ b/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_ diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index e84717bc2..2f5f5fee6 100644 --- a/include/SDL3/SDL_video.h +++ b/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_ diff --git a/include/SDL3/SDL_vulkan.h b/include/SDL3/SDL_vulkan.h index 05a5c559e..7871a05c8 100644 --- a/include/SDL3/SDL_vulkan.h +++ b/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_