mirrors/SDL
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add missing '\param' documentation

Browse Source
This commit is contained in:
Sylvain 2023-02-12 09:40:39 +01:00 committed by Sylvain Becker
parent ce366facaa
commit 43c08170af
12 changed files with 83 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
include/SDL3/SDL_assert.h
View File

@ -130,19 +130,28 @@ typedef struct SDL_AssertData
#if (SDL_ASSERT_LEVEL > 0)
/* Never call this directly. Use the SDL_assert* macros. */
extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *,
const char *,
const char *, int)
/**
* Never call this directly. Use the SDL_assert* macros.
*
* \param data assert data structure
* \param func function name
* \param file file name
* \param line line number
* \returns assert state
*/
extern DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data,
const char *func,
const char *file, int line)
#if defined(__clang__)
#if __has_feature(attribute_analyzer_noreturn)
/* this tells Clang's static analysis that we're a custom assert function,
and that the analyzer should assume the condition was always true past this
SDL_assert test. */
__attribute__((analyzer_noreturn))
#endif
#endif
;
/* Previous 'analyzer_noreturn' attribute tells Clang's static analysis that we're a custom assert function,
and that the analyzer should assume the condition was always true past this
SDL_assert test. */
/* the do {} while(0) avoids dangling else problems:
if (x) SDL_assert(y); else blah();

3
include/SDL3/SDL_audio.h
View File

@ -768,6 +768,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void
* resample correctly, so this number might be lower than what you expect, or
* even be zero. Add more data or flush the stream if you need the data now.
*
* \param stream The audio stream to query
* \returns the number of converted/resampled bytes available.
*
* \since This function is available since SDL 3.0.0.
@ -789,6 +790,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
* audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available.
*
* \param stream The audio stream to flush
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -824,6 +826,7 @@ extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
/**
* Free an audio stream
*
* \param stream The audio stream to free
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_CreateAudioStream

7
include/SDL3/SDL_error.h
View File

@ -148,7 +148,12 @@ typedef enum
SDL_UNSUPPORTED,
SDL_LASTERROR
} SDL_errorcode;
/* SDL_Error() unconditionally returns -1. */
/**
* SDL_Error()
*
* \param code Error code
* \returns unconditionally -1.
*/
extern DECLSPEC int SDLCALL SDL_Error(SDL_errorcode code);
/* @} *//* Internal error functions */

11
include/SDL3/SDL_gamepad.h
View File

@ -232,6 +232,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadMappings(void);
/**
* Get the mapping at a particular index.
*
* \param mapping_index mapping index
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* the index is out of range.
*
@ -843,6 +844,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetGamepadButton(SDL_Gamepad *gamepad, SDL_Gam
/**
* Get the number of touchpads on a gamepad.
*
* \param gamepad a gamepad
* \returns number of touchpads
*
* \since This function is available since SDL 3.0.0.
@ -853,6 +855,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpads(SDL_Gamepad *gamepad);
* Get the number of supported simultaneous fingers on a touchpad on a game
* gamepad.
*
* \param gamepad a gamepad
* \param touchpad a touchpad
* \returns number of supported simultaneous fingers
*
* \since This function is available since SDL 3.0.0.
@ -862,6 +866,13 @@ extern DECLSPEC int SDLCALL SDL_GetNumGamepadTouchpadFingers(SDL_Gamepad *gamepa
/**
* Get the current state of a finger on a touchpad on a gamepad.
*
* \param gamepad a gamepad
* \param touchpad a touchpad
* \param finger a finger
* \param state filled with state
* \param x filled with x position
* \param y filled with y position
* \param pressure filled with pressure value
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*

1
include/SDL3/SDL_hidapi.h
View File

@ -235,6 +235,7 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id,
* platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
*
* \param path The path name of the device to open
* \param bExclusive exclusive opening (windows only?FIXME)
* \returns a pointer to a SDL_hid_device object on success or NULL on
* failure.
*

5
include/SDL3/SDL_joystick.h
View File

@ -309,6 +309,10 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GetJoystickFromPlayerIndex(int player_
/**
* Attach a new virtual joystick.
*
* \param type Type of joystick
* \param naxes number of axes
* \param nbuttons number of buttons
* \param nhats number of hats
* \returns the joystick instance ID, or 0 if an error occurred; call
* SDL_GetError() for more information.
*
@ -361,6 +365,7 @@ typedef struct SDL_VirtualJoystickDesc
/**
* Attach a new virtual joystick with extended properties.
*
* \param desc Joystick description
* \returns the joystick instance ID, or 0 if an error occurred; call
* SDL_GetError() for more information.
*

4
include/SDL3/SDL_metal.h
View File

@ -58,6 +58,7 @@ typedef void *SDL_MetalView;
* The returned handle can be casted directly to a NSView or UIView. To access
* the backing CAMetalLayer, call SDL_Metal_GetLayer().
*
* \param window the window
* \returns handle NSView or UIView
*
* \since This function is available since SDL 3.0.0.
@ -73,6 +74,8 @@ extern DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window * window);
* This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was
* called after SDL_CreateWindow.
*
* \param view the view
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_Metal_CreateView
@ -82,6 +85,7 @@ extern DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
/**
* Get a pointer to the backing CAMetalLayer for the given view.
*
* \param view the view
* \returns a pointer
*
* \since This function is available since SDL 3.0.0.

16
include/SDL3/SDL_surface.h
View File

@ -795,6 +795,12 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUnchecked
* Perform a fast, low quality, stretch blit between two surfaces of the same
* format.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the rectangle that is
* copied into
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -810,6 +816,12 @@ extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src,
/**
* Perform bilinear scaling between two surfaces of the same format, 32BPP.
*
* \param src the SDL_Surface structure to be copied from
* \param srcrect the SDL_Rect structure representing the rectangle to be
* copied
* \param dst the SDL_Surface structure that is the blit target
* \param dstrect the SDL_Rect structure representing the rectangle that is
* copied into
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
@ -867,6 +879,8 @@ extern DECLSPEC int SDLCALL SDL_BlitSurfaceUncheckedScaled
/**
* Set the YUV conversion mode
*
* \param YUV conversion mode
*
* \since This function is available since SDL 3.0.0.
*/
extern DECLSPEC void SDLCALL SDL_SetYUVConversionMode(SDL_YUV_CONVERSION_MODE mode);
@ -884,6 +898,8 @@ extern DECLSPEC SDL_YUV_CONVERSION_MODE SDLCALL SDL_GetYUVConversionMode(void);
* Get the YUV conversion mode, returning the correct mode for the resolution
* when the current conversion mode is SDL_YUV_CONVERSION_AUTOMATIC
*
* \param width width
* \param height height
* \returns YUV conversion mode
*
* \since This function is available since SDL 3.0.0.

2
include/SDL3/SDL_test_memory.h
View File

@ -39,7 +39,7 @@ extern "C" {
/**
* \brief Start tracking SDL memory allocations
*
*
* \note This should be called before any other SDL functions for complete tracking coverage
*/
int SDLTest_TrackAllocations(void);

17
include/SDL3/SDL_thread.h
View File

@ -118,6 +118,14 @@ typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
/*
* Create a SDL Thread
*
* \param fn Thread function
* \param name name
* \param data some data
* \param pfnSDL_CurrentBeginThread begin function
* \param pfnSDL_CurrentEndThread end function
*
* \returns SDL_Thread pointer
*/
extern DECLSPEC SDL_Thread *SDLCALL
@ -126,6 +134,15 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
pfnSDL_CurrentEndThread pfnEndThread);
/*
* Create a SDL Thread, with explicit stack size
*
* \param fn Thread function
* \param name name
* \param stacksize stack size
* \param data some data
* \param pfnSDL_CurrentBeginThread begin function
* \param pfnSDL_CurrentEndThread end function
*
* \returns SDL_Thread pointer
*/
extern DECLSPEC SDL_Thread *SDLCALL

2
include/SDL3/SDL_touch.h
View File

@ -99,6 +99,7 @@ extern DECLSPEC SDL_TouchID SDLCALL SDL_GetTouchDevice(int index);
* Get the touch device name as reported from the driver or NULL if the index
* is invalid.
*
* \param index the touch device index
* \returns touch device name
*
* \since This function is available since SDL 3.0.0.
@ -108,6 +109,7 @@ extern DECLSPEC const char* SDLCALL SDL_GetTouchName(int index);
/**
* Get the type of the given touch device.
*
* \param touchID the ID of a touch device
* \returns touch device type
*
* \since This function is available since SDL 3.0.0.

1
include/SDL3/SDL_video.h
View File

@ -1842,6 +1842,7 @@ extern DECLSPEC SDL_EGLConfig SDLCALL SDL_EGL_GetCurrentEGLConfig(void);
/**
* Get the EGL surface associated with the window.
*
* \param window the window to query
* \returns the EGLSurface pointer associated with the window, or NULL on
* failure.
*