Skip to content

Commit

Permalink
wikiheaders: Allow parts of the headers to be ignored.
Browse files Browse the repository at this point in the history
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.
icculus committed Apr 14, 2024

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
1 parent e4f0978 commit 21bc72b
Showing 3 changed files with 18 additions and 3 deletions.
14 changes: 13 additions & 1 deletion build-scripts/wikiheaders.pl
Original file line number Diff line number Diff line change
@@ -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 = $_;
3 changes: 1 addition & 2 deletions include/SDL3/SDL_endian.h
Original file line number Diff line number Diff line change
@@ -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 {
4 changes: 4 additions & 0 deletions include/SDL3/SDL_stdinc.h
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 21bc72b

Please sign in to comment.