diff options
author | Campbell Barton <ideasman42@gmail.com> | 2019-06-26 05:40:22 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2019-06-26 05:44:22 +0300 |
commit | 545610d3aae0c64ad98abb4fcb19d8958018bd76 (patch) | |
tree | 4f9d256e3e58b08faa08fb41ba28840c0fae7490 /source/blender/makesrna | |
parent | abaf6b106d3a34512f1061dc23277f3924da7fc6 (diff) |
Cleanup: un-wrap lines in headers, use doxy comments
Diffstat (limited to 'source/blender/makesrna')
-rw-r--r-- | source/blender/makesrna/RNA_access.h | 50 | ||||
-rw-r--r-- | source/blender/makesrna/RNA_types.h | 264 |
2 files changed, 190 insertions, 124 deletions
diff --git a/source/blender/makesrna/RNA_access.h b/source/blender/makesrna/RNA_access.h index 5045137fd95..30e24917b83 100644 --- a/source/blender/makesrna/RNA_access.h +++ b/source/blender/makesrna/RNA_access.h @@ -1205,7 +1205,7 @@ bool RNA_enum_is_equal(struct bContext *C, const char *name, const char *enumname); -/* lower level functions that don't use a PointerRNA */ +/* Lower level functions that don't use a PointerRNA. */ bool RNA_enum_value_from_id(const EnumPropertyItem *item, const char *identifier, int *r_value); bool RNA_enum_id_from_value(const EnumPropertyItem *item, int value, const char **r_identifier); bool RNA_enum_icon_from_value(const EnumPropertyItem *item, int value, int *r_icon); @@ -1425,14 +1425,19 @@ void _RNA_warning(const char *format, ...) ATTR_PRINTF_FORMAT(1, 2); /* Equals test. */ -/* Note: In practice, EQ_STRICT and EQ_COMPARE have same behavior currently, - * and will yield same result. */ +/** + * \note In practice, #EQ_STRICT and #EQ_COMPARE have same behavior currently, + * and will yield same result. + */ typedef enum eRNACompareMode { /* Only care about equality, not full comparison. */ - RNA_EQ_STRICT, /* set/unset ignored */ - RNA_EQ_UNSET_MATCH_ANY, /* unset property matches anything */ - RNA_EQ_UNSET_MATCH_NONE, /* unset property never matches set property */ - /* Full comparison. */ + /** Set/unset ignored. */ + RNA_EQ_STRICT, + /** Unset property matches anything. */ + RNA_EQ_UNSET_MATCH_ANY, + /** Unset property never matches set property. */ + RNA_EQ_UNSET_MATCH_NONE, + /** Full comparison. */ RNA_EQ_COMPARE, } eRNACompareMode; @@ -1448,33 +1453,38 @@ bool RNA_struct_equals(struct Main *bmain, /* Override. */ -/* flags for RNA_struct_override_matches. */ +/** Flags for #RNA_struct_override_matches. */ typedef enum eRNAOverrideMatch { - /* Do not compare properties that are not overridable. */ + /** Do not compare properties that are not overridable. */ RNA_OVERRIDE_COMPARE_IGNORE_NON_OVERRIDABLE = 1 << 0, - /* Do not compare properties that are already overridden. */ + /** Do not compare properties that are already overridden. */ RNA_OVERRIDE_COMPARE_IGNORE_OVERRIDDEN = 1 << 1, - /* Create new property override if needed and possible. */ + /** Create new property override if needed and possible. */ RNA_OVERRIDE_COMPARE_CREATE = 1 << 16, - /* Restore property's value(s) to reference ones if needed and possible. */ + /** Restore property's value(s) to reference ones if needed and possible. */ RNA_OVERRIDE_COMPARE_RESTORE = 1 << 17, } eRNAOverrideMatch; typedef enum eRNAOverrideMatchResult { - /* Some new property overrides were created to take into account - * differences between local and reference. */ + /** + * Some new property overrides were created to take into account + * differences between local and reference. + */ RNA_OVERRIDE_MATCH_RESULT_CREATED = 1 << 0, - /* Some properties were reset to reference values. */ + /** Some properties were reset to reference values. */ RNA_OVERRIDE_MATCH_RESULT_RESTORED = 1 << 1, } eRNAOverrideMatchResult; typedef enum eRNAOverrideStatus { - RNA_OVERRIDE_STATUS_OVERRIDABLE = 1 << 0, /* The property is overridable. */ - RNA_OVERRIDE_STATUS_OVERRIDDEN = 1 << 1, /* The property is overridden. */ - RNA_OVERRIDE_STATUS_MANDATORY = - 1 << 2, /* Overriding this property is mandatory when creating an override. */ - RNA_OVERRIDE_STATUS_LOCKED = 1 << 3, /* The override status of this property is locked. */ + /** The property is overridable. */ + RNA_OVERRIDE_STATUS_OVERRIDABLE = 1 << 0, + /** The property is overridden. */ + RNA_OVERRIDE_STATUS_OVERRIDDEN = 1 << 1, + /** Overriding this property is mandatory when creating an override. */ + RNA_OVERRIDE_STATUS_MANDATORY = 1 << 2, + /** The override status of this property is locked. */ + RNA_OVERRIDE_STATUS_LOCKED = 1 << 3, } eRNAOverrideStatus; bool RNA_struct_override_matches(struct Main *bmain, diff --git a/source/blender/makesrna/RNA_types.h b/source/blender/makesrna/RNA_types.h index aac42fb596b..c6f1fd337ed 100644 --- a/source/blender/makesrna/RNA_types.h +++ b/source/blender/makesrna/RNA_types.h @@ -63,7 +63,7 @@ typedef struct PropertyPointerRNA { typedef struct PathResolvedRNA { struct PointerRNA ptr; struct PropertyRNA *prop; - /* -1 for non-array access */ + /** -1 for non-array access. */ int prop_index; } PathResolvedRNA; @@ -104,9 +104,9 @@ typedef enum PropertyUnit { #define RNA_STACK_ARRAY 32 -/* also update enums in bpy_props.c when adding items here - * watch it: these values are written to files as part of - * node socket button subtypes! +/** + * \note Also update enums in bpy_props.c when adding items here. + * Watch it: these values are written to files as part of node socket button subtypes! */ typedef enum PropertySubType { PROP_NONE = 0, @@ -115,10 +115,11 @@ typedef enum PropertySubType { PROP_FILEPATH = 1, PROP_DIRPATH = 2, PROP_FILENAME = 3, - PROP_BYTESTRING = - 4, /* a string which should be represented as bytes in python, NULL terminated though. */ + /** A string which should be represented as bytes in python, NULL terminated though. */ + PROP_BYTESTRING = 4, /* 5 was used by "PROP_TRANSLATE" sub-type, which is now a flag. */ - PROP_PASSWORD = 6, /* a string which should not be displayed in UI */ + /** A string which should not be displayed in UI. */ + PROP_PASSWORD = 6, /* numbers */ PROP_PIXEL = 12, @@ -127,7 +128,7 @@ typedef enum PropertySubType { PROP_FACTOR = 15, PROP_ANGLE = 16 | PROP_UNIT_ROTATION, PROP_TIME = 17 | PROP_UNIT_TIME, - /* distance in 3d space, don't use for pixel distance for eg. */ + /** Distance in 3d space, don't use for pixel distance for eg. */ PROP_DISTANCE = 18 | PROP_UNIT_LENGTH, PROP_DISTANCE_CAMERA = 19 | PROP_UNIT_CAMERA, @@ -143,14 +144,16 @@ typedef enum PropertySubType { PROP_AXISANGLE = 28, PROP_XYZ = 29, PROP_XYZ_LENGTH = 29 | PROP_UNIT_LENGTH, - PROP_COLOR_GAMMA = 30, /* used for colors which would be color managed before display */ - PROP_COORDS = 31, /* generic array, no units applied, only that x/y/z/w are used (python vec) */ + /** Used for colors which would be color managed before display. */ + PROP_COLOR_GAMMA = 30, + /** Generic array, no units applied, only that x/y/z/w are used (Python vector). */ + PROP_COORDS = 31, /* booleans */ PROP_LAYER = 40, PROP_LAYER_MEMBER = 41, - /* light */ + /** Light */ PROP_POWER = 42 | PROP_UNIT_POWER, } PropertySubType; @@ -158,62 +161,72 @@ typedef enum PropertySubType { /* HIGHEST FLAG IN USE: 1 << 31 * FREE FLAGS: 2, 9, 11, 13, 14, 15, 30 */ typedef enum PropertyFlag { - /* editable means the property is editable in the user + /** + * Editable means the property is editable in the user * interface, properties are editable by default except - * for pointers and collections. */ + * for pointers and collections. + */ PROP_EDITABLE = (1 << 0), - - /* this property is editable even if it is lib linked, + /** + * This property is editable even if it is lib linked, * meaning it will get lost on reload, but it's useful - * for editing. */ + * for editing. + */ PROP_LIB_EXCEPTION = (1 << 16), - - /* animatable means the property can be driven by some + /** + * Animatable means the property can be driven by some * other input, be it animation curves, expressions, .. * properties are animatable by default except for pointers - * and collections */ + * and collections. + */ PROP_ANIMATABLE = (1 << 1), - - /* This flag means when the property's widget is in 'textedit' mode, it will be updated + /** + * This flag means when the property's widget is in 'textedit' mode, it will be updated * after every typed char, instead of waiting final validation. Used e.g. for text searchbox. * It will also cause UI_BUT_VALUE_CLEAR to be set for text buttons. We could add an own flag - * for search/filter properties, but this works just fine for now. */ + * for search/filter properties, but this works just fine for now. + */ PROP_TEXTEDIT_UPDATE = (1u << 31), /* icon */ PROP_ICONS_CONSECUTIVE = (1 << 12), PROP_ICONS_REVERSE = (1 << 8), - /* hidden in the user interface */ + /** Hidden in the user interface. */ PROP_HIDDEN = (1 << 19), - /* do not write in presets */ + /** Do not write in presets. */ PROP_SKIP_SAVE = (1 << 28), /* numbers */ - /* each value is related proportionally (object scale, image size) */ + /** Each value is related proportionally (object scale, image size). */ PROP_PROPORTIONAL = (1 << 26), /* pointers */ PROP_ID_REFCOUNT = (1 << 6), - /* disallow assigning a variable to its self, eg an object tracking its self - * only apply this to types that are derived from an ID ()*/ + /** + * Disallow assigning a variable to its self, eg an object tracking its self + * only apply this to types that are derived from an ID (). + */ PROP_ID_SELF_CHECK = (1 << 20), - /* use for... + /** + * Use for... * - pointers: in the UI and python so unsetting or setting to None won't work. * - strings: so our internal generated get/length/set * functions know to do NULL checks before access T30865. */ PROP_NEVER_NULL = (1 << 18), - /* currently only used for UI, this is similar to PROP_NEVER_NULL + /** + * Currently only used for UI, this is similar to PROP_NEVER_NULL * except that the value may be NULL at times, used for ObData, where an Empty's will be NULL * but setting NULL on a mesh object is not possible. * So, if its not NULL, setting NULL cant be done! */ PROP_NEVER_UNLINK = (1 << 25), - /* Pointers to data that is not owned by the struct. + /** + * Pointers to data that is not owned by the struct. * Typical example: Bone.parent, Bone.child, etc., and nearly all ID pointers. * This is crucial information for processes that walk the whole data of an ID e.g. * (like library override). @@ -222,11 +235,12 @@ typedef enum PropertyFlag { */ PROP_PTR_NO_OWNERSHIP = (1 << 7), - /* flag contains multiple enums. + /** + * flag contains multiple enums. * note: not to be confused with prop->enumbitflags * this exposes the flag as multiple options in python and the UI. * - * note: these can't be animated so use with care. + * \note These can't be animated so use with care. */ PROP_ENUM_FLAG = (1 << 21), @@ -238,55 +252,72 @@ typedef enum PropertyFlag { PROP_REGISTER = (1 << 4), PROP_REGISTER_OPTIONAL = PROP_REGISTER | (1 << 5), - /* Use for arrays or for any data that should not have a reference kept - * most common case is functions that return arrays where the array */ + /** + * Use for arrays or for any data that should not have a reference kept + * most common case is functions that return arrays where the array. + */ PROP_THICK_WRAP = (1 << 23), - PROP_IDPROPERTY = (1 << 10), /* This is an IDProperty, not a DNA one. */ - PROP_DYNAMIC = (1 << 17), /* for dynamic arrays, and retvals of type string */ - PROP_ENUM_NO_CONTEXT = (1 << 24), /* for enum that shouldn't be contextual */ - PROP_ENUM_NO_TRANSLATE = - (1 << 29), /* for enums not to be translated (e.g. viewlayers' names in nodes) */ + /** This is an IDProperty, not a DNA one. */ + PROP_IDPROPERTY = (1 << 10), + /** For dynamic arrays, and retvals of type string. */ + PROP_DYNAMIC = (1 << 17), + /** For enum that shouldn't be contextual */ + PROP_ENUM_NO_CONTEXT = (1 << 24), + /** For enums not to be translated (e.g. viewlayers' names in nodes). */ + PROP_ENUM_NO_TRANSLATE = (1 << 29), - /* Don't do dependency graph tag from a property update callback. + /** + * Don't do dependency graph tag from a property update callback. * Use this for properties which defines interface state, for example, - * properties which denotes whether modifier panel is collapsed or not. */ + * properties which denotes whether modifier panel is collapsed or not. + */ PROP_NO_DEG_UPDATE = (1 << 30), } PropertyFlag; -/* Flags related to comparing and overriding RNA properties. - * Make sure enums are updated with these */ -/* FREE FLAGS: 2, 3, 4, 5, 6, 7, 8, 9, 12 and above. */ +/** + * Flags related to comparing and overriding RNA properties. + * Make sure enums are updated with these. + * + * FREE FLAGS: 2, 3, 4, 5, 6, 7, 8, 9, 12 and above. + */ typedef enum PropertyOverrideFlag { - /* Means the property can be overridden by a local 'proxy' of some linked datablock. */ + /** Means the property can be overridden by a local 'proxy' of some linked datablock. */ PROPOVERRIDE_OVERRIDABLE_LIBRARY = (1 << 0), - /* Forbid usage of this property in comparison (& hence override) code. - * Useful e.g. for collections of data like mesh's geometry, particles, etc. */ + /** + * Forbid usage of this property in comparison (& hence override) code. + * Useful e.g. for collections of data like mesh's geometry, particles, etc. + */ PROPOVERRIDE_NO_COMPARISON = (1 << 1), /*** Collections-related ***/ - /* The property supports insertion (collections only). */ + /** The property supports insertion (collections only). */ PROPOVERRIDE_LIBRARY_INSERTION = (1 << 10), - /* Only use indices to compare items in the property, never names (collections only). */ - /* Useful when nameprop of the items is generated from other data - * (e.g. name of material slots is actually name of assigned material). */ + /** Only use indices to compare items in the property, never names (collections only). + * + * Useful when nameprop of the items is generated from other data + * (e.g. name of material slots is actually name of assigned material). + */ PROPOVERRIDE_NO_PROP_NAME = (1 << 11), } PropertyOverrideFlag; -/* Function parameters flags. - * WARNING: 16bits only. */ +/** + * Function parameters flags. + * \warning 16bits only. + */ typedef enum ParameterFlag { PARM_REQUIRED = (1 << 0), PARM_OUTPUT = (1 << 1), PARM_RNAPTR = (1 << 2), - /* This allows for non-breaking API updates, + /** + * This allows for non-breaking API updates, * when adding non-critical new parameter to a callback function. * This way, old py code defining funcs without that parameter would still work. * WARNING: any parameter after the first PYFUNC_OPTIONAL one will be considered as optional! - * NOTE: only for input parameters! + * \note only for input parameters! */ PARM_PYFUNC_OPTIONAL = (1 << 3), } ParameterFlag; @@ -303,17 +334,20 @@ typedef struct ListBaseIterator { typedef struct ArrayIterator { char *ptr; - /* Past the last valid pointer, only for comparisons, ignores skipped values. */ + /** Past the last valid pointer, only for comparisons, ignores skipped values. */ char *endptr; - /* Will be freed if set. */ + /** Will be freed if set. */ void *free_ptr; int itemsize; - /* Array length with no skip functions applied, - * take care not to compare against index from animsys or python indices. */ + /** + * Array length with no skip functions applied, + * take care not to compare against index from animsys or Python indices. + */ int length; - /* Optional skip function, + /** + * Optional skip function, * when set the array as viewed by rna can contain only a subset of the members. * this changes indices so quick array index lookups are not possible when skip function is used. */ @@ -343,7 +377,7 @@ typedef struct CollectionPointerLink { PointerRNA ptr; } CollectionPointerLink; -/* Copy of ListBase for RNA... */ +/** Copy of ListBase for RNA. */ typedef struct CollectionListBase { struct CollectionPointerLink *first, *last; } CollectionListBase; @@ -448,13 +482,13 @@ typedef struct PropertyRNA PropertyRNA; /* Parameter List */ typedef struct ParameterList { - /* storage for parameters */ + /** Storage for parameters*. */ void *data; - /* function passed at creation time */ + /** Function passed at creation time. */ struct FunctionRNA *func; - /* store the parameter size */ + /** Store the parameter size. */ int alloc_size; int arg_count, ret_count; @@ -470,32 +504,41 @@ typedef struct ParameterIterator { int valid; } ParameterIterator; -/* mainly to avoid confusing casts */ +/** Mainly to avoid confusing casts. */ typedef struct ParameterDynAlloc { - intptr_t array_tot; /* important, this breaks when set to an int */ + /** Important, this breaks when set to an int. */ + intptr_t array_tot; void *array; } ParameterDynAlloc; /* Function */ +/** + * Options affecting callback signature. + * + * Those add additional parameters at the beginning of the C callback, like that: + * <pre> + * rna_my_func([ID *_selfid], + * [<DNA_STRUCT> *self|StructRNA *type], + * [Main *bmain], + * [bContext *C], + * [ReportList *reports], + * <other RNA-defined parameters>); + * </pre> + */ typedef enum FunctionFlag { - /***** Options affecting callback signature. *****/ - /* Those add additional parameters at the beginning of the C callback, like that: - * rna_my_func([ID *_selfid], - * [<DNA_STRUCT> *self|StructRNA *type], - * [Main *bmain], - * [bContext *C], - * [ReportList *reports], - * <other RNA-defined parameters>); + /** + * Pass ID owning 'self' data + * (i.e. ptr->id.data, might be same as self in case data is an ID...). */ - /* Pass ID owning 'self' data - * (i.e. ptr->id.data, might be same as self in case data is an ID...). */ FUNC_USE_SELF_ID = (1 << 11), - /* Do not pass the object (DNA struct pointer) from which it is called, - * used to define static or class functions. */ + /** + * Do not pass the object (DNA struct pointer) from which it is called, + * used to define static or class functions. + */ FUNC_NO_SELF = (1 << 0), - /* Pass RNA type, used to define class functions, only valid when FUNC_NO_SELF is set. */ + /** Pass RNA type, used to define class functions, only valid when #FUNC_NO_SELF is set. */ FUNC_USE_SELF_TYPE = (1 << 1), /* Pass Main, bContext and/or ReportList. */ @@ -503,26 +546,32 @@ typedef enum FunctionFlag { FUNC_USE_CONTEXT = (1 << 3), FUNC_USE_REPORTS = (1 << 4), - /***** Registering of python subclasses. *****/ - /* This function is part of the registerable class' interface, - * and can be implemented/redefined in python. */ + /***** Registering of Python subclasses. *****/ + /** + * This function is part of the registerable class' interface, + * and can be implemented/redefined in Python. + */ FUNC_REGISTER = (1 << 5), - /* Subclasses can choose not to implement this function. */ + /** Subclasses can choose not to implement this function. */ FUNC_REGISTER_OPTIONAL = FUNC_REGISTER | (1 << 6), - /* If not set, the python function implementing this call + /** + * If not set, the Python function implementing this call * is not allowed to write into data-blocks. - * Except for WindowManager and Screen currently, see rna_id_write_error() in bpy_rna.c */ + * Except for WindowManager and Screen currently, see rna_id_write_error() in bpy_rna.c + */ FUNC_ALLOW_WRITE = (1 << 12), /***** Internal flags. *****/ - /* UNUSED CURRENTLY? ??? */ + /** UNUSED CURRENTLY? ??? */ FUNC_BUILTIN = (1 << 7), - /* UNUSED CURRENTLY. ??? */ + /** UNUSED CURRENTLY. ??? */ FUNC_EXPORT = (1 << 8), - /* Function has been defined at runtime, not statically in RNA source code. */ + /** Function has been defined at runtime, not statically in RNA source code. */ FUNC_RUNTIME = (1 << 9), - /* UNUSED CURRENTLY? Function owns its identifier and description strings, - * and has to free them when deleted. */ + /** + * UNUSED CURRENTLY? Function owns its identifier and description strings, + * and has to free them when deleted. + */ FUNC_FREE_POINTERS = (1 << 10), } FunctionFlag; @@ -536,21 +585,26 @@ typedef struct FunctionRNA FunctionRNA; /* Struct */ typedef enum StructFlag { - /* indicates that this struct is an ID struct, and to use refcounting */ + /** Indicates that this struct is an ID struct, and to use reference-counting. */ STRUCT_ID = (1 << 0), STRUCT_ID_REFCOUNT = (1 << 1), - STRUCT_UNDO = (1 << 2), /* defaults on, clear for user preferences and similar */ + /** defaults on, clear for user preferences and similar */ + STRUCT_UNDO = (1 << 2), /* internal flags */ STRUCT_RUNTIME = (1 << 3), STRUCT_GENERATED = (1 << 4), STRUCT_FREE_POINTERS = (1 << 5), - STRUCT_NO_IDPROPERTIES = (1 << 6), /* Menus and Panels don't need properties */ - STRUCT_NO_DATABLOCK_IDPROPERTIES = (1 << 7), /* e.g. for Operator */ - STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES = - (1 << 8), /* for PropertyGroup which contains pointers to datablocks */ - STRUCT_PUBLIC_NAMESPACE = (1 << 9), /* Added to type-map #BlenderRNA.structs_map */ - STRUCT_PUBLIC_NAMESPACE_INHERIT = (1 << 10), /* All subtypes are added too. */ + /** Menus and Panels don't need properties */ + STRUCT_NO_IDPROPERTIES = (1 << 6), + /** e.g. for Operator */ + STRUCT_NO_DATABLOCK_IDPROPERTIES = (1 << 7), + /** for PropertyGroup which contains pointers to datablocks */ + STRUCT_CONTAINS_DATABLOCK_IDPROPERTIES = (1 << 8), + /** Added to type-map #BlenderRNA.structs_map */ + STRUCT_PUBLIC_NAMESPACE = (1 << 9), + /** All subtypes are added too. */ + STRUCT_PUBLIC_NAMESPACE_INHERIT = (1 << 10), } StructFlag; typedef int (*StructValidateFunc)(struct PointerRNA *ptr, void *data, int *have_function); @@ -572,17 +626,19 @@ typedef void **(*StructInstanceFunc)(PointerRNA *ptr); typedef struct StructRNA StructRNA; -/* Blender RNA +/** + * Blender RNA * - * Root RNA data structure that lists all struct types. */ - + * Root RNA data structure that lists all struct types. + */ typedef struct BlenderRNA BlenderRNA; -/* Extending +/** + * Extending * * This struct must be embedded in *Type structs in - * order to make then definable through RNA. */ - + * order to make then definable through RNA. + */ typedef struct ExtensionRNA { void *data; StructRNA *srna; |