Add Doxygen-styled comments to parts of the libretro API (#15641)

* Touch up the documentation for a few environment calls

* Touch up more comments

* Update docs for more environment calls

* Add doc comments for more environment calls

* Change various @returns to indicate that the environment call is available

- Some environment calls might be recognized but ignored (e.g. when fast-forwarding during netplay)

* Note some deprecated symbols

* Touch up the docs for RETRO_ENVIRONMENT_SET_MESSAGE

* Touch up the docs for RETRO_ENVIRONMENT_SET_PIXEL_FORMAT

* Add more doc comments

* (libretro) Add more doxygen documentation for the libretro API

* (libretro) Add doxygen comments for the callbacks

* Document retro_init and retro_deinit

* Add comments for retro_log-related symbols

* Add a comment

* Clean up some camera-related comments

* Clean up frame time-related callbacks

* Correct some information about major callbacks

* Clarify some parameter info

* Fix incorrect info about retro_set_environment

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* (libretro) Add doxygen docs on RETRO_THROTTLE

* Touch up the docs for RETRO_ENVIRONMENT_SET_AUDIO_CALLBACK

* Touch up the docs for some macros

* Touch up the docs for some more environment calls

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Tidy up the doc comments for clamping.h

- It was a low-hanging fruit

* Define some sections for constants

- Doxygen will group all contained symbols on one page

* Fix a duplicate @see

* Polish up the docs for the rumble interface

* Polish up the docs for RETRO_ENVIRONMENT_GET_INPUT_DEVICE_CAPABILITIES

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Document INLINE

* Clean up some tags

* Touch up the docs for the sensor interface

* Add docs for RETRO_ENVIRONMENT_SET_PROC_ADDRESS_CALLBACK

* Update docs for RETRO_ENVIRONMENT_GET_INPUT_BITMASKS and accompanying names

* Update some group definitions

* Spiff up the docs for retro_dirent.h

* Document dylib.h

* Document base64.h

* Document crc32.h

* Touch up the docs for audio conversion functions

* Clean up some Doxygen tags

* Refine the docs for RETRO_ENVIRONMENT_GET_PERF_INTERFACE

* Fix incorrect infor in dylib.h

* Touch up the docs for RETRO_ENVIRONMENT_GET_CAMERA_INTERFACE

* Revise the docs for RETRO_ENVIRONMENT_SET_GEOMETRY

* Revise the docs for RETRO_ENVIRONMENT_GET_LOCATION_INTERFACE

* Revise a function's doc

* Touch up most of the rthreads docs

* Touch up the retro_timers.h docs

* Revise the subsystem docs

* Fix some incorrect @see's

* Touch up the docs for RETRO_ENVIRONMENT_GET_LED_INTERFACE

* Give the RETRO_ENVIRONMENT_GET_SAVESTATE_CONTEXT docs a makeover

* Slight cleanup to the microphone docs

* Slight cleanup to the device power docs

* Touch up serialization quirk docs

* Give the MIDI docs a haircut

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Freshen up rtime's docs

* Improve the docs and accompanying definitions for RETRO_ENVIRONMENT_GET_AUDIO_VIDEO_ENABLE

- Revise the text of the documentation
- Introduce an enum that defines the flags (it's still an int, so ABI compatibility will be fine)
- Move the documentation for each bit to its corresponding enum

* Shine the shoes of RETRO_ENVIRONMENT_GET_INPUT_MAX_USERS's docs

* Freshen up the docs for fifo_queue.h

* Document most of task_queue.h

* Put retro_dirent's symbols in a group

* Finish documenting task_queue.h

* Document some compatibility headers

* Document read_stdin

* Document file_stream_transforms.h

* Document the VFS API

- Not the wrappers, just the plain API itself

* (Docs) Add doxygen notes about RETRO_DEVICE_*

* Fix some line breaks

* Revise RETRO_DEVICE docs

* Document strl.h

* Update the features_cpu.h docs

* Rewrite the docs for file_stream.h

* Update the docs for retro_endianness.h

* Update the docs for retro_miscellaneous.h

* Document the RETRO_VFS_SEEK_POSITION constants

* Finish documenting rthreads.h

* Document network_stream.h

* Put the RETRO_MEMORY defines in a defgroup

* Move a doc comment in retro_common.h to file scope

* Revise the docs for RETRO_ENVIRONMENT_SET_CONTROLLER_INFO, and accompanying symbols

* Fix the @param/in/out order in libretro.h's @param declarations

* Tidy up the docs for RETRO_ENVIRONMENT_GET_CORE_OPTIONS_VERSION

* Spiff up the docs for RETRO_ENVIRONMENT_GET_CURRENT_SOFTWARE_FRAMEBUFFER

* Fix some tags

* Polish up RETRO_ENVIRONMENT_GET_HW_RENDER_INTERFACE's docs

* libretro: Add header doxygen

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Update libretro-common/include/libretro.h

Co-authored-by: Rob Loach <[email protected]>

* Clean up the docs for RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY

* Clean up the docs for RETRO_ENVIRONMENT_SET_HW_RENDER_CONTEXT_NEGOTIATION_INTERFACE

* Touch up some comment syntax for RETRO_ENVIRONMENT_GET_VARIABLE_UPDATE

* Fix some inaccuracies

* Re-add the license statement for libretro.h

* Touch up the docs for RETRO_ENVIRONMENT_SET_CORE_OPTIONS_V2

* Touch up docs for RETRO_ENVIRONMENT_SET_CORE_OPTIONS_DISPLAY

* Touch up docs for some options-related symbols

* Fix some syntax that was preventing most doc files from being generated

* Express retro_core_option_definition docs in terms of retro_core_option_v2_definition

* Finalize some core option-related docs

* Fix some incorrect info about achievements

* Polish up the docs for RETRO_ENVIRONMENT_SET_MEMORY_MAPS

* Polish up the docs for RETRO_ENVIRONMENT_GET_DISK_CONTROL_INTERFACE_VERSION

* Add a notice for `RETRO_ENVIRONMENT_GET_LOG_INTERFACE`

* Update the disk control interface docs

* Add a sentence to a doc comment

* Update a comment

* Remove an irrelevant @todo

* Touch up the docs for `retro_message_target`

* Touch up the docs for `retro_message_type`

* Touch up the docs for `RETRO_ENVIRONMENT_SET_MESSAGE_EXT`

* Touch up the docs for `RETRO_ENVIRONMENT_SET_AUDIO_BUFFER_STATUS_CALLBACK`

* Touch up the docs for `RETRO_ENVIRONMENT_SET_MINIMUM_AUDIO_LATENCY`

* Revise a comment

* Revise the docs for `RETRO_ENVIRONMENT_SET_VARIABLE`

* Add a `@see`

* Clean up the `RETRO_ENVIRONMENT_SET_FASTFORWARDING_OVERRIDE` docs

* Update the Doxyfile

* libretro: Add three more environment callback doxygen docs

* doxygen: Remove @example reference

---------

Co-authored-by: Rob Loach <[email protected]>

libretro-common/features/features_cpu.c

@@ -150,13 +150,6 @@ static int ra_clock_gettime(int clk_ik, struct timespec *t)
 
 #include <string.h>
 
-/**
- * cpu_features_get_perf_counter:
- *
- * Gets performance counter.
- *
- * @return Performance counter.
- **/
 retro_perf_tick_t cpu_features_get_perf_counter(void)
 {
    retro_perf_tick_t time_ticks = 0;
@@ -218,13 +211,6 @@ retro_perf_tick_t cpu_features_get_perf_counter(void)
    return time_ticks;
 }
 
-/**
- * cpu_features_get_time_usec:
- *
- * Gets time in microseconds.
- *
- * @return Time in microseconds.
- **/
 retro_time_t cpu_features_get_time_usec(void)
 {
 #if defined(_WIN32)
@@ -503,13 +489,6 @@ static void cpulist_read_from(CpuList* list, const char* filename)
 
 #endif
 
-/**
- * cpu_features_get_core_amount:
- *
- * Gets the amount of available CPU cores.
- *
- * @return Amount of CPU cores available.
- **/
 unsigned cpu_features_get_core_amount(void)
 {
 #if defined(_WIN32) && !defined(_XBOX)
@@ -609,13 +588,6 @@ unsigned cpu_features_get_core_amount(void)
 #define VENDOR_INTEL_c  0x6c65746e
 #define VENDOR_INTEL_d  0x49656e69
 
-/**
- * cpu_features_get:
- *
- * Gets CPU features..
- *
- * @return Bitmask of all CPU features available.
- **/
 uint64_t cpu_features_get(void)
 {
    uint64_t cpu        = 0;

libretro-common/include/audio/conversion/float_to_s16.h

@@ -31,22 +31,28 @@ RETRO_BEGIN_DECLS
 #include <stddef.h>
 
 /**
- * convert_float_to_s16:
- * @out               : output buffer
- * @in                : input buffer
- * @samples           : size of samples to be converted
+ * Converts an array of floating-point audio samples
+ * to signed integer 16-bit audio samples,
+ * possibly using SIMD intrinsics.
  *
- * Converts floating point
- * to signed integer 16-bit.
+ * @param out The buffer that will be used to store the converted samples.
+ * @param in The buffer containing the samples to convert.
+ * Any number of channels is supported.
+ * @param samples The length of \c in in samples, \em not bytes or frames.
+ * \c out must be as large as <tt>sizeof(int16_t) * samples</tt>.
+ * @see convert_s16_to_float
  **/
 void convert_float_to_s16(int16_t *out,
       const float *in, size_t samples);
 
 /**
- * convert_float_to_s16_init_simd:
+ * Initializes any prerequisites for
+ * using SIMD implementations of \c convert_float_to_s16.
  *
- * Sets up function pointers for conversion
- * functions based on CPU features.
+ * If SIMD intrinsics are not available or no initialization is required,
+ * this function does nothing.
+ *
+ * @see convert_float_to_s16
  **/
 void convert_float_to_s16_init_simd(void);
 

libretro-common/include/audio/conversion/s16_to_float.h

@@ -30,23 +30,30 @@
 RETRO_BEGIN_DECLS
 
 /**
- * convert_s16_to_float:
- * @out               : output buffer
- * @in                : input buffer
- * @samples           : size of samples to be converted
- * @gain              : gain applied (.e.g. audio volume)
+ * Converts an array of signed integer 16-bit audio samples
+ * to floating-point format,
+ * possibly using SIMD intrinsics.
  *
- * Converts from signed integer 16-bit
- * to floating point.
+ * @param out The buffer that will be used to store the converted samples.
+ * @param in The buffer containing the samples to convert.
+ * Any number of channels is supported.
+ * @param samples The length of \c in in samples, \em not bytes or frames.
+ * \c out must be as large as <tt>sizeof(float) * samples</tt>.
+ * @param gain The gain (audio volume) to apply to the samples.
+ * Pass a value of 1.0 to not apply any gain.
+ * @see convert_float_to_s16
  **/
 void convert_s16_to_float(float *out,
       const int16_t *in, size_t samples, float gain);
 
 /**
- * convert_s16_to_float_init_simd:
+ * Initializes any prerequisites for
+ * using SIMD implementations of \c convert_s16_to_float.
  *
- * Sets up function pointers for conversion
- * functions based on CPU features.
+ * If SIMD intrinsics are not available or no initialization is required,
+ * this function does nothing.
+ *
+ * @see convert_s16_to_float
  **/
 void convert_s16_to_float_init_simd(void);
 

libretro-common/include/clamping.h

@@ -27,14 +27,13 @@
 #include <retro_inline.h>
 
 /**
- * clamp_float:
- * @val           : initial value
- * @lower         : lower limit that value should be clamped against
- * @upper         : upper limit that value should be clamped against
+ * Clamps a floating-point value to the specified range.
  *
- * Clamps a floating point value.
+ * @param val The value to clamp.
+ * @param lower The minimum possible value.
+ * @param upper The maximum possible value.
  *
- * Returns: a clamped value of initial float value @val.
+ * @returns \c val clamped to between \c lower and \c upper (inclusive).
  */
 static INLINE float clamp_float(float val, float lower, float upper)
 {
@@ -46,12 +45,10 @@ static INLINE float clamp_float(float val, float lower, float upper)
 }
 
 /**
- * clamp_8bit:
- * @val           : initial value
+ * Clamps an integer to fit in 8 bits.
  *
- * Clamps an unsigned 8-bit value.
- *
- * Returns: a clamped value of initial unsigned 8-bit value @val.
+ * @param val The value to clamp.
+ * @return \c val clamped to between 0 and 255 (inclusive).
  */
 static INLINE uint8_t clamp_8bit(int val)
 {

libretro-common/include/compat/fnmatch.h

@@ -25,6 +25,11 @@
 
 #define	FNM_NOMATCH	1
 
+/**
+ * Portable implementation of \c fnmatch(3),
+ * except \c flags is not implemented.
+ * @see https://man7.org/linux/man-pages/man3/fnmatch.3.html
+ */
 int rl_fnmatch(const char *pattern, const char *string, int flags);
 
 #endif

libretro-common/include/compat/getopt.h

@@ -27,9 +27,17 @@
 #include "../../../config.h"
 #endif
 
-/* Custom implementation of the GNU getopt_long for portability.
- * Not designed to be fully compatible, but compatible with
- * the features RetroArch uses. */
+/**
+ * @file getopt.h
+ *
+ * Portable reimplementation of a subset of libc's \c getopt_long.
+ * Not designed to be fully compatible,
+ * but it's enough for RetroArch's purposes.
+ *
+ * If \c getopt_long is available (as determined by \c HAVE_GETOPT_LONG), it will be used instead.
+ *
+ * @see https://man7.org/linux/man-pages/man3/getopt.3.html
+ */
 
 #ifdef HAVE_GETOPT_LONG
 #include <getopt.h>

libretro-common/include/compat/ifaddrs.h

@@ -47,7 +47,20 @@ struct ifaddrs
 
 #include <sys/cdefs.h>
 
+/**
+ * Portable reimplementation of \c getifaddrs().
+ * The original function will be used if it's available.
+ *
+ * @see https://man7.org/linux/man-pages/man3/getifaddrs.3.html
+ */
 extern int getifaddrs(struct ifaddrs **ifap);
+
+/**
+ * Portable reimplementation of \c freeifaddrs().
+ * The original function will be used if it's available.
+ *
+ * @see https://man7.org/linux/man-pages/man3/getifaddrs.3.html
+ */
 extern void freeifaddrs(struct ifaddrs *ifa);
 
 #endif

libretro-common/include/compat/intrinsics.h

@@ -38,7 +38,13 @@
 
 RETRO_BEGIN_DECLS
 
-/* Count Leading Zero, unsigned 16bit input value */
+/**
+ * Counts the leading zero bits in a \c uint16_t.
+ * Uses compiler intrinsics if available, or a standard C implementation if not.
+ *
+ * @param val Value to count leading zeroes in.
+ * @return Number of leading zeroes in \c val.
+ */
 static INLINE unsigned compat_clz_u16(uint16_t val)
 {
 #if defined(__GNUC__)
@@ -56,7 +62,13 @@ static INLINE unsigned compat_clz_u16(uint16_t val)
 #endif
 }
 
-/* Count Trailing Zero */
+/**
+ * Counts the trailing zero bits in a \c uint16_t.
+ * Uses compiler intrinsics if available, or a standard C implementation if not.
+ *
+ * @param val Value to count trailing zeroes in.
+ * @return Number of trailing zeroes in \c val.
+ */
 static INLINE int compat_ctz(unsigned x)
 {
 #if defined(__GNUC__) && !defined(RARCH_CONSOLE)

libretro-common/include/compat/posix_string.h

@@ -25,31 +25,64 @@
 
 #include <retro_common_api.h>
 
+/**
+ * @file posix_string.h
+ *
+ * Portable reimplementations of various string functions
+ * that are normally provided by libc or POSIX.
+ */
+
 #ifdef _MSC_VER
 #include <compat/msvc.h>
 #endif
 
 RETRO_BEGIN_DECLS
 
-#ifdef _WIN32
+#if defined(_WIN32) || defined(DOXYGEN)
 #undef strtok_r
 #define strtok_r(str, delim, saveptr) retro_strtok_r__(str, delim, saveptr)
 
+/**
+ * Portable reimplementation of \c strtok_r().
+ * The original function will be used if it's available.
+ *
+ * @see https://man7.org/linux/man-pages/man3/strtok.3.html
+ */
 char *strtok_r(char *str, const char *delim, char **saveptr);
 #endif
 
-#ifdef _MSC_VER
+#if defined(_MSC_VER) || defined(DOXYGEN)
 #undef strcasecmp
 #undef strdup
+
 #define strcasecmp(a, b) retro_strcasecmp__(a, b)
 #define strdup(orig)     retro_strdup__(orig)
+/**
+ * Portable reimplementation of \c strcasecmp().
+ * The original function will be used if it's available.
+ *
+ * @see https://man7.org/linux/man-pages/man3/strcasecmp.3.html
+ */
 int strcasecmp(const char *a, const char *b);
+
+/**
+ * Portable reimplementation of \c strdup().
+ * The original function will be used if it's available.
+ *
+ * @see https://man7.org/linux/man-pages/man3/strdup.3.html
+ */
 char *strdup(const char *orig);
 
 /* isblank is available since MSVC 2013 */
 #if _MSC_VER < 1800
 #undef isblank
 #define isblank(c)       retro_isblank__(c)
+/**
+ * Portable reimplementation of \c isblank().
+ * The original function will be used if it's available.
+ *
+ * @see https://en.cppreference.com/w/c/string/byte/isblank
+ */
 int isblank(int c);
 #endif
 

libretro-common/include/compat/strcasestr.h

@@ -39,6 +39,14 @@ RETRO_BEGIN_DECLS
  * since we prefer to use the actual name. */
 #define strcasestr(haystack, needle) strcasestr_retro__(haystack, needle)
 
+/**
+ * Portable reimplementation of \c strcasestr(3).
+ * If the original function is available
+ * (as determined by the presence of \c HAVE_STRCASESTR),
+ * it will be used instead.
+ *
+ * @see https://man7.org/linux/man-pages/man3/strstr.3.html
+ */
 char *strcasestr(const char *haystack, const char *needle);
 
 RETRO_END_DECLS

libretro-common/include/compat/strl.h

@@ -23,6 +23,15 @@
 #ifndef __LIBRETRO_SDK_COMPAT_STRL_H
 #define __LIBRETRO_SDK_COMPAT_STRL_H
 
+/**
+ * @file strl.h
+ *
+ * Portable implementation of \c strlcpy(3) and \c strlcat(3).
+ * If these functions are available on the target platform,
+ * then the originals should be imported instead.
+ *
+ * @see https://linux.die.net/man/3/strlcpy
+ */
 #include <string.h>
 #include <stddef.h>
 
@@ -47,11 +56,29 @@ RETRO_BEGIN_DECLS
 
 #define strlcat(dst, src, size) strlcat_retro__(dst, src, size)
 
+/**
+ * @brief Portable implementation of \c strlcpy(3).
+ * @see https://linux.die.net/man/3/strlcpy
+ */
 size_t strlcpy(char *dest, const char *source, size_t size);
+
+/**
+ * @brief Portable implementation of \c strlcat(3).
+ * @see https://linux.die.net/man/3/strlcpy
+ */
 size_t strlcat(char *dest, const char *source, size_t size);
 
 #endif
 
+/**
+ * A version of \c strndup(3) that guarantees the result will be null-terminated.
+ *
+ * @param s The string to duplicate.
+ * @param n The maximum number of characters to copy from \c s.
+ * The result will allocate one more byte than this value.
+ * @return Pointer to the cloned string.
+ * Must be freed with \c free().
+ */
 char *strldup(const char *s, size_t n);
 
 RETRO_END_DECLS