From 0e56f6a3ca808aca7f962152575d9308d5afccb7 Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
Date: Fri, 12 Jul 2024 10:45:32 -0700
Subject: [PATCH] Clarify property group documentation

Fixes https://github.com/libsdl-org/SDL/issues/10241
---
 include/SDL3/SDL_properties.h | 58 +++++++++++++++++------------------
 1 file changed, 29 insertions(+), 29 deletions(-)

diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h
index 599dfbfcc..f0d6a12e4 100644
--- a/include/SDL3/SDL_properties.h
+++ b/include/SDL3/SDL_properties.h
@@ -25,11 +25,11 @@
  * A property is a variable that can be created and retrieved by name at
  * runtime.
  *
- * All properties are part of a property set (SDL_PropertiesID). A property
- * set can be created with the SDL_CreateProperties function and destroyed
+ * All properties are part of a property group (SDL_PropertiesID). A property
+ * group can be created with the SDL_CreateProperties function and destroyed
  * with the SDL_DestroyProperties function.
  *
- * Properties can be added to and retrieved from a property set through the
+ * Properties can be added to and retrieved from a property group through the
  * following functions:
  *
  * - SDL_SetPointerProperty and SDL_GetPointerProperty operate on `void*`
@@ -42,7 +42,7 @@
  * - SDL_SetBooleanProperty and SDL_GetBooleanProperty operate on boolean
  *   types.
  *
- * Properties can be removed from a set by using SDL_ClearProperty.
+ * Properties can be removed from a group by using SDL_ClearProperty.
  */
 
 
@@ -91,11 +91,11 @@ typedef enum SDL_PropertyType
 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
 
 /**
- * Create a set of properties.
+ * Create a group of properties.
  *
  * All properties are automatically destroyed when SDL_Quit() is called.
  *
- * \returns an ID for a new set of properties, or 0 on failure; call
+ * \returns an ID for a new group of properties, or 0 on failure; call
  *          SDL_GetError() for more information.
  *
  * \threadsafety It is safe to call this function from any thread.
@@ -107,9 +107,9 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
 extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
 
 /**
- * Copy a set of properties.
+ * Copy a group of properties.
  *
- * Copy all the properties from one set of properties to another, with the
+ * Copy all the properties from one group of properties to another, with the
  * exception of properties requiring cleanup (set using
  * SDL_SetPointerPropertyWithCleanup()), which will not be copied. Any
  * property that already exists on `dst` will be overwritten.
@@ -126,7 +126,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
 extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);
 
 /**
- * Lock a set of properties.
+ * Lock a group of properties.
  *
  * Obtain a multi-threaded lock for these properties. Other threads will wait
  * while trying to lock these properties until they are unlocked. Properties
@@ -150,7 +150,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_Pro
 extern SDL_DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
 
 /**
- * Unlock a set of properties.
+ * Unlock a group of properties.
  *
  * \param props the properties to unlock.
  *
@@ -168,7 +168,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
  * This should release any resources associated with `value` that are no
  * longer needed.
  *
- * This callback is set per-property. Different properties in the same set can
+ * This callback is set per-property. Different properties in the same group can
  * have different cleanup callbacks.
  *
  * This callback will be called _during_ SDL_SetPointerPropertyWithCleanup if
@@ -187,7 +187,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
 typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value);
 
 /**
- * Set a property on a set of properties with a cleanup function that is
+ * Set a property on a group of properties with a cleanup function that is
  * called when the property is deleted.
  *
  * The cleanup function is also called if setting the property fails for any
@@ -218,7 +218,7 @@ typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value)
 extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata);
 
 /**
- * Set a property on a set of properties.
+ * Set a property on a group of properties.
  *
  * \param props the properties to modify.
  * \param name the name of the property to modify.
@@ -241,7 +241,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_Properties
 extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value);
 
 /**
- * Set a string property on a set of properties.
+ * Set a string property on a group of properties.
  *
  * This function makes a copy of the string; the caller does not have to
  * preserve the data after this call completes.
@@ -261,7 +261,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, c
 extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
 
 /**
- * Set an integer property on a set of properties.
+ * Set an integer property on a group of properties.
  *
  * \param props the properties to modify.
  * \param name the name of the property to modify.
@@ -278,7 +278,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, co
 extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
 
 /**
- * Set a floating point property on a set of properties.
+ * Set a floating point property on a group of properties.
  *
  * \param props the properties to modify.
  * \param name the name of the property to modify.
@@ -295,7 +295,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, co
 extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
 
 /**
- * Set a boolean property on a set of properties.
+ * Set a boolean property on a group of properties.
  *
  * \param props the properties to modify.
  * \param name the name of the property to modify.
@@ -312,7 +312,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, con
 extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
 
 /**
- * Return whether a property exists in a set of properties.
+ * Return whether a property exists in a group of properties.
  *
  * \param props the properties to query.
  * \param name the name of the property to query.
@@ -327,7 +327,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, c
 extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);
 
 /**
- * Get the type of a property on a set of properties.
+ * Get the type of a property on a group of properties.
  *
  * \param props the properties to query.
  * \param name the name of the property to query.
@@ -343,7 +343,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, con
 extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
 
 /**
- * Get a property on a set of properties.
+ * Get a property on a group of properties.
  *
  * By convention, the names of properties that SDL exposes on objects will
  * start with "SDL.", and properties that SDL uses internally will start with
@@ -376,7 +376,7 @@ extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesI
 extern SDL_DECLSPEC void *SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props, const char *name, void *default_value);
 
 /**
- * Get a string property on a set of properties.
+ * Get a string property on a group of properties.
  *
  * The returned string follows the SDL_GetStringRule.
  *
@@ -397,7 +397,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props,
 extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
 
 /**
- * Get a number property on a set of properties.
+ * Get a number property on a group of properties.
  *
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a number property.
@@ -419,7 +419,7 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID p
 extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
 
 /**
- * Get a floating point property on a set of properties.
+ * Get a floating point property on a group of properties.
  *
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a floating point property.
@@ -441,7 +441,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props,
 extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
 
 /**
- * Get a boolean property on a set of properties.
+ * Get a boolean property on a group of properties.
  *
  * You can use SDL_GetPropertyType() to query whether the property exists and
  * is a boolean property.
@@ -463,7 +463,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
 extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
 
 /**
- * Clear a property on a set of properties.
+ * Clear a property on a group of properties.
  *
  * \param props the properties to modify.
  * \param name the name of the property to clear.
@@ -477,7 +477,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID pro
 extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
 
 /**
- * A callback used to enumerate all properties set in an SDL_PropertiesID.
+ * A callback used to enumerate all the properties in a group of properties.
  *
  * This callback is called from SDL_EnumerateProperties(), and is called once
  * per property in the set.
@@ -496,9 +496,9 @@ extern SDL_DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const
 typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
 
 /**
- * Enumerate the properties contained in a property set.
+ * Enumerate the properties contained in a group of properties.
  *
- * The callback function is called for each property on the set of properties.
+ * The callback function is called for each property in the group of properties.
  * The properties are locked during enumeration.
  *
  * \param props the properties to query.
@@ -514,7 +514,7 @@ typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_Prop
 extern SDL_DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
 
 /**
- * Destroy a set of properties.
+ * Destroy a group of properties.
  *
  * All properties are deleted and their cleanup functions will be called, if
  * any.