documentation: clean up a minor syntax issue.

build-scripts/wikiheaders.pl

@@ -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*//;

include/SDL3/SDL_audio.h

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

include/SDL3/SDL_camera.h

@@ -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.

include/SDL3/SDL_filesystem.h

@@ -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.

include/SDL3/SDL_pen.h

@@ -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

include/SDL3/SDL_stdinc.h

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

include/SDL3/SDL_video.h

@@ -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.

include/SDL3/SDL_vulkan.h

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