Merge pull request #68701 from Bromeon/bugfix/extension-header-cleanup

Extension header: fix typos, documentation and member order

1 files changed, 44 insertions, 26 deletions

diff --git a/core/extension/gdnative_interface.h b/core/extension/gdnative_interface.h
index a361e40096..50410c4857 100644
--- a/core/extension/gdnative_interface.h
+++ b/core/extension/gdnative_interface.h
@@ -109,6 +109,7 @@ typedef enum {
 	GDNATIVE_VARIANT_OP_LESS_EQUAL,
 	GDNATIVE_VARIANT_OP_GREATER,
 	GDNATIVE_VARIANT_OP_GREATER_EQUAL,
+
 	/* mathematic */
 	GDNATIVE_VARIANT_OP_ADD,
 	GDNATIVE_VARIANT_OP_SUBTRACT,
@@ -118,6 +119,7 @@ typedef enum {
 	GDNATIVE_VARIANT_OP_POSITIVE,
 	GDNATIVE_VARIANT_OP_MODULE,
 	GDNATIVE_VARIANT_OP_POWER,
+
 	/* bitwise */
 	GDNATIVE_VARIANT_OP_SHIFT_LEFT,
 	GDNATIVE_VARIANT_OP_SHIFT_RIGHT,
@@ -125,11 +127,13 @@ typedef enum {
 	GDNATIVE_VARIANT_OP_BIT_OR,
 	GDNATIVE_VARIANT_OP_BIT_XOR,
 	GDNATIVE_VARIANT_OP_BIT_NEGATE,
+
 	/* logic */
 	GDNATIVE_VARIANT_OP_AND,
 	GDNATIVE_VARIANT_OP_OR,
 	GDNATIVE_VARIANT_OP_XOR,
 	GDNATIVE_VARIANT_OP_NOT,
+
 	/* containment */
 	GDNATIVE_VARIANT_OP_IN,
 	GDNATIVE_VARIANT_OP_MAX
@@ -152,11 +156,11 @@ typedef uint64_t GDObjectInstanceID;
 typedef enum {
 	GDNATIVE_CALL_OK,
 	GDNATIVE_CALL_ERROR_INVALID_METHOD,
-	GDNATIVE_CALL_ERROR_INVALID_ARGUMENT, /* expected is variant type */
-	GDNATIVE_CALL_ERROR_TOO_MANY_ARGUMENTS, /* expected is number of arguments */
-	GDNATIVE_CALL_ERROR_TOO_FEW_ARGUMENTS, /*  expected is number of arguments */
+	GDNATIVE_CALL_ERROR_INVALID_ARGUMENT, // Expected a different variant type.
+	GDNATIVE_CALL_ERROR_TOO_MANY_ARGUMENTS, // Expected lower number of arguments.
+	GDNATIVE_CALL_ERROR_TOO_FEW_ARGUMENTS, // Expected higher number of arguments.
 	GDNATIVE_CALL_ERROR_INSTANCE_IS_NULL,
-	GDNATIVE_CALL_ERROR_METHOD_NOT_CONST, /* used for const call */
+	GDNATIVE_CALL_ERROR_METHOD_NOT_CONST, // Used for const call.
 } GDNativeCallErrorType;
 
 typedef struct {
@@ -204,20 +208,24 @@ typedef struct {
 	GDNativeVariantType type;
 	GDNativeStringNamePtr name;
 	GDNativeStringNamePtr class_name;
-	uint32_t hint; // Bitfield of `PropertyHint` (defined in `extension_api.json`)
+	uint32_t hint; // Bitfield of `PropertyHint` (defined in `extension_api.json`).
 	GDNativeStringPtr hint_string;
-	uint32_t usage; // Bitfield of `PropertyUsageFlags` (defined in `extension_api.json`)
+	uint32_t usage; // Bitfield of `PropertyUsageFlags` (defined in `extension_api.json`).
 } GDNativePropertyInfo;
 
 typedef struct {
 	GDNativeStringNamePtr name;
 	GDNativePropertyInfo return_value;
-	uint32_t flags; // Bitfield of `GDNativeExtensionClassMethodFlags`
+	uint32_t flags; // Bitfield of `GDNativeExtensionClassMethodFlags`.
 	int32_t id;
-	GDNativePropertyInfo *arguments; // array of `argument_count` size
+
+	/* Arguments: `default_arguments` is an array of size `argument_count`. */
 	uint32_t argument_count;
-	GDNativeVariantPtr *default_arguments; // array of `default_argument_count` size
+	GDNativePropertyInfo *arguments;
+
+	/* Default arguments: `default_arguments` is an array of size `default_argument_count`. */
 	uint32_t default_argument_count;
+	GDNativeVariantPtr *default_arguments;
 } GDNativeMethodInfo;
 
 typedef const GDNativePropertyInfo *(*GDNativeExtensionClassGetPropertyList)(GDExtensionClassInstancePtr p_instance, uint32_t *r_count);
@@ -246,11 +254,11 @@ typedef struct {
 	GDNativeExtensionClassToString to_string_func;
 	GDNativeExtensionClassReference reference_func;
 	GDNativeExtensionClassUnreference unreference_func;
-	GDNativeExtensionClassCreateInstance create_instance_func; /* this one is mandatory */
-	GDNativeExtensionClassFreeInstance free_instance_func; /* this one is mandatory */
-	GDNativeExtensionClassGetVirtual get_virtual_func;
+	GDNativeExtensionClassCreateInstance create_instance_func; // (Default) constructor; mandatory. If the class is not instantiable, consider making it virtual or abstract.
+	GDNativeExtensionClassFreeInstance free_instance_func; // Destructor; mandatory.
+	GDNativeExtensionClassGetVirtual get_virtual_func; // Queries a virtual function by name and returns a callback to invoke the requested virtual function.
 	GDNativeExtensionClassGetRID get_rid_func;
-	void *class_userdata;
+	void *class_userdata; // Per-class user data, later accessible in instance bindings.
 } GDNativeExtensionClassCreationInfo;
 
 typedef void *GDNativeExtensionClassLibraryPtr;
@@ -289,21 +297,28 @@ typedef struct {
 	void *method_userdata;
 	GDNativeExtensionClassMethodCall call_func;
 	GDNativeExtensionClassMethodPtrCall ptrcall_func;
-	uint32_t method_flags; // Bitfield of `GDNativeExtensionClassMethodFlags`
-	uint32_t argument_count;
+	uint32_t method_flags; // Bitfield of `GDNativeExtensionClassMethodFlags`.
+
+	/* If `has_return_value` is false, `return_value_info` and `return_value_metadata` are ignored. */
 	GDNativeBool has_return_value;
-	GDNativePropertyInfo *return_value_info; // Ignored if `has_return_value` is false
-	GDNativeExtensionClassMethodArgumentMetadata return_value_metadata; // Ignored if `has_return_value` is false
-	/* name and hint information for the argument can be omitted in release builds. Class name should always be present if it applies. */
-	GDNativePropertyInfo *aguments_info; // array of `argument_count` size
-	GDNativeExtensionClassMethodArgumentMetadata *aguments_metadata; // array of `argument_count` size
+	GDNativePropertyInfo *return_value_info;
+	GDNativeExtensionClassMethodArgumentMetadata return_value_metadata;
+
+	/* Arguments: `arguments_info` and `arguments_metadata` are array of size `argument_count`.
+	 * Name and hint information for the argument can be omitted in release builds. Class name should always be present if it applies.
+	 */
+	uint32_t argument_count;
+	GDNativePropertyInfo *arguments_info;
+	GDNativeExtensionClassMethodArgumentMetadata *arguments_metadata;
+
+	/* Default arguments: `default_arguments` is an array of size `default_argument_count`. */
 	uint32_t default_argument_count;
-	GDNativeVariantPtr *default_arguments; // array of `default_argument_count` size
+	GDNativeVariantPtr *default_arguments;
 } GDNativeExtensionClassMethodInfo;
 
 /* SCRIPT INSTANCE EXTENSION */
 
-typedef void *GDNativeExtensionScriptInstanceDataPtr; // Pointer to custom ScriptInstance native implementation
+typedef void *GDNativeExtensionScriptInstanceDataPtr; // Pointer to custom ScriptInstance native implementation.
 
 typedef GDNativeBool (*GDNativeExtensionScriptInstanceSet)(GDNativeExtensionScriptInstanceDataPtr p_instance, const GDNativeStringNamePtr p_name, const GDNativeVariantPtr p_value);
 typedef GDNativeBool (*GDNativeExtensionScriptInstanceGet)(GDNativeExtensionScriptInstanceDataPtr p_instance, const GDNativeStringNamePtr p_name, GDNativeVariantPtr r_ret);
@@ -389,6 +404,7 @@ typedef struct {
 	const char *version_string;
 
 	/* GODOT CORE */
+
 	void *(*mem_alloc)(size_t p_bytes);
 	void *(*mem_realloc)(void *p_ptr, size_t p_bytes);
 	void (*mem_free)(void *p_ptr);
@@ -455,7 +471,6 @@ typedef struct {
 	GDNativePtrUtilityFunction (*variant_get_ptr_utility_function)(const GDNativeStringNamePtr p_function, GDNativeInt p_hash);
 
 	/*  extra utilities */
-
 	void (*string_new_with_latin1_chars)(GDNativeStringPtr r_dest, const char *p_contents);
 	void (*string_new_with_utf8_chars)(GDNativeStringPtr r_dest, const char *p_contents);
 	void (*string_new_with_utf16_chars)(GDNativeStringPtr r_dest, const char16_t *p_contents);
@@ -466,6 +481,7 @@ typedef struct {
 	void (*string_new_with_utf16_chars_and_len)(GDNativeStringPtr r_dest, const char16_t *p_contents, const GDNativeInt p_size);
 	void (*string_new_with_utf32_chars_and_len)(GDNativeStringPtr r_dest, const char32_t *p_contents, const GDNativeInt p_size);
 	void (*string_new_with_wide_chars_and_len)(GDNativeStringPtr r_dest, const wchar_t *p_contents, const GDNativeInt p_size);
+
 	/* Information about the following functions:
 	 * - The return value is the resulting encoded string length.
 	 * - The length returned is in characters, not in bytes. It also does not include a trailing zero.
@@ -537,13 +553,14 @@ typedef struct {
 	GDNativeScriptInstancePtr (*script_instance_create)(const GDNativeExtensionScriptInstanceInfo *p_info, GDNativeExtensionScriptInstanceDataPtr p_instance_data);
 
 	/* CLASSDB */
+
 	GDNativeObjectPtr (*classdb_construct_object)(const GDNativeStringNamePtr p_classname); /* The passed class must be a built-in godot class, or an already-registered extension class. In both case, object_set_instance should be called to fully initialize the object. */
 	GDNativeMethodBindPtr (*classdb_get_method_bind)(const GDNativeStringNamePtr p_classname, const GDNativeStringNamePtr p_methodname, GDNativeInt p_hash);
 	void *(*classdb_get_class_tag)(const GDNativeStringNamePtr p_classname);
 
 	/* CLASSDB EXTENSION */
 
-	// Provided parameters for `classdb_register_extension_*` can be safely freed once the function returns
+	/* Provided parameters for `classdb_register_extension_*` can be safely freed once the function returns. */
 	void (*classdb_register_extension_class)(const GDNativeExtensionClassLibraryPtr p_library, const GDNativeStringNamePtr p_class_name, const GDNativeStringNamePtr p_parent_class_name, const GDNativeExtensionClassCreationInfo *p_extension_funcs);
 	void (*classdb_register_extension_class_method)(const GDNativeExtensionClassLibraryPtr p_library, const GDNativeStringNamePtr p_class_name, const GDNativeExtensionClassMethodInfo *p_method_info);
 	void (*classdb_register_extension_class_integer_constant)(const GDNativeExtensionClassLibraryPtr p_library, const GDNativeStringNamePtr p_class_name, const GDNativeStringNamePtr p_enum_name, const GDNativeStringNamePtr p_constant_name, GDNativeInt p_constant_value, GDNativeBool p_is_bitfield);
@@ -579,9 +596,10 @@ typedef struct {
 } GDNativeInitialization;
 
 /* Define a C function prototype that implements the function below and expose it to dlopen() (or similar).
- * It will be called on initialization. The name must be an unique one specified in the .gdextension config file.
+ * This is the entry point of the GDExtension library and will be called on initialization.
+ * It can be used to set up different init levels, which are called during various stages of initialization/shutdown.
+ * The function name must be a unique one specified in the .gdextension config file.
  */
-
 typedef GDNativeBool (*GDNativeInitializationFunction)(const GDNativeInterface *p_interface, const GDNativeExtensionClassLibraryPtr p_library, GDNativeInitialization *r_initialization);
 
 #ifdef __cplusplus