Commit f8c1fc49d9d1b79b746248ee4855a3a497df8f5f

Ryan C. Gordon 2021-07-14T14:15:30

doxygen: Fix all the "\returns" so they work as part of complete sentences.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
diff --git a/include/SDL.h b/include/SDL.h
index f4576d6..633b5f4 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -178,7 +178,7 @@ extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
  * Get a mask of the specified subsystems which are currently initialized.
  *
  * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
- * \returns If `flags` is 0 it returns a mask of all initialized subsystems,
+ * \returns a mask of all initialized subsystems if `flags` is 0,
  *          otherwise it returns the initialization status of the specified
  *          subsystems.
  *
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 890fced..2d12fca 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -1032,7 +1032,7 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da
  * \param dev the device ID from which we will dequeue audio
  * \param data a pointer into where audio data should be copied
  * \param len the number of bytes (not samples!) to which (data) points
- * \returns number of bytes dequeued, which could be less than requested; call
+ * \returns the number of bytes dequeued, which could be less than requested; call
  *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 2.0.5.
diff --git a/include/SDL_bits.h b/include/SDL_bits.h
index 08b59ea..553b687 100644
--- a/include/SDL_bits.h
+++ b/include/SDL_bits.h
@@ -45,7 +45,7 @@ extern "C" {
  *  with 0. This operation can also be stated as "count leading zeroes" and
  *  "log base 2".
  *
- *  \return Index of the most significant bit, or -1 if the value is 0.
+ *  \return the index of the most significant bit, or -1 if the value is 0.
  */
 #if defined(__WATCOMC__) && defined(__386__)
 extern _inline int _SDL_bsr_watcom (Uint32);
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index 9c4c193..8fa8a2e 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -426,7 +426,7 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
  * not 64 for the AVX-512 instructions that exist but SDL doesn't know about.
  * Plan accordingly.
  *
- * \returns Alignment in bytes needed for available, known SIMD instructions.
+ * \returns the alignment in bytes needed for available, known SIMD instructions.
  */
 extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
 
@@ -459,7 +459,7 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
  *
  * \param len The length, in bytes, of the block to allocate. The actual
  *            allocated block might be larger due to padding, etc.
- * \returns Pointer to newly-allocated block, NULL if out of memory.
+ * \returns a pointer to thenewly-allocated block, NULL if out of memory.
  *
  * \sa SDL_SIMDAlignment
  * \sa SDL_SIMDRealloc
@@ -481,7 +481,7 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
  *            allocated block might be larger due to padding, etc. Passing 0
  *            will return a non-NULL pointer, assuming the system isn't out of
  *            memory.
- * \returns Pointer to newly-reallocated block, NULL if out of memory.
+ * \returns a pointer to the newly-reallocated block, NULL if out of memory.
  *
  * \sa SDL_SIMDAlignment
  * \sa SDL_SIMDAlloc
diff --git a/include/SDL_error.h b/include/SDL_error.h
index bb200c5..7085871 100644
--- a/include/SDL_error.h
+++ b/include/SDL_error.h
@@ -106,7 +106,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void);
  * \param errstr A buffer to fill with the last error message that was set
  *                for the current thread
  * \param maxlen The size of the buffer pointed to by the errstr parameter
- * \returns The pointer passed in as the `errstr` parameter.
+ * \returns the pointer passed in as the `errstr` parameter.
  *
  * \sa SDL_GetError
  */
diff --git a/include/SDL_events.h b/include/SDL_events.h
index 6a04391..8b26982 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -909,9 +909,8 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event);
  * \param userdata what was passed as `userdata` to SDL_SetEventFilter()
  *        or SDL_AddEventWatch, etc
  * \param event the event that triggered the callback
- * \returns Filters return 1 to permit event to be added to the queue, and
- *          0 to disallow it. When used with SDL_AddEventWatch, the return
- *          value is ignored.
+ * \returns 1 to permit event to be added to the queue, and 0 to disallow
+ *          it. When used with SDL_AddEventWatch, the return value is ignored.
  *
  * \sa SDL_SetEventFilter
  * \sa SDL_AddEventWatch
@@ -1074,7 +1073,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
  * 0xFFFFFFFF), but is clearer to write.
  *
  * \param numevents the number of events to be allocated
- * \returns The beginning event number, or (Uint32)-1 if there are not enough
+ * \returns the beginning event number, or (Uint32)-1 if there are not enough
  *          user-defined events left.
  *
  * \since This function is available since SDL 2.0.0.
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 15134ba..e5dbaa5 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -388,7 +388,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerGetType(SDL_Gam
  *  For XInput controllers this returns the XInput user index.
  *
  * \param gamecontroller the game controller object to query.
- * \returns player index for controller, or -1 if it's not available.
+ * \returns the player index for controller, or -1 if it's not available.
  */
 extern DECLSPEC int SDLCALL SDL_GameControllerGetPlayerIndex(SDL_GameController *gamecontroller);
 
@@ -406,7 +406,7 @@ extern DECLSPEC void SDLCALL SDL_GameControllerSetPlayerIndex(SDL_GameController
  * If the vendor ID isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB vendor ID, or zero if unavailable.
+ * \return the USB vendor ID, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *gamecontroller);
 
@@ -416,7 +416,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetVendor(SDL_GameController *g
  * If the product ID isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB product ID, or zero if unavailable.
+ * \return the USB product ID, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *gamecontroller);
 
@@ -426,7 +426,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProduct(SDL_GameController *
  * If the product version isn't available this function returns 0.
  *
  * \param gamecontroller the game controller object to query.
- * \return USB product version, or zero if unavailable.
+ * \return the USB product version, or zero if unavailable.
  */
 extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameController *gamecontroller);
 
@@ -436,7 +436,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_GameControllerGetProductVersion(SDL_GameContr
  * Returns the serial number of the controller, or NULL if it is not available.
  *
  * \param gamecontroller the game controller object to query.
- * \return Serial number, or NULL if unavailable.
+ * \return the serial number, or NULL if unavailable.
  */
 extern DECLSPEC const char * SDLCALL SDL_GameControllerGetSerial(SDL_GameController *gamecontroller);
 
diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h
index 3b2bf19..688ab95 100644
--- a/include/SDL_mutex.h
+++ b/include/SDL_mutex.h
@@ -105,7 +105,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex);
  * don't want to wait for it, and will return to it to try again later.
  *
  * \param mutex the mutex to try to lock
- * \returns return 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
+ * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call
  *          SDL_GetError() for more information.
  *
  * \sa SDL_CreateMutex
diff --git a/include/SDL_render.h b/include/SDL_render.h
index 21ce63a..f0bf8ca 100644
--- a/include/SDL_render.h
+++ b/include/SDL_render.h
@@ -1589,7 +1589,7 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
  * headers, but it can be safely cast to a `CAMetalLayer *`.
  *
  * \param renderer The renderer to query
- * \returns CAMetalLayer* on success, or NULL if the renderer isn't a Metal
+ * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a Metal
  *          renderer
  *
  * \sa SDL_RenderGetMetalCommandEncoder()
@@ -1603,7 +1603,7 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
  * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
  *
  * \param renderer The renderer to query
- * \returns `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
+ * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
  *          isn't a Metal renderer.
  *
  *  \sa SDL_RenderGetMetalLayer()
diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h
index 6b2a330..189d5e8 100644
--- a/include/SDL_sensor.h
+++ b/include/SDL_sensor.h
@@ -140,7 +140,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockSensors(void);
 /**
  * Count the number of sensors attached to the system right now.
  *
- * \returns The number of sensors detected.
+ * \returns the number of sensors detected.
  */
 extern DECLSPEC int SDLCALL SDL_NumSensors(void);
 
@@ -148,7 +148,7 @@ extern DECLSPEC int SDLCALL SDL_NumSensors(void);
  * Get the implementation dependent name of a sensor.
  *
  * \param device_index The sensor to obtain name from
- * \returns The sensor name, or NULL if `device_index` is out of range.
+ * \returns the sensor name, or NULL if `device_index` is out of range.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
 
@@ -156,7 +156,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index);
  * Get the type of a sensor.
  *
  * \param device_index The sensor to get the type from
- * \returns The SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
+ * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is
  *          out of range.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index);
@@ -165,7 +165,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index)
  * Get the platform dependent type of a sensor.
  *
  * \param device_index The sensor to check
- * \returns The sensor platform dependent type, or -1 if `device_index` is out
+ * \returns the sensor platform dependent type, or -1 if `device_index` is out
  *          of range.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index);
@@ -174,7 +174,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index)
  * Get the instance ID of a sensor.
  *
  * \param device_index The sensor to get instance id from
- * \returns The sensor instance ID, or -1 if `device_index` is out of range.
+ * \returns the sensor instance ID, or -1 if `device_index` is out of range.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_index);
 
@@ -182,7 +182,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_in
  * Open a sensor for use.
  *
  * \param device_index The sensor to open
- * \returns An SDL_Sensor sensor object, or NULL if an error occurred.
+ * \returns an SDL_Sensor sensor object, or NULL if an error occurred.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
 
@@ -190,7 +190,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index);
  * Return the SDL_Sensor associated with an instance id.
  *
  * \param instance_id The sensor from instance id
- * \returns An SDL_Sensor object.
+ * \returns an SDL_Sensor object.
  */
 extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instance_id);
 
@@ -198,7 +198,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instan
  * Get the implementation dependent name of a sensor
  *
  * \param sensor The SDL_Sensor object
- * \returns The sensor name, or NULL if `sensor` is NULL.
+ * \returns the sensor name, or NULL if `sensor` is NULL.
  */
 extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
 
@@ -206,7 +206,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetName(SDL_Sensor *sensor);
  * Get the type of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
+ * \returns the SDL_SensorType type, or `SDL_SENSOR_INVALID` if `sensor` is
  *          NULL.
  */
 extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
@@ -215,7 +215,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(SDL_Sensor *sensor);
  * Get the platform dependent type of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The sensor platform dependent type, or -1 if `sensor` is NULL.
+ * \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
  */
 extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
 
@@ -223,7 +223,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(SDL_Sensor *sensor);
  * Get the instance ID of a sensor.
  *
  * \param sensor The SDL_Sensor object to inspect
- * \returns The sensor instance ID, or -1 if `sensor` is NULL.
+ * \returns the sensor instance ID, or -1 if `sensor` is NULL.
  */
 extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor);
 
diff --git a/include/SDL_shape.h b/include/SDL_shape.h
index b8c05db..344d09c 100644
--- a/include/SDL_shape.h
+++ b/include/SDL_shape.h
@@ -59,7 +59,7 @@ extern "C" {
  *               ::SDL_WINDOW_MAXIMIZED,  ::SDL_WINDOW_MINIMIZED,
  *       ::SDL_WINDOW_BORDERLESS is always set, and ::SDL_WINDOW_FULLSCREEN is always unset.
  *
- *  \return The window created, or NULL if window creation failed.
+ *  \return the window created, or NULL if window creation failed.
  *
  *  \sa SDL_DestroyWindow()
  */
diff --git a/include/SDL_surface.h b/include/SDL_surface.h
index b6acd47..d238f1f 100644
--- a/include/SDL_surface.h
+++ b/include/SDL_surface.h
@@ -714,7 +714,7 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  *  surface (\c src or \c dst) is copied.  The final blit rectangles are saved
  *  in \c srcrect and \c dstrect after all clipping is performed.
  *
- *  \return If the blit is successful, it returns 0, otherwise it returns -1.
+ *  \returns 0 if the blit is successful, otherwise it returns -1.
  *
  *  The blit function should not be called on a locked surface.
  *
diff --git a/include/SDL_system.h b/include/SDL_system.h
index 6fea7d3..069c3f5 100644
--- a/include/SDL_system.h
+++ b/include/SDL_system.h
@@ -218,7 +218,7 @@ extern DECLSPEC void * SDLCALL SDL_AndroidGetActivity(void);
  * - API level 11: Android 3.0
  * - API level 10: Android 2.3.3
  *
- * \returns Android API level.
+ * \returns the Android API level.
  */
 extern DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void);
 
@@ -439,7 +439,7 @@ extern DECLSPEC const char * SDLCALL SDL_WinRTGetFSPathUTF8(SDL_WinRT_Path pathT
 /**
  * Detects the device family of WinRT plattform at runtime.
  *
- * \returns A value from the SDL_WinRT_DeviceFamily enum.
+ * \returns a value from the SDL_WinRT_DeviceFamily enum.
  */
 extern DECLSPEC SDL_WinRT_DeviceFamily SDLCALL SDL_WinRTGetDeviceFamily();
 
diff --git a/include/SDL_test_assert.h b/include/SDL_test_assert.h
index 55e32a4..d8e9d7d 100644
--- a/include/SDL_test_assert.h
+++ b/include/SDL_test_assert.h
@@ -66,7 +66,7 @@ void SDLTest_Assert(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *as
  * \param assertCondition Evaluated condition or variable to assert; fail (==0) or pass (!=0).
  * \param assertDescription Message to log with the assert describing it.
  *
- * \returns Returns the assertCondition so it can be used to externally to break execution flow if desired.
+ * \returns the assertCondition so it can be used to externally to break execution flow if desired.
  */
 int SDLTest_AssertCheck(int assertCondition, SDL_PRINTF_FORMAT_STRING const char *assertDescription, ...) SDL_PRINTF_VARARG_FUNC(2);
 
diff --git a/include/SDL_test_common.h b/include/SDL_test_common.h
index 6a49fa0..ff6c975 100644
--- a/include/SDL_test_common.h
+++ b/include/SDL_test_common.h
@@ -129,7 +129,7 @@ extern "C" {
  * \param argv Array of command line parameters
  * \param flags Flags indicating which subsystem to initialize (i.e. SDL_INIT_VIDEO | SDL_INIT_AUDIO)
  *
- * \returns Returns a newly allocated common state object.
+ * \returns a newly allocated common state object.
  */
 SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
 
@@ -139,7 +139,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
  * \param state The common state describing the test window to create.
  * \param index The index of the argument to process in argv[].
  *
- * \returns The number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
+ * \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
  */
 int SDLTest_CommonArg(SDLTest_CommonState * state, int index);
 
@@ -167,7 +167,7 @@ void SDLTest_CommonLogUsage(SDLTest_CommonState * state, const char *argv0, cons
  *  those strings' memory is freed and can no longer be used.
  *
  * \param state The common state describing the test window to create.
- * \returns String with usage information
+ * \returns a string with usage information
  */
 const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
 
@@ -176,7 +176,7 @@ const char *SDLTest_CommonUsage(SDLTest_CommonState * state);
  *
  * \param state The common state describing the test window to create.
  *
- * \returns True if initialization succeeded, false otherwise
+ * \returns SDL_TRUE if initialization succeeded, false otherwise
  */
 SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
 
@@ -187,7 +187,7 @@ SDL_bool SDLTest_CommonInit(SDLTest_CommonState * state);
  * \param argc argc, as supplied to SDL_main
  * \param argv argv, as supplied to SDL_main
  *
- * \returns False if app should quit, true otherwise.
+ * \returns SDL_FALSE if app should quit, true otherwise.
  */
 SDL_bool SDLTest_CommonDefaultArgs(SDLTest_CommonState * state, const int argc, char **argv);
 
diff --git a/include/SDL_test_font.h b/include/SDL_test_font.h
index f491289..daa6670 100644
--- a/include/SDL_test_font.h
+++ b/include/SDL_test_font.h
@@ -48,7 +48,7 @@ extern "C" {
  *  \param y The Y coordinate of the upper left corner of the character.
  *  \param c The character to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
 
@@ -60,7 +60,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, int x, int y, char c);
  *  \param y The Y coordinate of the upper left corner of the string.
  *  \param s The string to draw.
  *
- *  \returns Returns 0 on success, -1 on failure.
+ *  \returns 0 on success, -1 on failure.
  */
 int SDLTest_DrawString(SDL_Renderer *renderer, int x, int y, const char *s);
 
diff --git a/include/SDL_test_fuzzer.h b/include/SDL_test_fuzzer.h
index aa0b9a6..84278bf 100644
--- a/include/SDL_test_fuzzer.h
+++ b/include/SDL_test_fuzzer.h
@@ -66,14 +66,14 @@ void SDLTest_FuzzerInit(Uint64 execKey);
 /**
  * Returns a random Uint8
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint8 SDLTest_RandomUint8(void);
 
 /**
  * Returns a random Sint8
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint8 SDLTest_RandomSint8(void);
 
@@ -81,14 +81,14 @@ Sint8 SDLTest_RandomSint8(void);
 /**
  * Returns a random Uint16
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint16 SDLTest_RandomUint16(void);
 
 /**
  * Returns a random Sint16
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint16 SDLTest_RandomSint16(void);
 
@@ -96,7 +96,7 @@ Sint16 SDLTest_RandomSint16(void);
 /**
  * Returns a random integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Sint32 SDLTest_RandomSint32(void);
 
@@ -104,14 +104,14 @@ Sint32 SDLTest_RandomSint32(void);
 /**
  * Returns a random positive integer
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint32 SDLTest_RandomUint32(void);
 
 /**
  * Returns random Uint64.
  *
- * \returns Generated integer
+ * \returns a generated integer
  */
 Uint64 SDLTest_RandomUint64(void);
 
@@ -119,28 +119,28 @@ Uint64 SDLTest_RandomUint64(void);
 /**
  * Returns random Sint64.
  *
- * \returns Generated signed integer
+ * \returns a generated signed integer
  */
 Sint64 SDLTest_RandomSint64(void);
 
 /**
- * \returns random float in range [0.0 - 1.0[
+ * \returns a random float in range [0.0 - 1.0]
  */
 float SDLTest_RandomUnitFloat(void);
 
 /**
- * \returns random double in range [0.0 - 1.0[
+ * \returns a random double in range [0.0 - 1.0]
  */
 double SDLTest_RandomUnitDouble(void);
 
 /**
- * \returns random float.
+ * \returns a random float.
  *
  */
 float SDLTest_RandomFloat(void);
 
 /**
- * \returns random double.
+ * \returns a random double.
  *
  */
 double SDLTest_RandomDouble(void);
@@ -162,7 +162,7 @@ double SDLTest_RandomDouble(void);
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_bool validDomain);
 
@@ -183,7 +183,7 @@ Uint8 SDLTest_RandomUint8BoundaryValue(Uint8 boundary1, Uint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL_bool validDomain);
 
@@ -204,7 +204,7 @@ Uint16 SDLTest_RandomUint16BoundaryValue(Uint16 boundary1, Uint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL_bool validDomain);
 
@@ -225,7 +225,7 @@ Uint32 SDLTest_RandomUint32BoundaryValue(Uint32 boundary1, Uint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or 0 with error set
+ * \returns a random boundary value for the given range and domain or 0 with error set
  */
 Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL_bool validDomain);
 
@@ -246,7 +246,7 @@ Uint64 SDLTest_RandomUint64BoundaryValue(Uint64 boundary1, Uint64 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT8_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT8_MIN with error set
  */
 Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_bool validDomain);
 
@@ -268,7 +268,7 @@ Sint8 SDLTest_RandomSint8BoundaryValue(Sint8 boundary1, Sint8 boundary2, SDL_boo
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT16_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT16_MIN with error set
  */
 Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL_bool validDomain);
 
@@ -289,7 +289,7 @@ Sint16 SDLTest_RandomSint16BoundaryValue(Sint16 boundary1, Sint16 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT32_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT32_MIN with error set
  */
 Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL_bool validDomain);
 
@@ -310,7 +310,7 @@ Sint32 SDLTest_RandomSint32BoundaryValue(Sint32 boundary1, Sint32 boundary2, SDL
  * \param boundary2 Upper boundary limit
  * \param validDomain Should the generated boundary be valid (=within the bounds) or not?
  *
- * \returns Random boundary value for the given range and domain or SINT64_MIN with error set
+ * \returns a random boundary value for the given range and domain or SINT64_MIN with error set
  */
 Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL_bool validDomain);
 
@@ -324,7 +324,7 @@ Sint64 SDLTest_RandomSint64BoundaryValue(Sint64 boundary1, Sint64 boundary2, SDL
  * \param min Minimum inclusive value of returned random number
  * \param max Maximum inclusive value of returned random number
  *
- * \returns Generated random integer in range
+ * \returns a generated random integer in range
  */
 Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
 
@@ -336,7 +336,7 @@ Sint32 SDLTest_RandomIntegerInRange(Sint32 min, Sint32 max);
  *
  * Note: Returned string needs to be deallocated.
  *
- * \returns Newly allocated random string; or NULL if length was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if length was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiString(void);
 
@@ -350,7 +350,7 @@ char * SDLTest_RandomAsciiString(void);
  *
  * \param maxLength The maximum length of the generated string.
  *
- * \returns Newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if maxLength was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
 
@@ -364,12 +364,14 @@ char * SDLTest_RandomAsciiStringWithMaximumLength(int maxLength);
  *
  * \param size The length of the generated string
  *
- * \returns Newly allocated random string; or NULL if size was invalid or string could not be allocated.
+ * \returns a newly allocated random string; or NULL if size was invalid or string could not be allocated.
  */
 char * SDLTest_RandomAsciiStringOfSize(int size);
 
 /**
- * Returns the invocation count for the fuzzer since last ...FuzzerInit.
+ * Get the invocation count for the fuzzer since last ...FuzzerInit.
+ *
+ * \returns the invocation count.
  */
 int SDLTest_GetFuzzerInvocationCount(void);
 
diff --git a/include/SDL_test_harness.h b/include/SDL_test_harness.h
index 84212a6..106464c 100644
--- a/include/SDL_test_harness.h
+++ b/include/SDL_test_harness.h
@@ -105,7 +105,7 @@ typedef struct SDLTest_TestSuiteReference {
  *
  * \param length The length of the seed string to generate
  *
- * \returns The generated seed string
+ * \returns the generated seed string
  */
 char *SDLTest_GenerateRunSeed(const int length);
 
@@ -118,7 +118,7 @@ char *SDLTest_GenerateRunSeed(const int length);
  * \param filter Filter specification. NULL disables. Case sensitive.
  * \param testIterations Number of iterations to run each test case.
  *
- * \returns Test run result; 0 when all tests passed, 1 if any tests failed.
+ * \returns the test run result: 0 when all tests passed, 1 if any tests failed.
  */
 int SDLTest_RunSuites(SDLTest_TestSuiteReference *testSuites[], const char *userRunSeed, Uint64 userExecKey, const char *filter, int testIterations);
 
diff --git a/include/SDL_test_random.h b/include/SDL_test_random.h
index 2dfbfef..8297f94 100644
--- a/include/SDL_test_random.h
+++ b/include/SDL_test_random.h
@@ -98,7 +98,7 @@ extern "C" {
  *
  *  \param rndContext     pointer to context structure
  *
- *  \returns A random number (32bit unsigned integer)
+ *  \returns a random number (32bit unsigned integer)
  *
  */
  unsigned int SDLTest_Random(SDLTest_RandomContext *rndContext);
diff --git a/include/SDL_video.h b/include/SDL_video.h
index 44a7996..876c232 100644
--- a/include/SDL_video.h
+++ b/include/SDL_video.h
@@ -1244,7 +1244,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window);
  * Get a window's mouse grab mode.
  *
  * \param window the window to query
- * \returns This returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
+ * \returns SDL_TRUE if mouse is grabbed, and SDL_FALSE otherwise.
  *
  * \sa SDL_SetWindowKeyboardGrab
  * \sa SDL_GetWindowGrab
diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h
index 5307975..b8b58c2 100644
--- a/include/SDL_vulkan.h
+++ b/include/SDL_vulkan.h
@@ -114,7 +114,7 @@ extern DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
  * This should be called after either calling SDL_Vulkan_LoadLibrary()
  * or creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag.
  *
- * \returns The function pointer for `vkGetInstanceProcAddr` or NULL on error.
+ * \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
  */
 extern DECLSPEC void *SDLCALL SDL_Vulkan_GetVkGetInstanceProcAddr(void);