[Bf-blender-cvs] [9789835db86] master: Docs: improve ID property doc-strings
Campbell Barton
noreply at git.blender.org
Tue Jan 17 02:37:02 CET 2023
Commit: 9789835db8690098b392c160c2abd34f4d8e17e2
Author: Campbell Barton
Date: Tue Jan 17 11:51:07 2023 +1100
Branches: master
https://developer.blender.org/rB9789835db8690098b392c160c2abd34f4d8e17e2
Docs: improve ID property doc-strings
Add some clarifications and reference enum types from DNA.
===================================================================
M source/blender/blenkernel/BKE_idprop.h
M source/blender/blenkernel/intern/idprop.c
M source/blender/makesdna/DNA_ID.h
===================================================================
diff --git a/source/blender/blenkernel/BKE_idprop.h b/source/blender/blenkernel/BKE_idprop.h
index 84412fd139f..22470b7a629 100644
--- a/source/blender/blenkernel/BKE_idprop.h
+++ b/source/blender/blenkernel/BKE_idprop.h
@@ -28,12 +28,15 @@ typedef union IDPropertyTemplate {
double d;
struct {
const char *str;
+ /** String length (including the null byte): `strlen(str) + 1`. */
int len;
+ /** #eIDPropertySubType */
char subtype;
} string;
struct ID *id;
struct {
int len;
+ /** #eIDPropertyType */
char type;
} array;
struct {
diff --git a/source/blender/blenkernel/intern/idprop.c b/source/blender/blenkernel/intern/idprop.c
index b8f0db0699d..156ad97c923 100644
--- a/source/blender/blenkernel/intern/idprop.c
+++ b/source/blender/blenkernel/intern/idprop.c
@@ -39,19 +39,19 @@
static CLG_LogRef LOG = {"bke.idprop"};
-/* Local size table. */
+/** Local size table, aligned with #eIDPropertyType. */
static size_t idp_size_table[] = {
- 1, /*strings*/
- sizeof(int),
- sizeof(float),
- sizeof(float[3]), /* Vector type, deprecated. */
- sizeof(float[16]), /* Matrix type, deprecated. */
- 0, /* Arrays don't have a fixed size. */
- sizeof(ListBase), /* Group type. */
- sizeof(void *),
- sizeof(double),
- 0,
- sizeof(int8_t), /* Boolean type. */
+ 1, /* #IDP_STRING */
+ sizeof(int), /* #IDP_INT */
+ sizeof(float), /* #IDP_FLOAT */
+ sizeof(float[3]), /* DEPRECATED (was vector). */
+ sizeof(float[16]), /* DEPRECATED (was matrix). */
+ 0, /* #IDP_ARRAY (no fixed size). */
+ sizeof(ListBase), /* #IDP_GROUP */
+ sizeof(void *), /* #IDP_ID */
+ sizeof(double), /* #IDP_DOUBLE */
+ 0, /* #IDP_IDPARRAY (no fixed size). */
+ sizeof(int8_t), /* #IDP_BOOLEAN */
};
/* -------------------------------------------------------------------- */
diff --git a/source/blender/makesdna/DNA_ID.h b/source/blender/makesdna/DNA_ID.h
index 4e56fbe3dd0..43317bc0466 100644
--- a/source/blender/makesdna/DNA_ID.h
+++ b/source/blender/makesdna/DNA_ID.h
@@ -45,9 +45,9 @@ typedef struct DrawDataList {
} DrawDataList;
typedef struct IDPropertyUIData {
- /** Tooltip / property description pointer. Owned by the IDProperty. */
+ /** Tool-tip / property description pointer. Owned by the #IDProperty. */
char *description;
- /** RNA subtype, used for every type except string properties (PropertySubType). */
+ /** RNA `subtype`, used for every type except string properties (#PropertySubType). */
int rna_subtype;
char _pad[4];
@@ -68,7 +68,7 @@ typedef struct IDPropertyUIDataInt {
int default_value;
} IDPropertyUIDataInt;
-/* IDP_UI_DATA_TYPE_BOOLEAN Use "int8_t" because DNA does not support "bool". */
+/** For #IDP_UI_DATA_TYPE_BOOLEAN Use `int8_t` because DNA does not support `bool`. */
typedef struct IDPropertyUIDataBool {
IDPropertyUIData base;
int8_t *default_array; /* Only for array properties. */
@@ -78,7 +78,7 @@ typedef struct IDPropertyUIDataBool {
int8_t default_value;
} IDPropertyUIDataBool;
-/* IDP_UI_DATA_TYPE_FLOAT */
+/** For #IDP_UI_DATA_TYPE_FLOAT */
typedef struct IDPropertyUIDataFloat {
IDPropertyUIData base;
double *default_array; /* Only for array properties. */
@@ -95,13 +95,13 @@ typedef struct IDPropertyUIDataFloat {
double default_value;
} IDPropertyUIDataFloat;
-/* IDP_UI_DATA_TYPE_STRING */
+/** For #IDP_UI_DATA_TYPE_STRING */
typedef struct IDPropertyUIDataString {
IDPropertyUIData base;
char *default_value;
} IDPropertyUIDataString;
-/* IDP_UI_DATA_TYPE_ID */
+/** For #IDP_UI_DATA_TYPE_ID. */
typedef struct IDPropertyUIDataID {
IDPropertyUIData base;
} IDPropertyUIDataID;
@@ -109,15 +109,22 @@ typedef struct IDPropertyUIDataID {
typedef struct IDPropertyData {
void *pointer;
ListBase group;
- /** NOTE: we actually fit a double into these two 32bit integers. */
+ /** NOTE: a `double` is written into two 32bit integers. */
int val, val2;
} IDPropertyData;
typedef struct IDProperty {
struct IDProperty *next, *prev;
- char type, subtype;
+ /** #eIDPropertyType */
+ char type;
+ /**
+ * #eIDPropertySubType when `type` is #IDP_STRING.
+ * #eIDPropertyType for all other types.
+ */
+ char subtype;
+ /** #IDP_FLAG_GHOST and others. */
short flag;
- /** MAX_IDPROP_NAME. */
+ /** Size matches #MAX_IDPROP_NAME. */
char name[64];
/* saved is used to indicate if this struct has been saved yet.
@@ -126,13 +133,16 @@ typedef struct IDProperty {
/** NOTE: alignment for 64 bits. */
IDPropertyData data;
- /* Array length, also (this is important!) string length + 1.
- * the idea is to be able to reuse array realloc functions on strings. */
+ /**
+ * Array length, and importantly string length + 1.
+ * the idea is to be able to reuse array reallocation functions on strings.
+ */
int len;
-
- /* Strings and arrays are both buffered, though the buffer isn't saved. */
- /* totallen is total length of allocated array/string, including a buffer.
- * Note that the buffering is mild; the code comes from python's list implementation. */
+ /**
+ * Strings and arrays are both buffered, though the buffer isn't saved.
+ * `totallen` is total length of allocated array/string, including a buffer.
+ * \note the buffering is mild; see #IDP_ResizeIDPArray for details.
+ */
int totallen;
IDPropertyUIData *ui_data;
@@ -141,7 +151,7 @@ typedef struct IDProperty {
#define MAX_IDPROP_NAME 64
#define DEFAULT_ALLOC_FOR_NULL_STRINGS 64
-/*->type*/
+/** #IDProperty.type */
typedef enum eIDPropertyType {
IDP_STRING = 0,
IDP_INT = 1,
@@ -173,27 +183,29 @@ enum {
IDP_TYPE_FILTER_BOOLEAN = 1 << 10,
};
-/*->subtype */
-
-/* IDP_STRING */
-enum {
+/** #IDProperty.subtype for #IDP_STRING properties. */
+typedef enum eIDPropertySubType {
IDP_STRING_SUB_UTF8 = 0, /* default */
IDP_STRING_SUB_BYTE = 1, /* arbitrary byte array, _not_ null terminated */
-};
+} eIDPropertySubType;
-/*->flag*/
+/** #IDProperty.flag. */
enum {
- /** This IDProp may be statically overridden.
- * Should only be used/be relevant for custom properties. */
+ /**
+ * This #IDProperty may be statically overridden.
+ * Should only be used/be relevant for custom properties.
+ */
IDP_FLAG_OVERRIDABLE_LIBRARY = 1 << 0,
-
- /** This collection item IDProp has been inserted in a local override.
+ /**
+ * This collection item #IDProperty has been inserted in a local override.
* This is used by internal code to distinguish between library-originated items and
- * local-inserted ones, as many operations are not allowed on the former. */
+ * local-inserted ones, as many operations are not allowed on the former.
+ */
IDP_FLAG_OVERRIDELIBRARY_LOCAL = 1 << 1,
-
- /** This means the property is set but RNA will return false when checking
- * 'RNA_property_is_set', currently this is a runtime flag */
+ /**
+ * This means the property is set but RNA will return false when checking
+ * #RNA_property_is_set, currently this is a runtime flag.
+ */
IDP_FLAG_GHOST = 1 << 7,
};
@@ -208,7 +220,7 @@ typedef struct IDOverrideLibraryPropertyOperation {
short operation;
short flag;
- /** Runtime, tags are common to both IDOverrideProperty and IDOverridePropertyOperation. */
+ /** Runtime, tags are common to both #IDOverrideProperty and #IDOverridePropertyOperation. */
short tag;
char _pad0[2];
More information about the Bf-blender-cvs
mailing list