mirrors
/
SDL
mirror of https://github.com/libsdl-org/SDL
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

documentation: clean up a minor syntax issue.

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
Show Stats 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.
my $retstr = "R$1"; # "Return" or "Returns"
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) {
my $subline = $doxygenlines[0];
$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.
* \param spec the requested device configuration. Can be NULL to use
* 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.
*
* \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.
*
* \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.
*
@ -1700,7 +1700,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src
* silence.
*
* \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.
*

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);
/**
* 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
* SDL_free() when done with it.
*
* \param instance_id the camera device instance ID
* \returns Human-readable device name, or NULL on error; call SDL_GetError()
* for more information.
* \returns a human-readable device name, or NULL on error; call
* SDL_GetError() for more information.
*
* \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).
*
* \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.
*
@ -431,7 +431,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCameraFormat(SDL_Camera *camera, SDL_Came
* \param camera opened camera device
* \param timestampNS a pointer filled in with the frame's timestamp, or 0 on
* 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.
*
* \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().
*
* \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.
*
* \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
* 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,
* 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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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
* on platform settings. It is not guaranteed to be unique; use
* 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.
*
* \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
* 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

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`.
*
* \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.
*
@ -873,7 +873,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_toupper(int x);
* cannot be converted, or is already lowercase, this function returns `x`.
*
* \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.
*
@ -1077,7 +1077,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strrev(char *str);
* uppercase equivalents in-place, returning the original `str` pointer.
*
* \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.
*
@ -1098,7 +1098,7 @@ extern SDL_DECLSPEC char *SDLCALL SDL_strupr(char *str);
* lowercase equivalents in-place, returning the original `str` pointer.
*
* \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.
*

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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*
* \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.
*