From 1c3a1e113914a749d71193da41feb0506dd595ab Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Thu, 16 May 2024 11:41:54 -0400 Subject: [PATCH] wikiheaders: Updated to latest, cleaned up category documentation a little. This documentation needs a LOT of work--maybe someday--but it's definitely not _broken_ right now, which is good enough for now. --- .wikiheaders-options | 4 +- build-scripts/wikiheaders.pl | 310 +++++++++++++++++++++++++---------- include/SDL_atomic.h | 39 ++--- include/SDL_audio.h | 4 +- include/SDL_bits.h | 4 +- include/SDL_blendmode.h | 4 +- include/SDL_clipboard.h | 2 +- include/SDL_config.h | 4 +- include/SDL_cpuinfo.h | 12 +- include/SDL_egl.h | 7 +- include/SDL_endian.h | 4 +- include/SDL_error.h | 4 +- include/SDL_events.h | 4 +- include/SDL_filesystem.h | 4 +- include/SDL_gamecontroller.h | 12 +- include/SDL_gesture.h | 4 +- include/SDL_guid.h | 13 +- include/SDL_haptic.h | 28 ++-- include/SDL_hidapi.h | 71 ++++---- include/SDL_hints.h | 20 +-- include/SDL_joystick.h | 24 +-- include/SDL_keyboard.h | 4 +- include/SDL_keycode.h | 4 +- include/SDL_loadso.h | 38 ++--- include/SDL_locale.h | 4 +- include/SDL_log.h | 17 +- include/SDL_main.h | 4 +- include/SDL_metal.h | 5 +- include/SDL_misc.h | 4 +- include/SDL_mouse.h | 4 +- include/SDL_mutex.h | 4 +- include/SDL_opengl.h | 14 +- include/SDL_opengles.h | 7 +- include/SDL_opengles2.h | 7 +- include/SDL_pixels.h | 4 +- include/SDL_platform.h | 4 +- include/SDL_power.h | 4 +- include/SDL_quit.h | 22 +-- include/SDL_rect.h | 4 +- include/SDL_render.h | 35 ++-- include/SDL_rwops.h | 14 +- include/SDL_scancode.h | 4 +- include/SDL_sensor.h | 5 +- include/SDL_stdinc.h | 12 +- include/SDL_surface.h | 4 +- include/SDL_system.h | 4 +- include/SDL_syswm.h | 24 ++- include/SDL_thread.h | 4 +- include/SDL_timer.h | 4 +- include/SDL_touch.h | 4 +- include/SDL_types.h | 7 +- include/SDL_version.h | 4 +- include/SDL_video.h | 4 +- include/SDL_vulkan.h | 4 +- include/begin_code.h | 14 +- 55 files changed, 499 insertions(+), 380 deletions(-) diff --git a/.wikiheaders-options b/.wikiheaders-options index 9e6716ac56..eb8737519d 100644 --- a/.wikiheaders-options +++ b/.wikiheaders-options @@ -19,6 +19,6 @@ wikiheaderfiletext = Defined in [%fname%](https://github.com/libsdl-org/SDL/blob manpageheaderfiletext = Defined in %fname% # All SDL_config_*.h headers are uncategorized, in case something slips in from them. -# All SDL_test_* headers become "Test" categories, everything else just converts like SDL_audio.h -> Audio +# All SDL_test_* headers become uncategorized, everything else just converts like SDL_audio.h -> Audio # A handful of others we fix up in the header itself with /* WIKI CATEGORY: x */ comments. -headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z/Test/; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst(); +headercategoryeval = s/\ASDL_config_.*?\.h\Z//; s/\ASDL_test_.*?\.h\Z//; s/\ASDL_?(.*?)\.h\Z/$1/; ucfirst(); diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl index 185701b479..2669e33a0f 100755 --- a/build-scripts/wikiheaders.pl +++ b/build-scripts/wikiheaders.pl @@ -16,7 +16,7 @@ my $apiprefixregex = undef; my $versionfname = 'include/SDL_version.h'; my $versionmajorregex = '\A\#define\s+SDL_MAJOR_VERSION\s+(\d+)\Z'; my $versionminorregex = '\A\#define\s+SDL_MINOR_VERSION\s+(\d+)\Z'; -my $versionpatchregex = '\A\#define\s+SDL_PATCHLEVEL\s+(\d+)\Z'; +my $versionmicroregex = '\A\#define\s+SDL_MICRO_VERSION\s+(\d+)\Z'; my $mainincludefname = 'SDL.h'; my $selectheaderregex = '\ASDL.*?\.h\Z'; my $projecturl = 'https://libsdl.org/'; @@ -92,7 +92,7 @@ if (defined $optionsfname) { $readmesubdir = $val, next if $key eq 'readmesubdir'; $versionmajorregex = $val, next if $key eq 'versionmajorregex'; $versionminorregex = $val, next if $key eq 'versionminorregex'; - $versionpatchregex = $val, next if $key eq 'versionpatchregex'; + $versionmicroregex = $val, next if $key eq 'versionmicroregex'; $versionfname = $val, next if $key eq 'versionfname'; $mainincludefname = $val, next if $key eq 'mainincludefname'; $selectheaderregex = $val, next if $key eq 'selectheaderregex'; @@ -622,7 +622,7 @@ 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 @@ -2036,23 +2178,24 @@ if ($copy_direction == 1) { # --copy-to-headers open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); my $majorver = 0; my $minorver = 0; - my $patchver = 0; + my $microver = 0; while () { chomp; if (/$versionmajorregex/) { $majorver = int($1); } elsif (/$versionminorregex/) { $minorver = int($1); - } elsif (/$versionpatchregex/) { - $patchver = int($1); + } elsif (/$versionmicroregex/) { + $microver = int($1); } } close(FH); - my $fullversion = "$majorver.$minorver.$patchver"; + my $fullversion = "$majorver.$minorver.$microver"; foreach (keys %headersyms) { my $sym = $_; next if not defined $wikisyms{$sym}; # don't have a page for that function, skip it. + next if $sym =~ /\A\[category documentation\]/; # not real symbols my $symtype = $headersymstype{$sym}; my $wikitype = $wikitypes{$sym}; my $sectionsref = $wikisyms{$sym}; @@ -2318,19 +2461,19 @@ if ($copy_direction == 1) { # --copy-to-headers open(FH, '<', "$srcpath/$versionfname") or die("Can't open '$srcpath/$versionfname': $!\n"); my $majorver = 0; my $minorver = 0; - my $patchver = 0; + my $microver = 0; while () { chomp; if (/$versionmajorregex/) { $majorver = int($1); } elsif (/$versionminorregex/) { $minorver = int($1); - } elsif (/$versionpatchregex/) { - $patchver = int($1); + } elsif (/$versionmicroregex/) { + $microver = int($1); } } close(FH); - my $fullversion = "$majorver.$minorver.$patchver"; + my $fullversion = "$majorver.$minorver.$microver"; my $latex_fname = "$srcpath/$projectshortname.tex"; my $latex_tmpfname = "$latex_fname.tmp"; @@ -2369,7 +2512,7 @@ if ($copy_direction == 1) { # --copy-to-headers \\begin{document} \\frontmatter -\\title{$projectfullname $majorver.$minorver.$patchver Reference Manual} +\\title{$projectfullname $majorver.$minorver.$microver Reference Manual} \\author{The $projectshortname Developers} \\maketitle @@ -2399,6 +2542,7 @@ __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/SDL_atomic.h b/include/SDL_atomic.h index 79ec2006c7..d8cb3c0daf 100644 --- a/include/SDL_atomic.h +++ b/include/SDL_atomic.h @@ -20,38 +20,29 @@ */ /** - * \file SDL_atomic.h + * # CategoryAtomic * * Atomic operations. * - * IMPORTANT: - * If you are not an expert in concurrent lockless programming, you should - * only be using the atomic lock and reference counting functions in this - * file. In all other cases you should be protecting your data structures - * with full mutexes. + * IMPORTANT: If you are not an expert in concurrent lockless programming, you + * should not be using any functions in this file. You should be protecting + * your data structures with full mutexes instead. * - * The list of "safe" functions to use are: - * SDL_AtomicLock() - * SDL_AtomicUnlock() - * SDL_AtomicIncRef() - * SDL_AtomicDecRef() + * ***Seriously, here be dragons!*** * - * Seriously, here be dragons! - * ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - * - * You can find out a little more about lockless programming and the - * subtle issues that can arise here: - * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx + * You can find out a little more about lockless programming and the subtle + * issues that can arise here: + * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming * * There's also lots of good information here: - * http://www.1024cores.net/home/lock-free-algorithms - * http://preshing.com/ * - * These operations may or may not actually be implemented using - * processor specific atomic operations. When possible they are - * implemented as true processor specific atomic operations. When that - * is not possible the are implemented using locks that *do* use the - * available atomic operations. + * - https://www.1024cores.net/home/lock-free-algorithms + * - https://preshing.com/ + * + * These operations may or may not actually be implemented using processor + * specific atomic operations. When possible they are implemented as true + * processor specific atomic operations. When that is not possible the are + * implemented using locks that *do* use the available atomic operations. * * All of the atomic operations that modify memory are full memory barriers. */ diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 5f5d681865..e09a37554f 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -22,9 +22,9 @@ /* !!! FIXME: several functions in here need Doxygen comments. */ /** - * \file SDL_audio.h + * # CategoryAudio * - * Access to the raw audio mixing buffer for the SDL library. + * Access to the raw audio mixing buffer for the SDL library. */ #ifndef SDL_audio_h_ diff --git a/include/SDL_bits.h b/include/SDL_bits.h index 77f258804e..0b22131c31 100644 --- a/include/SDL_bits.h +++ b/include/SDL_bits.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_bits.h + * # CategoryBits * - * Functions for fiddling with bits and bitmasks. + * Functions for fiddling with bits and bitmasks. */ #ifndef SDL_bits_h_ diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h index 5ac3e7d0c9..75d21fe631 100644 --- a/include/SDL_blendmode.h +++ b/include/SDL_blendmode.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_blendmode.h + * # CategoryBlendmode * - * Header file declaring the SDL_BlendMode enumeration + * Header file declaring the SDL_BlendMode enumeration */ #ifndef SDL_blendmode_h_ diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h index bd4b044c6d..3a02774615 100644 --- a/include/SDL_clipboard.h +++ b/include/SDL_clipboard.h @@ -20,7 +20,7 @@ */ /** - * \file SDL_clipboard.h + * # CategoryClipboard * * Include file for SDL clipboard handling */ diff --git a/include/SDL_config.h b/include/SDL_config.h index 49605b1e8a..dde6edd77b 100644 --- a/include/SDL_config.h +++ b/include/SDL_config.h @@ -24,9 +24,7 @@ #include "SDL_platform.h" -/** - * \file SDL_config.h - */ +/* WIKI CATEGORY: - */ /* Add any platform that doesn't build using the configure system. */ #if defined(__WIN32__) diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h index e8ac85dab6..b9d0958ff0 100644 --- a/include/SDL_cpuinfo.h +++ b/include/SDL_cpuinfo.h @@ -19,10 +19,16 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* WIKI CATEGORY: CPUInfo */ + /** - * \file SDL_cpuinfo.h + * # CategoryCPUInfo * - * CPU feature detection for SDL. + * CPU feature detection for SDL. + * + * These functions are largely concerned with reporting if the system has + * access to various SIMD instruction sets, but also has other important info + * to share, such as number of logical CPU cores. */ #ifndef SDL_cpuinfo_h_ @@ -30,8 +36,6 @@ #include "SDL_stdinc.h" -/* WIKI CATEGORY: CPUInfo */ - /* Need to do this here because intrin.h has C++ code in it */ /* Visual Studio 2005 has a bug where intrin.h conflicts with winnt.h */ #if defined(_MSC_VER) && (_MSC_VER >= 1500) && (defined(_M_IX86) || defined(_M_X64)) diff --git a/include/SDL_egl.h b/include/SDL_egl.h index a4276e6810..84c1f1b31f 100644 --- a/include/SDL_egl.h +++ b/include/SDL_egl.h @@ -19,11 +19,10 @@ 3. This notice may not be removed or altered from 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. */ + #if !defined(_MSC_VER) && !defined(__ANDROID__) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) #if defined(__vita__) || defined(__psp2__) diff --git a/include/SDL_endian.h b/include/SDL_endian.h index d203ed623a..38ae231f78 100644 --- a/include/SDL_endian.h +++ b/include/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/SDL_error.h b/include/SDL_error.h index 2df6463ad9..aca98f70c3 100644 --- a/include/SDL_error.h +++ b/include/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/SDL_events.h b/include/SDL_events.h index aa97bd22f7..2cb3238f7d 100644 --- a/include/SDL_events.h +++ b/include/SDL_events.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_events.h + * # CategoryEvents * - * Include file for SDL event handling. + * Include file for SDL event handling. */ #ifndef SDL_events_h_ diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h index 07498898d3..04e405dba1 100644 --- a/include/SDL_filesystem.h +++ b/include/SDL_filesystem.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_filesystem.h + * # CategoryFilesystem * - * \brief Include file for filesystem SDL API functions + * Include file for filesystem SDL API functions */ #ifndef SDL_filesystem_h_ diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index 04043a5db0..ced8dd9ea7 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -19,14 +19,14 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_gamecontroller.h - * - * Include file for SDL game controller event handling - */ - /* WIKI CATEGORY: GameController */ +/** + * # CategoryGameController + * + * Include file for SDL game controller event handling + */ + #ifndef SDL_gamecontroller_h_ #define SDL_gamecontroller_h_ diff --git a/include/SDL_gesture.h b/include/SDL_gesture.h index 4fffa5f3e8..685fdc5478 100644 --- a/include/SDL_gesture.h +++ b/include/SDL_gesture.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_gesture.h + * # CategoryGesture * - * Include file for SDL gesture event handling. + * Include file for SDL gesture event handling. */ #ifndef SDL_gesture_h_ diff --git a/include/SDL_guid.h b/include/SDL_guid.h index ec6be97085..0c3ff2633b 100644 --- a/include/SDL_guid.h +++ b/include/SDL_guid.h @@ -19,14 +19,15 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_guid.h - * - * Include file for handling SDL_GUID values. - */ - /* WIKI CATEGORY: GUID */ +/** + * # CategoryGUID + * + * A GUID is a 128-bit value that represents something that is uniquely + * identifiable by this value: "globally unique." + */ + #ifndef SDL_guid_h_ #define SDL_guid_h_ diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index abe0d048fc..660f531156 100644 --- a/include/SDL_haptic.h +++ b/include/SDL_haptic.h @@ -20,23 +20,23 @@ */ /** - * \file SDL_haptic.h + * # CategoryHaptic * - * \brief The SDL haptic subsystem allows you to control haptic (force feedback) - * devices. + * SDL haptic subsystem allows you to control haptic (force feedback) devices. * - * The basic usage is as follows: - * - Initialize the subsystem (SDL_INIT_HAPTIC). - * - Open a haptic device. - * - SDL_HapticOpen() to open from index. - * - SDL_HapticOpenFromJoystick() to open from an existing joystick. - * - Create an effect (SDL_HapticEffect). - * - Upload the effect with SDL_HapticNewEffect(). - * - Run the effect with SDL_HapticRunEffect(). - * - (optional) Free the effect with SDL_HapticDestroyEffect(). - * - Close the haptic device with SDL_HapticClose(). + * The basic usage is as follows: * - * \par Simple rumble example: + * - Initialize the subsystem (SDL_INIT_HAPTIC). + * - Open a haptic device. + * - SDL_HapticOpen() to open from index. + * - SDL_HapticOpenFromJoystick() to open from an existing joystick. + * - Create an effect (SDL_HapticEffect). + * - Upload the effect with SDL_HapticNewEffect(). + * - Run the effect with SDL_HapticRunEffect(). + * - (optional) Free the effect with SDL_HapticDestroyEffect(). + * - Close the haptic device with SDL_HapticClose(). + * + * Simple rumble example: * * ```c * SDL_Haptic *haptic; diff --git a/include/SDL_hidapi.h b/include/SDL_hidapi.h index 320bdb503f..a204a1433c 100644 --- a/include/SDL_hidapi.h +++ b/include/SDL_hidapi.h @@ -19,48 +19,51 @@ 3. This notice may not be removed or altered from any source distribution. */ +/* 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. */ -/* WIKI CATEGORY: HIDAPI */ - #ifndef SDL_hidapi_h_ #define SDL_hidapi_h_ diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 9a8e9bb26d..15f2af691f 100644 --- a/include/SDL_hints.h +++ b/include/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/SDL_joystick.h b/include/SDL_joystick.h index 4ce760dbc4..44529ede60 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -20,22 +20,26 @@ */ /** - * \file SDL_joystick.h + * # CategoryJoystick * - * Include file for SDL joystick event handling + * Include file for SDL joystick event handling * - * The term "device_index" identifies currently plugged in joystick devices between 0 and SDL_NumJoysticks(), with the exact joystick - * behind a device_index changing as joysticks are plugged and unplugged. + * The term "device_index" identifies currently plugged in joystick devices + * between 0 and SDL_NumJoysticks(), with the exact joystick behind a + * device_index changing as joysticks are plugged and unplugged. * - * 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. + * 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 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/SDL_keyboard.h b/include/SDL_keyboard.h index 4fd76e243b..21ef8c09fb 100644 --- a/include/SDL_keyboard.h +++ b/include/SDL_keyboard.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_keyboard.h + * # CategoryKeyboard * - * Include file for SDL keyboard event handling + * Include file for SDL keyboard event handling */ #ifndef SDL_keyboard_h_ diff --git a/include/SDL_keycode.h b/include/SDL_keycode.h index 1798e8a752..aefddb0a23 100644 --- a/include/SDL_keycode.h +++ b/include/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/SDL_loadso.h b/include/SDL_loadso.h index d5d9992adf..61b75b266e 100644 --- a/include/SDL_loadso.h +++ b/include/SDL_loadso.h @@ -19,27 +19,27 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \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. :) - */ - /* WIKI CATEGORY: LoadSO */ +/** + * # CategoryLoadSO + * + * 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_ #define SDL_loadso_h_ diff --git a/include/SDL_locale.h b/include/SDL_locale.h index 0b6118f0ef..983974be84 100644 --- a/include/SDL_locale.h +++ b/include/SDL_locale.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_locale.h + * # CategoryLocale * - * Include file for SDL locale services + * Include file for SDL locale services */ #ifndef _SDL_locale_h diff --git a/include/SDL_log.h b/include/SDL_log.h index 99709e4573..ab6c6248a3 100644 --- a/include/SDL_log.h +++ b/include/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/SDL_main.h b/include/SDL_main.h index 94e85bd4bf..7695ce32df 100644 --- a/include/SDL_main.h +++ b/include/SDL_main.h @@ -25,9 +25,9 @@ #include "SDL_stdinc.h" /** - * \file SDL_main.h + * # CategoryMain * - * Redefine main() on some platforms so that it is called by SDL. + * Redefine main() on some platforms so that it is called by SDL. */ #ifndef SDL_MAIN_HANDLED diff --git a/include/SDL_metal.h b/include/SDL_metal.h index d1d33d31df..cb4d7d353e 100644 --- a/include/SDL_metal.h +++ b/include/SDL_metal.h @@ -20,9 +20,10 @@ */ /** - * \file SDL_metal.h + * # CategoryMetal * - * Header file for functions to creating Metal layers and views on SDL windows. + * Header file for functions to creating Metal layers and views on SDL + * windows. */ #ifndef SDL_metal_h_ diff --git a/include/SDL_misc.h b/include/SDL_misc.h index 113ba7a156..752b3f6616 100644 --- a/include/SDL_misc.h +++ b/include/SDL_misc.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_misc.h + * # CategoryMisc * - * \brief Include file for SDL API functions that don't fit elsewhere. + * Include file for SDL API functions that don't fit elsewhere. */ #ifndef SDL_misc_h_ diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h index 6c3be151e6..b04e37551c 100644 --- a/include/SDL_mouse.h +++ b/include/SDL_mouse.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_mouse.h + * # CategoryMouse * - * Include file for SDL mouse event handling. + * Include file for SDL mouse event handling. */ #ifndef SDL_mouse_h_ diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h index 2722920675..2d615ae2cb 100644 --- a/include/SDL_mutex.h +++ b/include/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 "SDL_stdinc.h" diff --git a/include/SDL_opengl.h b/include/SDL_opengl.h index 2bb38c5c0e..7a2a7e4f8b 100644 --- a/include/SDL_opengl.h +++ b/include/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/SDL_opengles.h b/include/SDL_opengles.h index 7e9a1ab8d4..efdc649bd8 100644 --- a/include/SDL_opengles.h +++ b/include/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 "SDL_config.h" #ifdef __IPHONEOS__ diff --git a/include/SDL_opengles2.h b/include/SDL_opengles2.h index 96971344d1..6bf81f22e5 100644 --- a/include/SDL_opengles2.h +++ b/include/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 "SDL_config.h" #if !defined(_MSC_VER) && !defined(SDL_USE_BUILTIN_OPENGL_DEFINITIONS) diff --git a/include/SDL_pixels.h b/include/SDL_pixels.h index 2f3238423b..1a2af49ec8 100644 --- a/include/SDL_pixels.h +++ b/include/SDL_pixels.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_pixels.h + * # CategoryPixels * - * Header for the enumerated pixel format definitions. + * Header for the enumerated pixel format definitions. */ #ifndef SDL_pixels_h_ diff --git a/include/SDL_platform.h b/include/SDL_platform.h index e8bf11acfd..f9024d31b6 100644 --- a/include/SDL_platform.h +++ b/include/SDL_platform.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_platform.h + * # CategoryPlatform * - * Try to get a standard set of platform defines. + * Try to get a standard set of platform defines. */ #ifndef SDL_platform_h_ diff --git a/include/SDL_power.h b/include/SDL_power.h index 707741b260..af19b21fab 100644 --- a/include/SDL_power.h +++ b/include/SDL_power.h @@ -23,9 +23,9 @@ #define SDL_power_h_ /** - * \file SDL_power.h + * # CategoryPower * - * Header for the SDL power management routines. + * Header for the SDL power management routines. */ #include "SDL_stdinc.h" diff --git a/include/SDL_quit.h b/include/SDL_quit.h index b0c9ee87bd..6317c96518 100644 --- a/include/SDL_quit.h +++ b/include/SDL_quit.h @@ -20,19 +20,7 @@ */ /** - * \file SDL_quit.h - * - * Include file for SDL quit event handling. - */ - -#ifndef SDL_quit_h_ -#define SDL_quit_h_ - -#include "SDL_stdinc.h" -#include "SDL_error.h" - -/** - * \file SDL_quit.h + * # CategoryQuit * * An SDL_QUIT event is generated when the user tries to close the application * window. If it is ignored or filtered out, the window will remain open. @@ -46,10 +34,14 @@ * to determine the cause of an SDL_QUIT event, but setting a signal * handler in your application will override the default generation of * quit events for that signal. - * - * \sa SDL_Quit() */ +#ifndef SDL_quit_h_ +#define SDL_quit_h_ + +#include "SDL_stdinc.h" +#include "SDL_error.h" + /* There are no functions directly affecting the quit event */ #define SDL_QuitRequested() \ diff --git a/include/SDL_rect.h b/include/SDL_rect.h index 5ce1f0b451..c7307eb258 100644 --- a/include/SDL_rect.h +++ b/include/SDL_rect.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_rect.h + * # CategoryRect * - * Header file for SDL_rect definition and management functions. + * Header file for SDL_rect definition and management functions. */ #ifndef SDL_rect_h_ diff --git a/include/SDL_render.h b/include/SDL_render.h index 69beeeb7e9..262f85916e 100644 --- a/include/SDL_render.h +++ b/include/SDL_render.h @@ -20,29 +20,30 @@ */ /** - * \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 * - * 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/SDL_rwops.h b/include/SDL_rwops.h index 3d51a85e2e..1abbb138fb 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -19,15 +19,15 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_rwops.h - * - * This file provides a general interface for SDL to read and write - * data streams. It can easily be extended to files, memory, etc. - */ - /* WIKI CATEGORY: RWOPS */ +/** + * # CategoryRWOPS + * + * This file provides a general interface for SDL to read and write data + * streams. It can easily be extended to files, memory, etc. + */ + #ifndef SDL_rwops_h_ #define SDL_rwops_h_ diff --git a/include/SDL_scancode.h b/include/SDL_scancode.h index 57b6d12fba..6e53a3550b 100644 --- a/include/SDL_scancode.h +++ b/include/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/SDL_sensor.h b/include/SDL_sensor.h index a5e853d916..564a6fe7d2 100644 --- a/include/SDL_sensor.h +++ b/include/SDL_sensor.h @@ -20,10 +20,9 @@ */ /** - * \file SDL_sensor.h - * - * Include file for SDL sensor event handling + * # CategorySensor * + * Include file for SDL sensor event handling */ #ifndef SDL_sensor_h_ diff --git a/include/SDL_stdinc.h b/include/SDL_stdinc.h index cbf759863c..bdfcf2d7e8 100644 --- a/include/SDL_stdinc.h +++ b/include/SDL_stdinc.h @@ -19,14 +19,14 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_stdinc.h - * - * This is a general header that includes C language support. - */ - /* WIKI CATEGORY: StdInc */ +/** + * # CategoryStdInc + * + * This is a general header that includes C language support. + */ + #ifndef SDL_stdinc_h_ #define SDL_stdinc_h_ diff --git a/include/SDL_surface.h b/include/SDL_surface.h index 9c7dc6e283..ad72bf7402 100644 --- a/include/SDL_surface.h +++ b/include/SDL_surface.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_surface.h + * # CategorySurface * - * Header file for SDL_Surface definition and management functions. + * Header file for SDL_Surface definition and management functions. */ #ifndef SDL_surface_h_ diff --git a/include/SDL_system.h b/include/SDL_system.h index e0216a7dfe..03d75e4a95 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_system.h + * # CategorySystem * - * Include file for platform specific SDL API functions + * Include file for platform specific SDL API functions */ #ifndef SDL_system_h_ diff --git a/include/SDL_syswm.h b/include/SDL_syswm.h index 705bf6b018..7081adefec 100644 --- a/include/SDL_syswm.h +++ b/include/SDL_syswm.h @@ -19,10 +19,17 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_syswm.h +/* WIKI CATEGORY: SYSWM */ + +/* + * # CategorySYSWM * - * Include file for SDL custom system window manager hooks. + * Include file for SDL custom system window manager hooks. + * + * Your application has access to a special type of event SDL_SYSWMEVENT, + * which contains window-manager specific information and arrives whenever + * an unhandled window event occurs. This event is ignored by default, but + * you can enable it with SDL_EventState(). */ #ifndef SDL_syswm_h_ @@ -33,17 +40,6 @@ #include "SDL_video.h" #include "SDL_version.h" -/* - * \file SDL_syswm.h - * - * Your application has access to a special type of event SDL_SYSWMEVENT, - * which contains window-manager specific information and arrives whenever - * an unhandled window event occurs. This event is ignored by default, but - * you can enable it with SDL_EventState(). - */ - -/* WIKI CATEGORY: SYSWM */ - struct SDL_SysWMinfo; #if !defined(SDL_PROTOTYPES_ONLY) diff --git a/include/SDL_thread.h b/include/SDL_thread.h index 3c91417094..b09512e127 100644 --- a/include/SDL_thread.h +++ b/include/SDL_thread.h @@ -23,9 +23,9 @@ #define SDL_thread_h_ /** - * \file SDL_thread.h + * # CategoryThread * - * Header for the SDL thread management routines. + * Header for the SDL thread management routines. */ #include "SDL_stdinc.h" diff --git a/include/SDL_timer.h b/include/SDL_timer.h index 0add28b835..5e962e1d14 100644 --- a/include/SDL_timer.h +++ b/include/SDL_timer.h @@ -23,9 +23,9 @@ #define SDL_timer_h_ /** - * \file SDL_timer.h + * # CategoryTimer * - * Header for the SDL time management routines. + * Header for the SDL time management routines. */ #include "SDL_stdinc.h" diff --git a/include/SDL_touch.h b/include/SDL_touch.h index f6a5db413d..f4b0b66564 100644 --- a/include/SDL_touch.h +++ b/include/SDL_touch.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_touch.h + * # CategoryTouch * - * Include file for SDL touch event handling. + * Include file for SDL touch event handling. */ #ifndef SDL_touch_h_ diff --git a/include/SDL_types.h b/include/SDL_types.h index e8d33c6513..4440b02b4e 100644 --- a/include/SDL_types.h +++ b/include/SDL_types.h @@ -19,11 +19,6 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file SDL_types.h - * - * \deprecated - */ - /* DEPRECATED */ + #include "SDL_stdinc.h" diff --git a/include/SDL_version.h b/include/SDL_version.h index 087a03f3c3..120cd15c76 100644 --- a/include/SDL_version.h +++ b/include/SDL_version.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_version.h + * # CategoryVersion * - * This header defines the current SDL version. + * This header defines the current SDL version. */ #ifndef SDL_version_h_ diff --git a/include/SDL_video.h b/include/SDL_video.h index 529ff9c902..80ed6c1fed 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_video.h + * # CategoryVideo * - * Header file for SDL video functions. + * Header file for SDL video functions. */ #ifndef SDL_video_h_ diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h index 5b27366e2f..07adb8d33a 100644 --- a/include/SDL_vulkan.h +++ b/include/SDL_vulkan.h @@ -20,9 +20,9 @@ */ /** - * \file SDL_vulkan.h + * # CategoryVulkan * - * Header file for functions to creating Vulkan surfaces on SDL windows. + * Header file for functions to creating Vulkan surfaces on SDL windows. */ #ifndef SDL_vulkan_h_ diff --git a/include/begin_code.h b/include/begin_code.h index 1ee7567783..51f7b26403 100644 --- a/include/begin_code.h +++ b/include/begin_code.h @@ -19,16 +19,14 @@ 3. This notice may not be removed or altered from any source distribution. */ -/** - * \file 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. :) - */ - /* WIKI CATEGORY: BeginCode */ +/** + * 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. */ #ifdef SDL_begin_code_h #error Nested inclusion of begin_code.h