From 87ea39aceab9cb59266350bf26a4e3e48f7beff6 Mon Sep 17 00:00:00 2001
From: Jesse Talavera-Greenberg <jesse@jesse.tg>
Date: Mon, 9 Oct 2023 20:35:37 -0400
Subject: [PATCH] Update the features_cpu.h docs

---
 libretro-common/features/features_cpu.c       | 28 ----------
 .../include/features/features_cpu.h           | 56 +++++++++++++------
 2 files changed, 38 insertions(+), 46 deletions(-)

diff --git a/libretro-common/features/features_cpu.c b/libretro-common/features/features_cpu.c
index 80fe2c1bee3..98b85024d9d 100644
--- a/libretro-common/features/features_cpu.c
+++ b/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;
diff --git a/libretro-common/include/features/features_cpu.h b/libretro-common/include/features/features_cpu.h
index 130d748125a..59796dae13c 100644
--- a/libretro-common/include/features/features_cpu.h
+++ b/libretro-common/include/features/features_cpu.h
@@ -32,42 +32,62 @@
 RETRO_BEGIN_DECLS
 
 /**
- * cpu_features_get_perf_counter:
+ * Gets the time in ticks since some unspecified epoch.
+ * The notion of a "tick" varies per platform.
  *
- * Gets performance counter.
+ * The epoch may change between devices or across reboots.
  *
- * @return Performance counter.
- **/
+ * Suitable for use as a default implementation of \c retro_perf_callback::get_perf_counter,
+ * (or as a fallback by the core),
+ * although a frontend may provide its own implementation.
+ *
+ * @return The current time, in ticks.
+ * @see retro_perf_callback::get_perf_counter
+ */
 retro_perf_tick_t cpu_features_get_perf_counter(void);
 
 /**
- * cpu_features_get_time_usec:
+ * Gets the time in microseconds since some unspecified epoch.
+ *
+ * The epoch may change between devices or across reboots.
  *
- * Gets time in microseconds, from an undefined epoch.
- * The epoch may change between computers or across reboots.
+ * Suitable for use as a default implementation of \c retro_perf_callback::get_time_usec,
+ * (or as a fallback by the core),
+ * although a frontend may provide its own implementation.
  *
- * @return Time in microseconds
- **/
+ * @return The current time, in microseconds.
+ * @see retro_perf_callback::get_time_usec
+ */
 retro_time_t cpu_features_get_time_usec(void);
 
 /**
- * cpu_features_get:
+ * Returns the available features (mostly SIMD extensions)
+ * supported by this CPU.
  *
- * Gets CPU features.
+ * Suitable for use as a default implementation of \c retro_perf_callback::get_time_usec,
+ * (or as a fallback by the core),
+ * although a frontend may provide its own implementation.
  *
  * @return Bitmask of all CPU features available.
- **/
+ * @see RETRO_SIMD
+ * @see retro_perf_callback::get_cpu_features
+ */
 uint64_t cpu_features_get(void);
 
 /**
- * cpu_features_get_core_amount:
- *
- * Gets the amount of available CPU cores.
- *
- * @return Amount of CPU cores available.
- **/
+ * @return The number of CPU cores available,
+ * or 1 if the number of cores could not be determined.
+ */
 unsigned cpu_features_get_core_amount(void);
 
+/**
+ * Returns the name of the CPU model.
+ *
+ * @param[out] name Pointer to a buffer to store the name.
+ * Will be \c NULL-terminated.
+ * If \c NULL, this value will not be modified.
+ * @param len The amount of space available in \c name.
+ */
 void cpu_features_get_model_name(char *name, int len);
 
 RETRO_END_DECLS