Skip to content

Commit

Permalink
Clarify property group documentation
Browse files Browse the repository at this point in the history 
Fixes libsdl-org#10241
  • Loading branch information
@slouken
slouken committed Jul 12, 2024
1 parent 5bf6bc4 commit da1bbd1
Showing 1 changed file with 29 additions and 29 deletions.
58 changes: 29 additions & 29 deletions include/SDL3/SDL_properties.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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*` pointer types.
Expand All @@ -41,7 +41,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.
*/


Expand Down Expand Up @@ -90,11 +90,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.
Expand All @@ -106,9 +106,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.
Expand All @@ -125,7 +125,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
Expand All @@ -149,7 +149,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.
*
Expand All @@ -167,7 +167,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 the
Expand All @@ -186,7 +186,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
Expand Down Expand Up @@ -217,7 +217,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.
Expand All @@ -240,7 +240,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.
Expand All @@ -260,7 +260,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.
Expand All @@ -277,7 +277,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.
Expand All @@ -294,7 +294,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.
Expand All @@ -311,7 +311,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.
Expand All @@ -326,7 +326,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.
Expand All @@ -342,7 +342,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
Expand Down Expand Up @@ -374,7 +374,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.
*
Expand All @@ -395,7 +395,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.
Expand All @@ -417,7 +417,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.
Expand All @@ -439,7 +439,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.
Expand All @@ -461,7 +461,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.
Expand All @@ -475,7 +475,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.
Expand All @@ -494,9 +494,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.
Expand All @@ -512,7 +512,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.
Expand Down

0 comments on commit da1bbd1

Please sign in to comment.