eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-06-06 23:40:54 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

documentation: clean up a minor syntax issue.

Browse source
This commit is contained in:
Ryan C. Gordon 2024-06-13 18:10:28 -04:00
parent 466886049c
commit 2ad7c70ac6
No known key found for this signature in database
GPG key ID: FA148B892AB48044
8 changed files with 31 additions and 23 deletions
Download patch file Download diff file Expand all files Collapse all files

8
build-scripts/wikiheaders.pl
View file

@ -1856,6 +1856,14 @@ if ($copy_direction == 1) { # --copy-to-headers
# !!! FIXME: complain if this isn't a function or macro. # !!! FIXME: complain if this isn't a function or macro.
my $retstr = "R$1"; # "Return" or "Returns" my $retstr = "R$1"; # "Return" or "Returns"
my $desc = $2; my $desc = $2;
if (0) { # !!! FIXME: disabled because it's not currently suitable for general use, but for manually inspecting the output, it can be useful.
if (($desc =~ /\A[A-Z]/) && (not $desc =~ /\ASDL_/)) {
print STDERR "WARNING: $sym\'s '\\returns' text starts with a capital letter: '$desc'. Fixing.\n";
$desc = lcfirst($desc);
}
}
while (@doxygenlines) { while (@doxygenlines) {
my $subline = $doxygenlines[0]; my $subline = $doxygenlines[0];
$subline =~ s/\A\s*//; $subline =~ s/\A\s*//;

6
include/SDL3/SDL_audio.h
View file

@ -588,7 +588,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid
* default device. * default device.
* \param spec the requested device configuration. Can be NULL to use * \param spec the requested device configuration. Can be NULL to use
* reasonable defaults. * reasonable defaults.
* \returns The device ID on success, 0 on error; call SDL_GetError() for more * \returns the device ID on success, 0 on error; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@ -805,7 +805,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
* ID. * ID.
* *
* \param stream the audio stream to query. * \param stream the audio stream to query.
* \returns The bound audio device, or 0 if not bound or invalid. * \returns the bound audio device, or 0 if not bound or invalid.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -1700,7 +1700,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src
* silence. * silence.
* *
* \param format the audio data format to query. * \param format the audio data format to query.
* \returns A byte value that can be passed to memset. * \returns a byte value that can be passed to memset.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *

10
include/SDL3/SDL_camera.h
View file

@ -228,14 +228,14 @@ extern SDL_DECLSPEC SDL_CameraDeviceID *SDLCALL SDL_GetCameraDevices(int *count)
extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(SDL_CameraDeviceID devid, int *count); extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraDeviceSupportedFormats(SDL_CameraDeviceID devid, int *count);
/** /**
* Get human-readable device name for a camera. * Get the human-readable device name for a camera.
* *
* The returned string is owned by the caller; please release it with * The returned string is owned by the caller; please release it with
* SDL_free() when done with it. * SDL_free() when done with it.
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID
* \returns Human-readable device name, or NULL on error; call SDL_GetError() * \returns a human-readable device name, or NULL on error; call
* for more information. * SDL_GetError() for more information.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -254,7 +254,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetCameraDeviceName(SDL_CameraDeviceID in
* filming in the direction the user is facing). * filming in the direction the user is facing).
* *
* \param instance_id the camera device instance ID * \param instance_id the camera device instance ID
* \returns The position of the camera on the system hardware. * \returns the position of the camera on the system hardware.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -431,7 +431,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_Came
* \param camera opened camera device * \param camera opened camera device
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on * \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
* error. Can be NULL. * error. Can be NULL.
* \returns A new frame of video on success, NULL if none is currently * \returns a new frame of video on success, NULL if none is currently
* available. * available.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.

2
include/SDL3/SDL_filesystem.h
View file

@ -233,7 +233,7 @@ typedef enum SDL_Folder
* If NULL is returned, the error may be obtained with SDL_GetError(). * If NULL is returned, the error may be obtained with SDL_GetError().
* *
* \param folder The type of folder to find * \param folder The type of folder to find
* \returns Either a null-terminated C string containing the full path to the * \returns either a null-terminated C string containing the full path to the
* folder, or NULL if an error happened. * folder, or NULL if an error happened.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

10
include/SDL3/SDL_pen.h
View file

@ -156,7 +156,7 @@ typedef enum SDL_PenSubtype
* *
* \param count The number of pens in the array (number of array elements * \param count The number of pens in the array (number of array elements
* minus 1, i.e., not counting the terminator 0). * minus 1, i.e., not counting the terminator 0).
* \returns A 0 terminated array of SDL_PenID values, or NULL on error. The * \returns a 0 terminated array of SDL_PenID values, or NULL on error. The
* array must be freed with SDL_free(). On a NULL return, * array must be freed with SDL_free(). On a NULL return,
* SDL_GetError() is set. * SDL_GetError() is set.
* *
@ -189,7 +189,7 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetPenStatus(SDL_PenID instance_id, float
* Retrieves an SDL_PenID for the given SDL_GUID. * Retrieves an SDL_PenID for the given SDL_GUID.
* *
* \param guid A pen GUID. * \param guid A pen GUID.
* \returns A valid SDL_PenID, or SDL_PEN_INVALID if there is no matching * \returns a valid SDL_PenID, or SDL_PEN_INVALID if there is no matching
* SDL_PenID. * SDL_PenID.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -200,7 +200,7 @@ extern SDL_DECLSPEC SDL_PenID SDLCALL SDL_GetPenFromGUID(SDL_GUID guid);
* Retrieves the SDL_GUID for a given SDL_PenID. * Retrieves the SDL_GUID for a given SDL_PenID.
* *
* \param instance_id The pen to query. * \param instance_id The pen to query.
* \returns The corresponding pen GUID; persistent across multiple sessions. * \returns the corresponding pen GUID; persistent across multiple sessions.
* If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID. * If "instance_id" is SDL_PEN_INVALID, returns an all-zeroes GUID.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -227,7 +227,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_PenConnected(SDL_PenID instance_id);
* The returned string follows the SDL_GetStringRule. * The returned string follows the SDL_GetStringRule.
* *
* \param instance_id The pen to query. * \param instance_id The pen to query.
* \returns A string that contains the name of the pen, intended for human * \returns a string that contains the name of the pen, intended for human
* consumption. The string might or might not be localised, depending * consumption. The string might or might not be localised, depending
* on platform settings. It is not guaranteed to be unique; use * on platform settings. It is not guaranteed to be unique; use
* SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer * SDL_GetPenGUID() for (best-effort) unique identifiers. The pointer
@ -267,7 +267,7 @@ extern SDL_DECLSPEC SDL_PenCapabilityFlags SDLCALL SDL_GetPenCapabilities(SDL_Pe
* Retrieves the pen type for a given SDL_PenID. * Retrieves the pen type for a given SDL_PenID.
* *
* \param instance_id The pen to query. * \param instance_id The pen to query.
* \returns The corresponding pen type (cf. SDL_PenSubtype) or 0 on error. * \returns the corresponding pen type (cf. SDL_PenSubtype) or 0 on error.
* Note that the pen type does not dictate whether the pen tip is * Note that the pen type does not dictate whether the pen tip is
* SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen * SDL_PEN_TIP_INK or SDL_PEN_TIP_ERASER; to determine whether a pen
* is being used for drawing or in eraser mode, check either the pen * is being used for drawing or in eraser mode, check either the pen

8
include/SDL3/SDL_stdinc.h
View file

@ -855,7 +855,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_isgraph(int x);
* cannot be converted, or is already uppercase, this function returns `x`. * cannot be converted, or is already uppercase, this function returns `x`.
* *
* \param x character value to check. * \param x character value to check.
* \returns Capitalized version of x, or x if no conversion available. * \returns capitalized version of x, or x if no conversion available.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -873,7 +873,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x);
* cannot be converted, or is already lowercase, this function returns `x`. * cannot be converted, or is already lowercase, this function returns `x`.
* *
* \param x character value to check. * \param x character value to check.
* \returns Lowercase version of x, or x if no conversion available. * \returns lowercase version of x, or x if no conversion available.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -1077,7 +1077,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strrev(char *str);
* uppercase equivalents in-place, returning the original `str` pointer. * uppercase equivalents in-place, returning the original `str` pointer.
* *
* \param str The string to convert in-place. Can not be NULL. * \param str The string to convert in-place. Can not be NULL.
* \returns The `str` pointer passed into this function. * \returns the `str` pointer passed into this function.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -1098,7 +1098,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strupr(char *str);
* lowercase equivalents in-place, returning the original `str` pointer. * lowercase equivalents in-place, returning the original `str` pointer.
* *
* \param str The string to convert in-place. Can not be NULL. * \param str The string to convert in-place. Can not be NULL.
* \returns The `str` pointer passed into this function. * \returns the `str` pointer passed into this function.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *

8
include/SDL3/SDL_video.h
View file

@ -507,7 +507,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(SDL_DisplayID display
* Get the orientation of a display when it is unrotated. * Get the orientation of a display when it is unrotated.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query
* \returns The SDL_DisplayOrientation enum value of the display, or * \returns the SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available. * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -520,7 +520,7 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetNaturalDisplayOrientat
* Get the orientation of a display. * Get the orientation of a display.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query
* \returns The SDL_DisplayOrientation enum value of the display, or * \returns the SDL_DisplayOrientation enum value of the display, or
* `SDL_ORIENTATION_UNKNOWN` if it isn't available. * `SDL_ORIENTATION_UNKNOWN` if it isn't available.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -538,7 +538,7 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat
* big on this display, to aid in readability. * big on this display, to aid in readability.
* *
* \param displayID the instance ID of the display to query * \param displayID the instance ID of the display to query
* \returns The content scale of the display, or 0.0f on error; call * \returns the content scale of the display, or 0.0f on error; call
* SDL_GetError() for more details. * SDL_GetError() for more details.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
@ -2086,7 +2086,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window *window, const
* Get the mouse confinement rectangle of a window. * Get the mouse confinement rectangle of a window.
* *
* \param window The window to query * \param window The window to query
* \returns A pointer to the mouse confinement rectangle of a window, or NULL * \returns a pointer to the mouse confinement rectangle of a window, or NULL
* if there isn't one. * if there isn't one.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.

2
include/SDL3/SDL_vulkan.h
View file

@ -148,7 +148,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
* You should not free the returned array; it is owned by SDL. * You should not free the returned array; it is owned by SDL.
* *
* \param count a pointer filled in with the number of extensions returned. * \param count a pointer filled in with the number of extensions returned.
* \returns An array of extension name strings on success, NULL on error. * \returns an array of extension name strings on success, NULL on error.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *