From 21bc72bef17319b7d362b2e3f23a162771284caa Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sat, 13 Apr 2024 22:55:23 -0400
Subject: [PATCH] wikiheaders: Allow parts of the headers to be ignored.
The specific cases here were SDL_size_mul_overflow_builtin and
SDL_size_add_overflow_builtin, which are forced-inline symbols in
SDL_stdinc.h that have to exist, but aren't really part of the public API,
and thus shouldn't be exported as documentation.
---
build-scripts/wikiheaders.pl | 14 +++++++++++++-
include/SDL3/SDL_endian.h | 3 +--
include/SDL3/SDL_stdinc.h | 4 ++++
3 files changed, 18 insertions(+), 3 deletions(-)
diff --git a/build-scripts/wikiheaders.pl b/build-scripts/wikiheaders.pl
index 53fbaf598e3ed..b81025e5674d8 100755
--- a/build-scripts/wikiheaders.pl
+++ b/build-scripts/wikiheaders.pl
@@ -594,6 +594,7 @@ sub print_undocumented_section {
open(FH, '<', "$incpath/$dent") or die("Can't open '$incpath/$dent': $!\n");
my @contents = ();
+ my $ignoring_lines = 0;
while (<FH>) {
chomp;
@@ -606,7 +607,18 @@ sub print_undocumented_section {
# Since a lot of macros are just preprocessor logic spam and not all macros are worth documenting anyhow, we only pay attention to them when they have a Doxygen comment attached.
# Functions and other things are a different story, though!
- if (/\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC/) { # a function declaration without a doxygen comment?
+ if ($ignoring_lines && /\A\s*\#\s*endif\s*\Z/) {
+ $ignoring_lines = 0;
+ push @contents, $_;
+ next;
+ } elsif ($ignoring_lines) {
+ push @contents, $_;
+ next;
+ } elsif (/\A\s*\#\s*ifndef\s+SDL_WIKI_DOCUMENTATION_SECTION\s*\Z/) {
+ $ignoring_lines = 1;
+ push @contents, $_;
+ next;
+ } elsif (/\A\s*extern\s+(SDL_DEPRECATED\s+|)DECLSPEC/) { # a function declaration without a doxygen comment?
$symtype = 1; # function declaration
@templines = ();
$decl = $_;
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index 208fb593b124a..f1c03e512804d 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -238,8 +238,7 @@ SDL_FORCE_INLINE Uint32 SDL_Swap32(Uint32 x)
#pragma intrinsic(_byteswap_uint64)
#define SDL_Swap64(x) _byteswap_uint64(x)
#elif defined(__i386__) && !HAS_BROKEN_BSWAP
-SDL_FORCE_INLINE Uint64
-SDL_Swap64(Uint64 x)
+SDL_FORCE_INLINE Uint64 SDL_Swap64(Uint64 x)
{
union {
struct {
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index b3b12a616cf84..00a54a139f33d 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -2476,6 +2476,7 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow (size_t a,
return 0;
}
+#ifndef SDL_WIKI_DOCUMENTATION_SECTION
#if SDL_HAS_BUILTIN(__builtin_mul_overflow)
/* This needs to be wrapped in an inline rather than being a direct #define,
* because __builtin_mul_overflow() is type-generic, but we want to be
@@ -2488,6 +2489,7 @@ SDL_FORCE_INLINE int SDL_size_mul_overflow_builtin (size_t a,
}
#define SDL_size_mul_overflow(a, b, ret) (SDL_size_mul_overflow_builtin(a, b, ret))
#endif
+#endif
/**
* If a + b would overflow, return -1.
@@ -2507,6 +2509,7 @@ SDL_FORCE_INLINE int SDL_size_add_overflow (size_t a,
return 0;
}
+#ifndef SDL_WIKI_DOCUMENTATION_SECTION
#if SDL_HAS_BUILTIN(__builtin_add_overflow)
/* This needs to be wrapped in an inline rather than being a direct #define,
* the same as the call to __builtin_mul_overflow() above. */
@@ -2518,6 +2521,7 @@ SDL_FORCE_INLINE int SDL_size_add_overflow_builtin (size_t a,
}
#define SDL_size_add_overflow(a, b, ret) (SDL_size_add_overflow_builtin(a, b, ret))
#endif
+#endif
/* This is a generic function pointer which should be cast to the type you expect */
#ifdef SDL_FUNCTION_POINTER_IS_VOID_POINTER