[Bf-blender-cvs] [db795a4727b] master: Cleanup: move public doc-strings into headers for 'makesrna'
Campbell Barton
noreply at git.blender.org
Wed Dec 8 07:15:54 CET 2021
Commit: db795a4727b3a2ad56a11147181d5e3d60ca0466
Author: Campbell Barton
Date: Wed Dec 8 17:12:40 2021 +1100
Branches: master
https://developer.blender.org/rBdb795a4727b3a2ad56a11147181d5e3d60ca0466
Cleanup: move public doc-strings into headers for 'makesrna'
Ref T92709
===================================================================
M source/blender/makesrna/RNA_access.h
M source/blender/makesrna/RNA_define.h
M source/blender/makesrna/RNA_enum_types.h
M source/blender/makesrna/intern/rna_access.c
M source/blender/makesrna/intern/rna_access_compare_override.c
M source/blender/makesrna/intern/rna_access_internal.h
M source/blender/makesrna/intern/rna_armature.c
M source/blender/makesrna/intern/rna_asset.c
M source/blender/makesrna/intern/rna_constraint.c
M source/blender/makesrna/intern/rna_define.c
M source/blender/makesrna/intern/rna_internal.h
M source/blender/makesrna/intern/rna_pose.c
M source/blender/makesrna/intern/rna_wm.c
===================================================================
diff --git a/source/blender/makesrna/RNA_access.h b/source/blender/makesrna/RNA_access.h
index 188f933dba5..7fa7405add1 100644
--- a/source/blender/makesrna/RNA_access.h
+++ b/source/blender/makesrna/RNA_access.h
@@ -801,6 +801,11 @@ PropertyRNA *RNA_struct_name_property(const StructRNA *type);
const EnumPropertyItem *RNA_struct_property_tag_defines(const StructRNA *type);
PropertyRNA *RNA_struct_iterator_property(StructRNA *type);
StructRNA *RNA_struct_base(StructRNA *type);
+/**
+ * Use to find the sub-type directly below a base-type.
+ *
+ * So if type were `RNA_SpotLight`, `RNA_struct_base_of(type, &RNA_ID)` would return `&RNA_Light`.
+ */
const StructRNA *RNA_struct_base_child_of(const StructRNA *type, const StructRNA *parent_type);
bool RNA_struct_is_ID(const StructRNA *type);
@@ -823,16 +828,32 @@ struct IDProperty *RNA_struct_idprops(PointerRNA *ptr, bool create);
bool RNA_struct_idprops_check(StructRNA *srna);
bool RNA_struct_idprops_register_check(const StructRNA *type);
bool RNA_struct_idprops_datablock_allowed(const StructRNA *type);
+/**
+ * Whether given type implies datablock usage by IDProperties.
+ * This is used to prevent classes allowed to have IDProperties,
+ * but not datablock ones, to indirectly use some
+ * (e.g. by assigning an IDP_GROUP containing some IDP_ID pointers...).
+ */
bool RNA_struct_idprops_contains_datablock(const StructRNA *type);
+/**
+ * Remove an id-property.
+ */
bool RNA_struct_idprops_unset(PointerRNA *ptr, const char *identifier);
PropertyRNA *RNA_struct_find_property(PointerRNA *ptr, const char *identifier);
bool RNA_struct_contains_property(PointerRNA *ptr, PropertyRNA *prop_test);
unsigned int RNA_struct_count_properties(StructRNA *srna);
-/* lower level functions for access to type properties */
+/**
+ * Low level direct access to type->properties,
+ * note this ignores parent classes so should be used with care.
+ */
const struct ListBase *RNA_struct_type_properties(StructRNA *srna);
PropertyRNA *RNA_struct_type_find_property_no_base(StructRNA *srna, const char *identifier);
+/**
+ * \note #RNA_struct_find_property is a higher level alternative to this function
+ * which takes a #PointerRNA instead of a #StructRNA.
+ */
PropertyRNA *RNA_struct_type_find_property(StructRNA *srna, const char *identifier);
FunctionRNA *RNA_struct_find_function(StructRNA *srna, const char *identifier);
@@ -840,6 +861,9 @@ const struct ListBase *RNA_struct_type_functions(StructRNA *srna);
char *RNA_struct_name_get_alloc(PointerRNA *ptr, char *fixedbuf, int fixedlen, int *r_len);
+/**
+ * Use when registering structs with the #STRUCT_PUBLIC_NAMESPACE flag.
+ */
bool RNA_struct_available_or_report(struct ReportList *reports, const char *identifier);
bool RNA_struct_bl_idname_ok_or_report(struct ReportList *reports,
const char *identifier,
@@ -861,17 +885,32 @@ PropertyUnit RNA_property_unit(PropertyRNA *prop);
PropertyScaleType RNA_property_ui_scale(PropertyRNA *prop);
int RNA_property_flag(PropertyRNA *prop);
int RNA_property_override_flag(PropertyRNA *prop);
+/**
+ * Get the tags set for \a prop as int bitfield.
+ * \note Doesn't perform any validity check on the set bits. #RNA_def_property_tags does this
+ * in debug builds (to avoid performance issues in non-debug builds), which should be
+ * the only way to set tags. Hence, at this point we assume the tag bitfield to be valid.
+ */
int RNA_property_tags(PropertyRNA *prop);
bool RNA_property_builtin(PropertyRNA *prop);
void *RNA_property_py_data_get(PropertyRNA *prop);
int RNA_property_array_length(PointerRNA *ptr, PropertyRNA *prop);
bool RNA_property_array_check(PropertyRNA *prop);
+/**
+ * Return the size of Nth dimension.
+ */
int RNA_property_multi_array_length(PointerRNA *ptr, PropertyRNA *prop, int dimension);
+/**
+ * Used by BPY to make an array from the python object.
+ */
int RNA_property_array_dimension(PointerRNA *ptr, PropertyRNA *prop, int length[]);
char RNA_property_array_item_char(PropertyRNA *prop, int index);
int RNA_property_array_item_index(PropertyRNA *prop, char name);
+/**
+ * \return the maximum length including the \0 terminator. '0' is used when there is no maximum.
+ */
int RNA_property_string_maxlength(PropertyRNA *prop);
const char *RNA_property_ui_name(const PropertyRNA *prop);
@@ -906,6 +945,10 @@ bool RNA_enum_name(const EnumPropertyItem *item, const int value, const char **r
bool RNA_enum_description(const EnumPropertyItem *item, const int value, const char **description);
int RNA_enum_from_value(const EnumPropertyItem *item, const int value);
int RNA_enum_from_identifier(const EnumPropertyItem *item, const char *identifier);
+/**
+ * Take care using this with translated enums,
+ * prefer #RNA_enum_from_identifier where possible.
+ */
int RNA_enum_from_name(const EnumPropertyItem *item, const char *name);
unsigned int RNA_enum_items_count(const EnumPropertyItem *item);
@@ -967,27 +1010,54 @@ StructRNA *RNA_property_pointer_type(PointerRNA *ptr, PropertyRNA *prop);
bool RNA_property_pointer_poll(PointerRNA *ptr, PropertyRNA *prop, PointerRNA *value);
bool RNA_property_editable(PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * Version of #RNA_property_editable that tries to return additional info in \a r_info
+ * that can be exposed in UI.
+ */
bool RNA_property_editable_info(PointerRNA *ptr, PropertyRNA *prop, const char **r_info);
+/**
+ * Same as RNA_property_editable(), except this checks individual items in an array.
+ */
bool RNA_property_editable_index(PointerRNA *ptr, PropertyRNA *prop, int index);
-/* without lib check, only checks the flag */
+/**
+ * Without lib check, only checks the flag.
+ */
bool RNA_property_editable_flag(PointerRNA *ptr, PropertyRNA *prop);
bool RNA_property_animateable(PointerRNA *ptr, PropertyRNA *prop);
bool RNA_property_animated(PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * \note Does not take into account editable status, this has to be checked separately
+ * (using #RNA_property_editable_flag() usually).
+ */
bool RNA_property_overridable_get(PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * Should only be used for custom properties.
+ */
bool RNA_property_overridable_library_set(PointerRNA *ptr,
PropertyRNA *prop,
const bool is_overridable);
bool RNA_property_overridden(PointerRNA *ptr, PropertyRNA *prop);
bool RNA_property_comparable(PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * This function is to check if its possible to create a valid path from the ID
+ * its slow so don't call in a loop.
+ */
bool RNA_property_path_from_ID_check(PointerRNA *ptr, PropertyRNA *prop); /* slow, use with care */
void RNA_property_update(struct bContext *C, PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * \param scene: may be NULL.
+ */
void RNA_property_update_main(struct Main *bmain,
struct Scene *scene,
PointerRNA *ptr,
PropertyRNA *prop);
+/**
+ * \note its possible this returns a false positive in the case of #PROP_CONTEXT_UPDATE
+ * but this isn't likely to be a performance problem.
+ */
bool RNA_property_update_check(struct PropertyRNA *prop);
/* Property Data */
@@ -1031,15 +1101,28 @@ char *RNA_property_string_get_alloc(
PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len);
void RNA_property_string_set(PointerRNA *ptr, PropertyRNA *prop, const char *value);
void RNA_property_string_set_bytes(PointerRNA *ptr, PropertyRNA *prop, const char *value, int len);
+/**
+ * \return the length without `\0` terminator.
+ */
int RNA_property_string_length(PointerRNA *ptr, PropertyRNA *prop);
void RNA_property_string_get_default(PropertyRNA *prop, char *value, int max_len);
char *RNA_property_string_get_default_alloc(
PointerRNA *ptr, PropertyRNA *prop, char *fixedbuf, int fixedlen, int *r_len);
+/**
+ * \return the length without `\0` terminator.
+ */
int RNA_property_string_default_length(PointerRNA *ptr, PropertyRNA *prop);
int RNA_property_enum_get(PointerRNA *ptr, PropertyRNA *prop);
void RNA_property_enum_set(PointerRNA *ptr, PropertyRNA *prop, int value);
int RNA_property_enum_get_default(PointerRNA *ptr, PropertyRNA *prop);
+/**
+ * Get the value of the item that is \a step items away from \a from_value.
+ *
+ * \param from_value: Item value to start stepping from.
+ * \param step: Absolute value defines step size, sign defines direction.
+ * E.g to get the next item, pass 1, for the previous -1.
+ */
int RNA_property_enum_step(
const struct bContext *C, PointerRNA *ptr, PropertyRNA *prop, int from_value, int step);
@@ -1068,6 +1151,9 @@ int RNA_property_collection_lookup_string(PointerRNA *ptr,
PointerRNA *r_ptr);
int RNA_property_collection_lookup_string_index(
PointerRNA *ptr, PropertyRNA *prop, const char *key, PointerRNA *r_ptr, int *r_index);
+/**
+ * Zero return is an assignment error.
+ */
int RNA_property_collection_assign_int(PointerRNA *ptr,
PropertyRNA *prop,
const int key,
@@ -1125,31 +1211,99 @@ char *RNA_path_append(
char *RNA_path_back(const char *path);
#endif
-/* path_resolve() variants only ensure that a valid pointer (and optionally property) exist */
+/* RNA_path_resolve() variants only ensure that a valid pointer (and optionally property) exist. */
+
+/**
+ * Resolve the given RNA Path to find the pointer and/or property
+ * indicated by fully resolving the path.
+ *
+ * \warning Unlike \a RNA_path_resolve_property(), that one *will* try to follow RNAPointers,
+ * e.g. the path 'parent' applied to a RNAObject \a ptr will return the object.parent in \a r_ptr,
+ * and a NULL \a r_prop...
+ *
+ * \note Assumes all pointers provided are valid
+ * \return True if path can be resolved to a valid "pointer + property" OR "pointer only"
+ */
bool RNA_path_resolve(PointerRNA *ptr, const char *path, PointerRNA *r_ptr, PropertyRNA **r_prop);
+/**
+ * Resolve the given RNA Path to find the pointer and/or prope
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list