From 42a6b2fd06e4fefe1bdb283d9e568d7f7dca178e Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 2 Dec 2021 17:24:04 +1100 Subject: Cleanup: move public doc-strings into headers for 'python' --- source/blender/python/BPY_extern.h | 27 ++++++++ source/blender/python/bmesh/bmesh_py_ops_call.c | 3 - source/blender/python/bmesh/bmesh_py_ops_call.h | 3 + source/blender/python/bmesh/bmesh_py_types.c | 11 --- source/blender/python/bmesh/bmesh_py_types.h | 17 ++++- .../python/bmesh/bmesh_py_types_customdata.c | 7 -- .../python/bmesh/bmesh_py_types_customdata.h | 15 +++-- .../blender/python/bmesh/bmesh_py_types_meshdata.c | 1 - .../blender/python/bmesh/bmesh_py_types_meshdata.h | 1 + .../blender/python/bmesh/bmesh_py_types_select.c | 3 - .../blender/python/bmesh/bmesh_py_types_select.h | 3 + source/blender/python/generic/bgl.c | 7 -- source/blender/python/generic/bgl.h | 9 ++- source/blender/python/generic/bpy_threads.c | 2 - source/blender/python/generic/idprop_py_api.c | 7 -- source/blender/python/generic/idprop_py_api.h | 9 +++ source/blender/python/generic/py_capi_rna.c | 24 ------- source/blender/python/generic/py_capi_rna.h | 24 +++++++ source/blender/python/generic/py_capi_utils.c | 72 -------------------- source/blender/python/generic/py_capi_utils.h | 78 +++++++++++++++++++++- source/blender/python/generic/python_utildefines.h | 12 ++-- source/blender/python/gpu/gpu_py_buffer.c | 7 -- source/blender/python/gpu/gpu_py_buffer.h | 7 ++ source/blender/python/intern/bpy.c | 3 - source/blender/python/intern/bpy.h | 2 + source/blender/python/intern/bpy_capi_utils.c | 3 - source/blender/python/intern/bpy_capi_utils.h | 3 + source/blender/python/intern/bpy_driver.c | 42 ++++-------- source/blender/python/intern/bpy_driver.h | 8 +++ source/blender/python/intern/bpy_interface.c | 10 --- source/blender/python/intern/bpy_operator_wrap.c | 8 --- source/blender/python/intern/bpy_operator_wrap.h | 8 +++ source/blender/python/intern/bpy_props.c | 4 -- source/blender/python/intern/bpy_props.h | 4 ++ source/blender/python/intern/bpy_rna.c | 16 ----- source/blender/python/intern/bpy_rna_array.c | 3 +- source/blender/python/intern/bpy_rna_driver.c | 3 - source/blender/python/intern/bpy_rna_driver.h | 3 + source/blender/python/mathutils/mathutils.c | 17 ----- source/blender/python/mathutils/mathutils.h | 40 +++++++++++ source/blender/python/mathutils/mathutils_Matrix.c | 3 - source/blender/python/mathutils/mathutils_Matrix.h | 3 + source/blender/python/mathutils/mathutils_Vector.c | 23 ------- source/blender/python/mathutils/mathutils_Vector.h | 12 ++++ 44 files changed, 290 insertions(+), 277 deletions(-) (limited to 'source') diff --git a/source/blender/python/BPY_extern.h b/source/blender/python/BPY_extern.h index 43a73363c98..554d4a4541f 100644 --- a/source/blender/python/BPY_extern.h +++ b/source/blender/python/BPY_extern.h @@ -55,7 +55,13 @@ int BPY_is_pyconstraint(struct Text *text); typedef void *BPy_ThreadStatePtr; +/** + * Analogue of #PyEval_SaveThread() + */ BPy_ThreadStatePtr BPY_thread_save(void); +/** + * Analogue of #PyEval_RestoreThread() + */ void BPY_thread_restore(BPy_ThreadStatePtr tstate); /* our own wrappers to Py_BEGIN_ALLOW_THREADS/Py_END_ALLOW_THREADS */ @@ -74,7 +80,18 @@ void BPY_modules_load_user(struct bContext *C); void BPY_app_handlers_reset(const short do_all); +/** + * Update function, it gets rid of py-drivers global dictionary, forcing + * BPY_driver_exec to recreate it. This function is used to force + * reloading the Blender text module "pydrivers.py", if available, so + * updates in it reach py-driver evaluation. + */ void BPY_driver_reset(void); + +/** + * This evaluates Python driver expressions, `driver_orig->expression` + * is a Python expression that should evaluate to a float number, which is returned. + */ float BPY_driver_exec(struct PathResolvedRNA *anim_rna, struct ChannelDriver *driver, struct ChannelDriver *driver_orig, @@ -93,6 +110,16 @@ void BPY_context_update(struct bContext *C); (C)->data.py_context_orig, \ ((const char *[]){__VA_ARGS__}), \ VA_NARGS_COUNT(__VA_ARGS__)) +/** + * Use for `CTX_*_set(..)` functions need to set values which are later read back as expected. + * In this case we don't want the Python context to override the values as it causes problems + * see T66256. + * + * \param dict_p: A pointer to #bContext.data.py_context so we can assign a new value. + * \param dict_orig: The value of #bContext.data.py_context_orig to check if we need to copy. + * + * \note Typically accessed via #BPY_context_dict_clear_members macro. + */ void BPY_context_dict_clear_members_array(void **dict_p, void *dict_orig, const char *context_members[], diff --git a/source/blender/python/bmesh/bmesh_py_ops_call.c b/source/blender/python/bmesh/bmesh_py_ops_call.c index 24887b24eb6..f1423c20b3b 100644 --- a/source/blender/python/bmesh/bmesh_py_ops_call.c +++ b/source/blender/python/bmesh/bmesh_py_ops_call.c @@ -745,9 +745,6 @@ static PyObject *bpy_slot_to_py(BMesh *bm, BMOpSlot *slot) return item; } -/** - * This is the __call__ for bmesh.ops.xxx() - */ PyObject *BPy_BMO_call(BPy_BMeshOpFunc *self, PyObject *args, PyObject *kw) { PyObject *ret; diff --git a/source/blender/python/bmesh/bmesh_py_ops_call.h b/source/blender/python/bmesh/bmesh_py_ops_call.h index 1c7a35788d2..c567375c568 100644 --- a/source/blender/python/bmesh/bmesh_py_ops_call.h +++ b/source/blender/python/bmesh/bmesh_py_ops_call.h @@ -28,4 +28,7 @@ typedef struct { const char *opname; } BPy_BMeshOpFunc; +/** + * This is the `__call__` for `bmesh.ops.xxx()`. + */ PyObject *BPy_BMO_call(BPy_BMeshOpFunc *self, PyObject *args, PyObject *kw); diff --git a/source/blender/python/bmesh/bmesh_py_types.c b/source/blender/python/bmesh/bmesh_py_types.c index 3dd8e58781e..38ec242fa49 100644 --- a/source/blender/python/bmesh/bmesh_py_types.c +++ b/source/blender/python/bmesh/bmesh_py_types.c @@ -3954,7 +3954,6 @@ PyObject *BPy_BMIter_CreatePyObject(BMesh *bm) return (PyObject *)self; } -/* this is just a helper func */ PyObject *BPy_BMElem_CreatePyObject(BMesh *bm, BMHeader *ele) { switch (ele->htype) { @@ -4036,11 +4035,6 @@ void bpy_bm_generic_invalidate(BPy_BMGeneric *self) self->bm = NULL; } -/* generic python seq as BMVert/Edge/Face array, - * return value must be freed with PyMem_FREE(...); - * - * The 'bm_r' value is assigned when empty, and used when set. - */ void *BPy_BMElem_PySeq_As_Array_FAST(BMesh **r_bm, PyObject *seq_fast, Py_ssize_t min, @@ -4233,11 +4227,6 @@ int BPy_BMElem_CheckHType(PyTypeObject *type, const char htype) ((htype & BM_LOOP) && (type == &BPy_BMLoop_Type))); } -/** - * Use for error strings only, not thread safe, - * - * \return a string like '(BMVert/BMEdge/BMFace/BMLoop)' - */ char *BPy_BMElem_StringFromHType_ex(const char htype, char ret[32]) { /* zero to ensure string is always NULL terminated */ diff --git a/source/blender/python/bmesh/bmesh_py_types.h b/source/blender/python/bmesh/bmesh_py_types.h index 043c5322735..42d1fee31c3 100644 --- a/source/blender/python/bmesh/bmesh_py_types.h +++ b/source/blender/python/bmesh/bmesh_py_types.h @@ -148,9 +148,15 @@ PyObject *BPy_BMFaceSeq_CreatePyObject(BMesh *bm); PyObject *BPy_BMLoopSeq_CreatePyObject(BMesh *bm); PyObject *BPy_BMIter_CreatePyObject(BMesh *bm); -/* Just checks type and creates v/e/f/l. */ +/** Just checks type and creates vert/edge/face/loop. */ PyObject *BPy_BMElem_CreatePyObject(BMesh *bm, BMHeader *ele); +/** + * Generic python seq as BMVert/Edge/Face array, + * return value must be freed with PyMem_FREE(...); + * + * The 'bm_r' value is assigned when empty, and used when set. + */ void *BPy_BMElem_PySeq_As_Array_FAST(BMesh **r_bm, PyObject *seq_fast, Py_ssize_t min, @@ -177,6 +183,11 @@ PyObject *BPy_BMFace_Array_As_Tuple(BMesh *bm, BMFace **elem, Py_ssize_t elem_le PyObject *BPy_BMLoop_Array_As_Tuple(BMesh *bm, BMLoop **elem, Py_ssize_t elem_len); int BPy_BMElem_CheckHType(PyTypeObject *type, const char htype); +/** + * Use for error strings only, not thread safe, + * + * \return a string like '(BMVert/BMEdge/BMFace/BMLoop)' + */ char *BPy_BMElem_StringFromHType_ex(const char htype, char ret[32]); char *BPy_BMElem_StringFromHType(const char htype); @@ -198,7 +209,9 @@ int bpy_bm_generic_valid_check_source(BMesh *bm_source, } \ (void)0 -/* macros like BPY_BM_CHECK_OBJ/BPY_BM_CHECK_INT that ensure we're from the right BMesh */ +/** + * Macros like `BPY_BM_CHECK_OBJ/BPY_BM_CHECK_INT` that ensure we're from the right #BMesh. + */ #define BPY_BM_CHECK_SOURCE_OBJ(bm, errmsg, ...) \ { \ void *_args[] = {__VA_ARGS__}; \ diff --git a/source/blender/python/bmesh/bmesh_py_types_customdata.c b/source/blender/python/bmesh/bmesh_py_types_customdata.c index 0aa92158524..1e1ba5edb0f 100644 --- a/source/blender/python/bmesh/bmesh_py_types_customdata.c +++ b/source/blender/python/bmesh/bmesh_py_types_customdata.c @@ -1104,13 +1104,6 @@ static void *bpy_bmlayeritem_ptr_get(BPy_BMElem *py_ele, BPy_BMLayerItem *py_lay return value; } -/** - *\brief BMElem.__getitem__() - * - * assume all error checks are done, eg: - * - * uv = vert[uv_layer] - */ PyObject *BPy_BMLayerItem_GetItem(BPy_BMElem *py_ele, BPy_BMLayerItem *py_layer) { void *value = bpy_bmlayeritem_ptr_get(py_ele, py_layer); diff --git a/source/blender/python/bmesh/bmesh_py_types_customdata.h b/source/blender/python/bmesh/bmesh_py_types_customdata.h index 8552942f73a..a5555a14ad7 100644 --- a/source/blender/python/bmesh/bmesh_py_types_customdata.h +++ b/source/blender/python/bmesh/bmesh_py_types_customdata.h @@ -23,7 +23,8 @@ #pragma once -/* all use BPy_BMLayerAccess struct */ +/* All use #BPy_BMLayerAccess struct. */ + extern PyTypeObject BPy_BMLayerAccessVert_Type; extern PyTypeObject BPy_BMLayerAccessEdge_Type; extern PyTypeObject BPy_BMLayerAccessFace_Type; @@ -36,14 +37,14 @@ extern PyTypeObject BPy_BMLayerItem_Type; #define BPy_BMLayerCollection_Check(v) (Py_TYPE(v) == &BPy_BMLayerCollection_Type) #define BPy_BMLayerItem_Check(v) (Py_TYPE(v) == &BPy_BMLayerItem_Type) -/* all layers for vert/edge/face/loop */ +/** All layers for vert/edge/face/loop. */ typedef struct BPy_BMLayerAccess { PyObject_VAR_HEAD struct BMesh *bm; /* keep first */ char htype; } BPy_BMLayerAccess; -/* access different layer types deform/uv/vertexcolor */ +/** Access different layer types deform/uv/vertex-color. */ typedef struct BPy_BMLayerCollection { PyObject_VAR_HEAD struct BMesh *bm; /* keep first */ @@ -51,7 +52,7 @@ typedef struct BPy_BMLayerCollection { int type; /* customdata type - CD_XXX */ } BPy_BMLayerCollection; -/* access a specific layer directly */ +/** Access a specific layer directly. */ typedef struct BPy_BMLayerItem { PyObject_VAR_HEAD struct BMesh *bm; /* keep first */ @@ -66,6 +67,10 @@ PyObject *BPy_BMLayerItem_CreatePyObject(BMesh *bm, const char htype, int type, void BPy_BM_init_types_customdata(void); -/* __getitem__ / __setitem__ */ +/** + *\brief BMElem.__getitem__() / __setitem__() + * + * Assume all error checks are done, eg: `uv = vert[uv_layer]` + */ PyObject *BPy_BMLayerItem_GetItem(BPy_BMElem *py_ele, BPy_BMLayerItem *py_layer); int BPy_BMLayerItem_SetItem(BPy_BMElem *py_ele, BPy_BMLayerItem *py_layer, PyObject *value); diff --git a/source/blender/python/bmesh/bmesh_py_types_meshdata.c b/source/blender/python/bmesh/bmesh_py_types_meshdata.c index d0c745e6a1d..dffc0814d9d 100644 --- a/source/blender/python/bmesh/bmesh_py_types_meshdata.c +++ b/source/blender/python/bmesh/bmesh_py_types_meshdata.c @@ -683,7 +683,6 @@ PyObject *BPy_BMDeformVert_CreatePyObject(struct MDeformVert *dvert) /* --- End Mesh Deform Vert --- */ -/* call to init all types */ void BPy_BM_init_types_meshdata(void) { bm_init_types_bmloopuv(); diff --git a/source/blender/python/bmesh/bmesh_py_types_meshdata.h b/source/blender/python/bmesh/bmesh_py_types_meshdata.h index 426bfcef6a0..b52bf6889bc 100644 --- a/source/blender/python/bmesh/bmesh_py_types_meshdata.h +++ b/source/blender/python/bmesh/bmesh_py_types_meshdata.h @@ -50,4 +50,5 @@ PyObject *BPy_BMLoopColor_CreatePyObject(struct MLoopCol *mloopcol); int BPy_BMDeformVert_AssignPyObject(struct MDeformVert *dvert, PyObject *value); PyObject *BPy_BMDeformVert_CreatePyObject(struct MDeformVert *dvert); +/* call to init all types */ void BPy_BM_init_types_meshdata(void); diff --git a/source/blender/python/bmesh/bmesh_py_types_select.c b/source/blender/python/bmesh/bmesh_py_types_select.c index b89822a080c..bc8c6853ff5 100644 --- a/source/blender/python/bmesh/bmesh_py_types_select.c +++ b/source/blender/python/bmesh/bmesh_py_types_select.c @@ -411,9 +411,6 @@ void BPy_BM_init_types_select(void) /* utility function */ -/** - * \note doesn't actually check selection. - */ int BPy_BMEditSel_Assign(BPy_BMesh *self, PyObject *value) { BMesh *bm; diff --git a/source/blender/python/bmesh/bmesh_py_types_select.h b/source/blender/python/bmesh/bmesh_py_types_select.h index 34ca162dd09..6b8609e36a6 100644 --- a/source/blender/python/bmesh/bmesh_py_types_select.h +++ b/source/blender/python/bmesh/bmesh_py_types_select.h @@ -46,4 +46,7 @@ void BPy_BM_init_types_select(void); PyObject *BPy_BMEditSel_CreatePyObject(BMesh *bm); PyObject *BPy_BMEditSelIter_CreatePyObject(BMesh *bm); +/** + * \note doesn't actually check selection. + */ int BPy_BMEditSel_Assign(struct BPy_BMesh *self, PyObject *value); diff --git a/source/blender/python/generic/bgl.c b/source/blender/python/generic/bgl.c index e416727fa70..3f01ff86f49 100644 --- a/source/blender/python/generic/bgl.c +++ b/source/blender/python/generic/bgl.c @@ -666,13 +666,6 @@ static Buffer *BGL_MakeBuffer_FromData( return buffer; } -/** - * Create a buffer object - * - * \param dimensions: An array of ndimensions integers representing the size of each dimension. - * \param initbuffer: When not NULL holds a contiguous buffer - * with the correct format from which the buffer will be initialized - */ Buffer *BGL_MakeBuffer(int type, int ndimensions, int *dimensions, void *initbuffer) { Buffer *buffer; diff --git a/source/blender/python/generic/bgl.h b/source/blender/python/generic/bgl.h index 4e59eab46ce..479c69b5de2 100644 --- a/source/blender/python/generic/bgl.h +++ b/source/blender/python/generic/bgl.h @@ -22,6 +22,13 @@ PyObject *BPyInit_bgl(void); +/** + * Create a buffer object + * + * \param dimensions: An array of ndimensions integers representing the size of each dimension. + * \param initbuffer: When not NULL holds a contiguous buffer + * with the correct format from which the buffer will be initialized + */ struct _Buffer *BGL_MakeBuffer(int type, int ndimensions, int *dimensions, void *initbuffer); int BGL_typeSize(int type); @@ -50,5 +57,5 @@ typedef struct _Buffer { } buf; } Buffer; -/** The type object */ +/** The type object. */ extern PyTypeObject BGL_bufferType; diff --git a/source/blender/python/generic/bpy_threads.c b/source/blender/python/generic/bpy_threads.c index 8aa8c5c5d92..41e2fb4adf2 100644 --- a/source/blender/python/generic/bpy_threads.c +++ b/source/blender/python/generic/bpy_threads.c @@ -26,7 +26,6 @@ #include "../BPY_extern.h" #include "BLI_utildefines.h" -/* analogue of PyEval_SaveThread() */ BPy_ThreadStatePtr BPY_thread_save(void) { /* Use `_PyThreadState_UncheckedGet()` instead of `PyThreadState_Get()`, to avoid a fatal error @@ -40,7 +39,6 @@ BPy_ThreadStatePtr BPY_thread_save(void) return NULL; } -/* analogue of PyEval_RestoreThread() */ void BPY_thread_restore(BPy_ThreadStatePtr tstate) { if (tstate) { diff --git a/source/blender/python/generic/idprop_py_api.c b/source/blender/python/generic/idprop_py_api.c index 8dc0d2fb857..ea7dc5d215b 100644 --- a/source/blender/python/generic/idprop_py_api.c +++ b/source/blender/python/generic/idprop_py_api.c @@ -686,12 +686,6 @@ static IDProperty *idp_from_PyObject(PyObject *name_obj, PyObject *ob) /** \name Mapping Get/Set (Internal Access) * \{ */ -/** - * \note group can be a pointer array or a group. - * assume we already checked key is a string. - * - * \return success. - */ bool BPy_IDProperty_Map_ValidateAndCreate(PyObject *name_obj, IDProperty *group, PyObject *ob) { IDProperty *prop = idp_from_PyObject(name_obj, ob); @@ -779,7 +773,6 @@ static PyObject *BPy_IDGroup_iter(BPy_IDProperty *self) return BPy_IDGroup_ViewKeys_CreatePyObject(self); } -/* for simple, non nested types this is the same as BPy_IDGroup_WrapData */ PyObject *BPy_IDGroup_MapDataToPy(IDProperty *prop) { switch (prop->type) { diff --git a/source/blender/python/generic/idprop_py_api.h b/source/blender/python/generic/idprop_py_api.h index f53c45b07c2..e4addcecc10 100644 --- a/source/blender/python/generic/idprop_py_api.h +++ b/source/blender/python/generic/idprop_py_api.h @@ -95,8 +95,17 @@ PyObject *BPy_Wrap_GetItems_View_WithID(struct ID *id, struct IDProperty *prop); int BPy_Wrap_SetMapItem(struct IDProperty *prop, PyObject *key, PyObject *val); +/** + * For simple, non nested types this is the same as #BPy_IDGroup_WrapData. + */ PyObject *BPy_IDGroup_MapDataToPy(struct IDProperty *prop); PyObject *BPy_IDGroup_WrapData(struct ID *id, struct IDProperty *prop, struct IDProperty *parent); +/** + * \note group can be a pointer array or a group. + * assume we already checked key is a string. + * + * \return success. + */ bool BPy_IDProperty_Map_ValidateAndCreate(PyObject *key, struct IDProperty *group, PyObject *ob); void IDProp_Init_Types(void); diff --git a/source/blender/python/generic/py_capi_rna.c b/source/blender/python/generic/py_capi_rna.c index 235b136ca74..a6a0d820d07 100644 --- a/source/blender/python/generic/py_capi_rna.c +++ b/source/blender/python/generic/py_capi_rna.c @@ -41,10 +41,6 @@ /** \name Enum Utilities * \{ */ -/** - * Convert all items into a single comma separated string. - * Use for creating useful error messages. - */ char *pyrna_enum_repr(const EnumPropertyItem *item) { DynStr *dynstr = BLI_dynstr_new(); @@ -69,9 +65,6 @@ char *pyrna_enum_repr(const EnumPropertyItem *item) /** \name Enum Conversion Utilities * \{ */ -/** - * Same as #RNA_enum_value_from_id, but raises an exception. - */ int pyrna_enum_value_from_id(const EnumPropertyItem *item, const char *identifier, int *r_value, @@ -88,14 +81,6 @@ int pyrna_enum_value_from_id(const EnumPropertyItem *item, return 0; } -/** - * Takes a set of strings and map it to and array of booleans. - * - * Useful when the values aren't flags. - * - * \param type_convert_sign: Maps signed to unsigned range, - * needed when we want to use the full range of a signed short/char. - */ BLI_bitmap *pyrna_enum_bitmap_from_set(const EnumPropertyItem *items, PyObject *value, int type_size, @@ -159,9 +144,6 @@ error: return NULL; } -/** - * 'value' _must_ be a set type, error check before calling. - */ int pyrna_enum_bitfield_from_set(const EnumPropertyItem *items, PyObject *value, int *r_value, @@ -223,9 +205,6 @@ PyObject *pyrna_enum_bitfield_as_set(const EnumPropertyItem *items, int value) /** \name Argument Parsing Helpers * \{ */ -/** - * Use with #PyArg_ParseTuple's `O&` formatting. - */ int pyrna_enum_value_parse_string(PyObject *o, void *p) { const char *identifier = PyUnicode_AsUTF8(o); @@ -244,9 +223,6 @@ int pyrna_enum_value_parse_string(PyObject *o, void *p) return 1; } -/** - * Use with #PyArg_ParseTuple's `O&` formatting. - */ int pyrna_enum_bitfield_parse_set(PyObject *o, void *p) { if (!PySet_Check(o)) { diff --git a/source/blender/python/generic/py_capi_rna.h b/source/blender/python/generic/py_capi_rna.h index 326ca777a4b..9733cb043ea 100644 --- a/source/blender/python/generic/py_capi_rna.h +++ b/source/blender/python/generic/py_capi_rna.h @@ -25,13 +25,28 @@ struct EnumPropertyItem; +/** + * Convert all items into a single comma separated string. + * Use for creating useful error messages. + */ char *pyrna_enum_repr(const struct EnumPropertyItem *item); +/** + * Same as #RNA_enum_value_from_id, but raises an exception. + */ int pyrna_enum_value_from_id(const struct EnumPropertyItem *item, const char *identifier, int *value, const char *error_prefix); +/** + * Takes a set of strings and map it to and array of booleans. + * + * Useful when the values aren't flags. + * + * \param type_convert_sign: Maps signed to unsigned range, + * needed when we want to use the full range of a signed short/char. + */ unsigned int *pyrna_enum_bitmap_from_set(const struct EnumPropertyItem *items, PyObject *value, int type_size, @@ -39,6 +54,9 @@ unsigned int *pyrna_enum_bitmap_from_set(const struct EnumPropertyItem *items, int bitmap_size, const char *error_prefix); +/** + * 'value' _must_ be a set type, error check before calling. + */ int pyrna_enum_bitfield_from_set(const struct EnumPropertyItem *items, PyObject *value, int *r_value, @@ -62,5 +80,11 @@ struct BPy_EnumProperty_Parse { int value; bool is_set; }; +/** + * Use with #PyArg_ParseTuple's `O&` formatting. + */ int pyrna_enum_value_parse_string(PyObject *o, void *p); +/** + * Use with #PyArg_ParseTuple's `O&` formatting. + */ int pyrna_enum_bitfield_parse_set(PyObject *o, void *p); diff --git a/source/blender/python/generic/py_capi_utils.c b/source/blender/python/generic/py_capi_utils.c index 9cccc2f608f..acb6d76f30b 100644 --- a/source/blender/python/generic/py_capi_utils.c +++ b/source/blender/python/generic/py_capi_utils.c @@ -470,10 +470,6 @@ PyObject *PyC_Tuple_PackArray_Multi_Bool(const bool *array, const int dims[], co /** \name Tuple/List Filling * \{ */ -/** - * Caller needs to ensure tuple is uninitialized. - * Handy for filling a tuple with None for eg. - */ void PyC_Tuple_Fill(PyObject *tuple, PyObject *value) { const uint tot = PyTuple_GET_SIZE(tuple); @@ -502,11 +498,6 @@ void PyC_List_Fill(PyObject *list, PyObject *value) /** \name Bool/Enum Argument Parsing * \{ */ -/** - * Use with PyArg_ParseTuple's "O&" formatting. - * - * \see #PyC_Long_AsBool for a similar function to use outside of argument parsing. - */ int PyC_ParseBool(PyObject *o, void *p) { bool *bool_p = p; @@ -520,9 +511,6 @@ int PyC_ParseBool(PyObject *o, void *p) return 1; } -/** - * Use with PyArg_ParseTuple's "O&" formatting. - */ int PyC_ParseStringEnum(PyObject *o, void *p) { struct PyC_StringEnum *e = p; @@ -598,10 +586,6 @@ void PyC_ObSpit(const char *name, PyObject *var) } } -/** - * A version of #PyC_ObSpit that writes into a string (and doesn't take a name argument). - * Use for logging. - */ void PyC_ObSpitStr(char *result, size_t result_len, PyObject *var) { /* No name, creator of string can manage that. */ @@ -789,13 +773,6 @@ PyObject *PyC_FrozenSetFromStrings(const char **strings) /** \name Exception Utilities * \{ */ -/** - * Similar to #PyErr_Format(), - * - * Implementation - we can't actually prepend the existing exception, - * because it could have _any_ arguments given to it, so instead we get its - * `__str__` output and raise our own exception including it. - */ PyObject *PyC_Err_Format_Prefix(PyObject *exception_type_prefix, const char *format, ...) { PyObject *error_value_prefix; @@ -835,10 +812,6 @@ PyObject *PyC_Err_SetString_Prefix(PyObject *exception_type_prefix, const char * return PyC_Err_Format_Prefix(exception_type_prefix, "%s", str); } -/** - * Use for Python callbacks run directly from C, - * when we can't use normal methods of raising exceptions. - */ void PyC_Err_PrintWithFunc(PyObject *py_func) { /* since we return to C code we can't leave the error */ @@ -1014,7 +987,6 @@ PyObject *PyC_ExceptionBuffer_Simple(void) * In some cases we need to coerce strings, avoid doing this inline. * \{ */ -/* string conversion, escape non-unicode chars, coerce must be set to NULL */ const char *PyC_UnicodeAsByteAndSize(PyObject *py_str, Py_ssize_t *size, PyObject **coerce) { const char *result; @@ -1093,18 +1065,6 @@ PyObject *PyC_UnicodeFromByte(const char *str) /** \name Name Space Creation/Manipulation * \{ */ -/***************************************************************************** - * Description: This function creates a new Python dictionary object. - * NOTE: dict is owned by sys.modules["__main__"] module, reference is borrowed - * NOTE: important we use the dict from __main__, this is what python expects - * for 'pickle' to work as well as strings like this... - * >> foo = 10 - * >> print(__import__("__main__").foo) - * - * NOTE: this overwrites __main__ which gives problems with nested calls. - * be sure to run PyC_MainModule_Backup & PyC_MainModule_Restore if there is - * any chance that python is in the call stack. - ****************************************************************************/ PyObject *PyC_DefaultNameSpace(const char *filename) { PyObject *modules = PyImport_GetModuleDict(); @@ -1143,7 +1103,6 @@ bool PyC_NameSpace_ImportArray(PyObject *py_dict, const char *imports[]) return true; } -/* restore MUST be called after this */ void PyC_MainModule_Backup(PyObject **r_main_mod) { PyObject *modules = PyImport_GetModuleDict(); @@ -1468,11 +1427,6 @@ PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag) /** \name Run String (Evaluate to Primitive Types) * \{ */ -/** - * \return success - * - * \note it is caller's responsibility to acquire & release GIL! - */ bool PyC_RunString_AsNumber(const char *imports[], const char *expr, const char *filename, @@ -1648,32 +1602,6 @@ bool PyC_RunString_AsString(const char *imports[], # pragma GCC diagnostic ignored "-Wtype-limits" #endif -/** - * - * Comparison with #PyObject_IsTrue - * ================================ - * - * Even though Python provides a way to retrieve the boolean value for an object, - * in many cases it's far too relaxed, with the following examples coercing values. - * - * \code{.py} - * data.value = "Text" # True. - * data.value = "" # False. - * data.value = {1, 2} # True - * data.value = {} # False. - * data.value = None # False. - * \endcode - * - * In practice this is often a mistake by the script author that doesn't behave as they expect. - * So it's better to be more strict for attribute assignment and function arguments, - * only accepting True/False 0/1. - * - * If coercing a value is desired, it can be done explicitly: `data.value = bool(value)` - * - * \see #PyC_ParseBool for use with #PyArg_ParseTuple and related functions. - * - * \note Don't use `bool` return type, so -1 can be used as an error value. - */ int PyC_Long_AsBool(PyObject *value) { const int test = _PyLong_AsInt(value); diff --git a/source/blender/python/generic/py_capi_utils.h b/source/blender/python/generic/py_capi_utils.h index a8695d2330a..09eade9c477 100644 --- a/source/blender/python/generic/py_capi_utils.h +++ b/source/blender/python/generic/py_capi_utils.h @@ -26,6 +26,10 @@ #include "BLI_utildefines_variadic.h" void PyC_ObSpit(const char *name, PyObject *var); +/** + * A version of #PyC_ObSpit that writes into a string (and doesn't take a name argument). + * Use for logging. + */ void PyC_ObSpitStr(char *result, size_t result_len, PyObject *var); void PyC_LineSpit(void); void PyC_StackSpit(void); @@ -34,9 +38,20 @@ PyObject *PyC_ExceptionBuffer_Simple(void); PyObject *PyC_Object_GetAttrStringArgs(PyObject *o, Py_ssize_t n, ...); PyObject *PyC_FrozenSetFromStrings(const char **strings); +/** + * Similar to #PyErr_Format(), + * + * Implementation - we can't actually prepend the existing exception, + * because it could have _any_ arguments given to it, so instead we get its + * `__str__` output and raise our own exception including it. + */ PyObject *PyC_Err_Format_Prefix(PyObject *exception_type_prefix, const char *format, ...); PyObject *PyC_Err_SetString_Prefix(PyObject *exception_type_prefix, const char *str); +/** + * Use for Python callbacks run directly from C, + * when we can't use normal methods of raising exceptions. + */ void PyC_Err_PrintWithFunc(PyObject *py_func); void PyC_FileAndNum(const char **r_filename, int *r_lineno); @@ -92,6 +107,10 @@ PyObject *PyC_Tuple_PackArray_Multi_F64(const double *array, const int dims[], c PyObject *PyC_Tuple_PackArray_Multi_I32(const int *array, const int dims[], const int dims_len); PyObject *PyC_Tuple_PackArray_Multi_Bool(const bool *array, const int dims[], const int dims_len); +/** + * Caller needs to ensure tuple is uninitialized. + * Handy for filling a tuple with None for eg. + */ void PyC_Tuple_Fill(PyObject *tuple, PyObject *value); void PyC_List_Fill(PyObject *list, PyObject *value); @@ -99,13 +118,31 @@ void PyC_List_Fill(PyObject *list, PyObject *value); PyObject *PyC_UnicodeFromByte(const char *str); PyObject *PyC_UnicodeFromByteAndSize(const char *str, Py_ssize_t size); const char *PyC_UnicodeAsByte(PyObject *py_str, PyObject **coerce); /* coerce must be NULL */ +/** + * String conversion, escape non-unicode chars + * \param coerce: must be set to NULL. + */ const char *PyC_UnicodeAsByteAndSize(PyObject *py_str, Py_ssize_t *size, PyObject **coerce); -/* name namespace function for bpy */ +/** + * Description: This function creates a new Python dictionary object. + * NOTE: dict is owned by sys.modules["__main__"] module, reference is borrowed + * NOTE: important we use the dict from __main__, this is what python expects + * for 'pickle' to work as well as strings like this... + * >> foo = 10 + * >> print(__import__("__main__").foo) + * + * NOTE: this overwrites __main__ which gives problems with nested calls. + * be sure to run PyC_MainModule_Backup & PyC_MainModule_Restore if there is + * any chance that python is in the call stack. + */ PyObject *PyC_DefaultNameSpace(const char *filename); void PyC_RunQuicky(const char *filepath, int n, ...); bool PyC_NameSpace_ImportArray(PyObject *py_dict, const char *imports[]); +/** + * #PyC_MainModule_Restore MUST be called after #PyC_MainModule_Backup. + */ void PyC_MainModule_Backup(PyObject **r_main_mod); void PyC_MainModule_Restore(PyObject *main_mod); @@ -131,6 +168,11 @@ int PyC_FlagSet_ToBitfield(const PyC_FlagSet *items, const char *error_prefix); PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag); +/** + * \return success + * + * \note it is caller's responsibility to acquire & release GIL! + */ bool PyC_RunString_AsNumber(const char **imports, const char *expr, const char *filename, @@ -149,6 +191,11 @@ bool PyC_RunString_AsString(const char **imports, const char *filename, char **r_value); +/** + * Use with PyArg_ParseTuple's "O&" formatting. + * + * \see #PyC_Long_AsBool for a similar function to use outside of argument parsing. + */ int PyC_ParseBool(PyObject *o, void *p); struct PyC_StringEnumItems { @@ -160,6 +207,9 @@ struct PyC_StringEnum { int value_found; }; +/** + * Use with PyArg_ParseTuple's "O&" formatting. + */ int PyC_ParseStringEnum(PyObject *o, void *p); const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *items, const int value); @@ -167,6 +217,32 @@ const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *ite int PyC_CheckArgs_DeepCopy(PyObject *args); /* Integer parsing (with overflow checks), -1 on error. */ +/** + * + * Comparison with #PyObject_IsTrue + * ================================ + * + * Even though Python provides a way to retrieve the boolean value for an object, + * in many cases it's far too relaxed, with the following examples coercing values. + * + * \code{.py} + * data.value = "Text" # True. + * data.value = "" # False. + * data.value = {1, 2} # True + * data.value = {} # False. + * data.value = None # False. + * \endcode + * + * In practice this is often a mistake by the script author that doesn't behave as they expect. + * So it's better to be more strict for attribute assignment and function arguments, + * only accepting True/False 0/1. + * + * If coercing a value is desired, it can be done explicitly: `data.value = bool(value)` + * + * \see #PyC_ParseBool for use with #PyArg_ParseTuple and related functions. + * + * \note Don't use `bool` return type, so -1 can be used as an error value. + */ int PyC_Long_AsBool(PyObject *value); int8_t PyC_Long_AsI8(PyObject *value); int16_t PyC_Long_AsI16(PyObject *value); diff --git a/source/blender/python/generic/python_utildefines.h b/source/blender/python/generic/python_utildefines.h index 1f093e633e4..25300c2fd45 100644 --- a/source/blender/python/generic/python_utildefines.h +++ b/source/blender/python/generic/python_utildefines.h @@ -36,16 +36,20 @@ extern "C" { } \ (void)0 -/* wrap Py_INCREF & return the result, - * use sparingly to avoid comma operator or temp var assignment */ +/** + * Wrap #Py_INCREF & return the result, + * use sparingly to avoid comma operator or temp var assignment. + */ Py_LOCAL_INLINE(PyObject *) Py_INCREF_RET(PyObject *op) { Py_INCREF(op); return op; } -/* Append & transfer ownership to the list, - * avoids inline Py_DECREF all over (which is quite a large macro). */ +/** + * Append & transfer ownership to the list, + * avoids inline #Py_DECREF all over (which is quite a large macro). + */ Py_LOCAL_INLINE(int) PyList_APPEND(PyObject *op, PyObject *v) { int ret = PyList_Append(op, v); diff --git a/source/blender/python/gpu/gpu_py_buffer.c b/source/blender/python/gpu/gpu_py_buffer.c index abfde7b48c8..f074b51af32 100644 --- a/source/blender/python/gpu/gpu_py_buffer.c +++ b/source/blender/python/gpu/gpu_py_buffer.c @@ -687,13 +687,6 @@ size_t bpygpu_Buffer_size(BPyGPUBuffer *buffer) return pygpu_buffer_calc_size(buffer->format, buffer->shape_len, buffer->shape); } -/** - * Create a buffer object - * - * \param shape: An array of `shape_len` integers representing the size of each dimension. - * \param buffer: When not NULL holds a contiguous buffer - * with the correct format from which the buffer will be initialized - */ BPyGPUBuffer *BPyGPU_Buffer_CreatePyObject(const int format, const Py_ssize_t *shape, const int shape_len, diff --git a/source/blender/python/gpu/gpu_py_buffer.h b/source/blender/python/gpu/gpu_py_buffer.h index 9df22e9b780..cbc46339628 100644 --- a/source/blender/python/gpu/gpu_py_buffer.h +++ b/source/blender/python/gpu/gpu_py_buffer.h @@ -48,6 +48,13 @@ typedef struct BPyGPUBuffer { } BPyGPUBuffer; size_t bpygpu_Buffer_size(BPyGPUBuffer *buffer); +/** + * Create a buffer object + * + * \param shape: An array of `shape_len` integers representing the size of each dimension. + * \param buffer: When not NULL holds a contiguous buffer + * with the correct format from which the buffer will be initialized + */ BPyGPUBuffer *BPyGPU_Buffer_CreatePyObject(const int format, const Py_ssize_t *shape, const int shape_len, diff --git a/source/blender/python/intern/bpy.c b/source/blender/python/intern/bpy.c index 152b08f5085..c792773272b 100644 --- a/source/blender/python/intern/bpy.c +++ b/source/blender/python/intern/bpy.c @@ -450,9 +450,6 @@ static PyObject *bpy_import_test(const char *modname) return mod; } -/****************************************************************************** - * Description: Creates the bpy module and adds it to sys.modules for importing - ******************************************************************************/ void BPy_init_modules(struct bContext *C) { PointerRNA ctx_ptr; diff --git a/source/blender/python/intern/bpy.h b/source/blender/python/intern/bpy.h index 25a047edfb5..b77a3e9fb7d 100644 --- a/source/blender/python/intern/bpy.h +++ b/source/blender/python/intern/bpy.h @@ -26,7 +26,9 @@ extern "C" { struct bContext; +/** Creates the bpy module and adds it to `sys.modules` for importing. */ void BPy_init_modules(struct bContext *C); + extern PyObject *bpy_package_py; /* bpy_interface_atexit.c */ diff --git a/source/blender/python/intern/bpy_capi_utils.c b/source/blender/python/intern/bpy_capi_utils.c index 8e9d8c02c03..ed01132ed4e 100644 --- a/source/blender/python/intern/bpy_capi_utils.c +++ b/source/blender/python/intern/bpy_capi_utils.c @@ -56,9 +56,6 @@ short BPy_reports_to_error(ReportList *reports, PyObject *exception, const bool return (report_str == NULL) ? 0 : -1; } -/** - * A version of #BKE_report_write_file_fp that uses Python's stdout. - */ void BPy_reports_write_stdout(const ReportList *reports, const char *header) { if (header) { diff --git a/source/blender/python/intern/bpy_capi_utils.h b/source/blender/python/intern/bpy_capi_utils.h index 80e92d918ac..318b168ec5b 100644 --- a/source/blender/python/intern/bpy_capi_utils.h +++ b/source/blender/python/intern/bpy_capi_utils.h @@ -33,6 +33,9 @@ struct ReportList; /* error reporting */ short BPy_reports_to_error(struct ReportList *reports, PyObject *exception, const bool clear); +/** + * A version of #BKE_report_write_file_fp that uses Python's stdout. + */ void BPy_reports_write_stdout(const struct ReportList *reports, const char *header); bool BPy_errors_to_report_ex(struct ReportList *reports, const char *error_prefix, diff --git a/source/blender/python/intern/bpy_driver.c b/source/blender/python/intern/bpy_driver.c index 7effa25e6e8..bd1f3cd301f 100644 --- a/source/blender/python/intern/bpy_driver.c +++ b/source/blender/python/intern/bpy_driver.c @@ -57,19 +57,12 @@ # include #endif -/** - * For PyDrivers - * (drivers using one-line Python expressions to express relationships between targets). - */ PyObject *bpy_pydriver_Dict = NULL; #ifdef USE_BYTECODE_WHITELIST static PyObject *bpy_pydriver_Dict__whitelist = NULL; #endif -/* For faster execution we keep a special dictionary for pydrivers, with - * the needed modules and aliases. - */ int bpy_pydriver_create_dict(void) { PyObject *d, *mod; @@ -220,11 +213,6 @@ static void bpy_pydriver_namespace_clear_self(void) } } -/* Update function, it gets rid of pydrivers global dictionary, forcing - * BPY_driver_exec to recreate it. This function is used to force - * reloading the Blender text module "pydrivers.py", if available, so - * updates in it reach pydriver evaluation. - */ void BPY_driver_reset(void) { PyGILState_STATE gilstate; @@ -429,28 +417,24 @@ static void bpy_pydriver_namespace_add_depsgraph(PyObject *driver_vars, } } -/** - * This evaluates Python driver expressions, `driver_orig->expression` - * is a Python expression that should evaluate to a float number, which is returned. - * - * (old) NOTE: PyGILState_Ensure() isn't always called because python can call - * the bake operator which intern starts a thread which calls scene update - * which does a driver update. to avoid a deadlock check #PyC_IsInterpreterActive() - * if #PyGILState_Ensure() is needed, see T27683. - * - * (new) NOTE: checking if python is running is not thread-safe T28114 - * now release the GIL on python operator execution instead, using - * #PyEval_SaveThread() / #PyEval_RestoreThread() so we don't lock up blender. - * - * For copy-on-write we always cache expressions and write errors in the - * original driver, otherwise these would get freed while editing. Due to - * the GIL this is thread-safe. - */ float BPY_driver_exec(struct PathResolvedRNA *anim_rna, ChannelDriver *driver, ChannelDriver *driver_orig, const AnimationEvalContext *anim_eval_context) { + /* (old) NOTE: PyGILState_Ensure() isn't always called because python can call + * the bake operator which intern starts a thread which calls scene update + * which does a driver update. to avoid a deadlock check #PyC_IsInterpreterActive() + * if #PyGILState_Ensure() is needed, see T27683. + * + * (new) NOTE: checking if python is running is not thread-safe T28114 + * now release the GIL on python operator execution instead, using + * #PyEval_SaveThread() / #PyEval_RestoreThread() so we don't lock up blender. + * + * For copy-on-write we always cache expressions and write errors in the + * original driver, otherwise these would get freed while editing. + * Due to the GIL this is thread-safe. */ + PyObject *driver_vars = NULL; PyObject *retval = NULL; diff --git a/source/blender/python/intern/bpy_driver.h b/source/blender/python/intern/bpy_driver.h index d5064d9fa56..b7bb0f846e8 100644 --- a/source/blender/python/intern/bpy_driver.h +++ b/source/blender/python/intern/bpy_driver.h @@ -24,7 +24,15 @@ extern "C" { #endif +/** + * For faster execution we keep a special dictionary for py-drivers, with + * the needed modules and aliases. + */ int bpy_pydriver_create_dict(void); +/** + * For PyDrivers + * (drivers using one-line Python expressions to express relationships between targets). + */ extern PyObject *bpy_pydriver_Dict; #ifdef __cplusplus diff --git a/source/blender/python/intern/bpy_interface.c b/source/blender/python/intern/bpy_interface.c index 95affa9dba9..aea91eae913 100644 --- a/source/blender/python/intern/bpy_interface.c +++ b/source/blender/python/intern/bpy_interface.c @@ -175,16 +175,6 @@ static void bpy_context_end(bContext *C) CTX_wm_operator_poll_msg_clear(C); } -/** - * Use for `CTX_*_set(..)` functions need to set values which are later read back as expected. - * In this case we don't want the Python context to override the values as it causes problems - * see T66256. - * - * \param dict_p: A pointer to #bContext.data.py_context so we can assign a new value. - * \param dict_orig: The value of #bContext.data.py_context_orig to check if we need to copy. - * - * \note Typically accessed via #BPY_context_dict_clear_members macro. - */ void BPY_context_dict_clear_members_array(void **dict_p, void *dict_orig, const char *context_members[], diff --git a/source/blender/python/intern/bpy_operator_wrap.c b/source/blender/python/intern/bpy_operator_wrap.c index c2d7257e458..bee64f5de2c 100644 --- a/source/blender/python/intern/bpy_operator_wrap.c +++ b/source/blender/python/intern/bpy_operator_wrap.c @@ -115,10 +115,6 @@ static void operator_properties_init(wmOperatorType *ot) /* end 'ot->prop' assignment */ } -/** - * Generic function used by all Python defined operators - * it's passed as an argument to #WM_operatortype_append_ptr in for operator registration. - */ void BPY_RNA_operator_wrapper(wmOperatorType *ot, void *userdata) { /* take care not to overwrite anything set in @@ -135,10 +131,6 @@ void BPY_RNA_operator_wrapper(wmOperatorType *ot, void *userdata) operator_properties_init(ot); } -/** - * Generic function used by all Python defined macro-operators - * it's passed as an argument to #WM_operatortype_append_ptr in for operator registration. - */ void BPY_RNA_operator_macro_wrapper(wmOperatorType *ot, void *userdata) { wmOperatorType *data = (wmOperatorType *)userdata; diff --git a/source/blender/python/intern/bpy_operator_wrap.h b/source/blender/python/intern/bpy_operator_wrap.h index 9e496cd8d26..41deb06814b 100644 --- a/source/blender/python/intern/bpy_operator_wrap.h +++ b/source/blender/python/intern/bpy_operator_wrap.h @@ -30,7 +30,15 @@ extern "C" { PyObject *PYOP_wrap_macro_define(PyObject *self, PyObject *args); /* exposed to rna/wm api */ +/** + * Generic function used by all Python defined operators + * it's passed as an argument to #WM_operatortype_append_ptr in for operator registration. + */ void BPY_RNA_operator_wrapper(struct wmOperatorType *ot, void *userdata); +/** + * Generic function used by all Python defined macro-operators + * it's passed as an argument to #WM_operatortype_append_ptr in for operator registration. + */ void BPY_RNA_operator_macro_wrapper(struct wmOperatorType *ot, void *userdata); #ifdef __cplusplus diff --git a/source/blender/python/intern/bpy_props.c b/source/blender/python/intern/bpy_props.c index 6a023999283..32b0a9b8230 100644 --- a/source/blender/python/intern/bpy_props.c +++ b/source/blender/python/intern/bpy_props.c @@ -4396,10 +4396,6 @@ PyObject *BPY_rna_props(void) return submodule; } -/** - * Run this on exit, clearing all Python callback users and disable the RNA callback, - * as it would be called after Python has already finished. - */ void BPY_rna_props_clear_all(void) { /* Remove all user counts, so this isn't considered a leak from Python's perspective. */ diff --git a/source/blender/python/intern/bpy_props.h b/source/blender/python/intern/bpy_props.h index e6bbd6f708d..9d739540919 100644 --- a/source/blender/python/intern/bpy_props.h +++ b/source/blender/python/intern/bpy_props.h @@ -25,6 +25,10 @@ extern "C" { #endif PyObject *BPY_rna_props(void); +/** + * Run this on exit, clearing all Python callback users and disable the RNA callback, + * as it would be called after Python has already finished. + */ void BPY_rna_props_clear_all(void); PyObject *BPy_PointerProperty(PyObject *self, PyObject *args, PyObject *kw); diff --git a/source/blender/python/intern/bpy_rna.c b/source/blender/python/intern/bpy_rna.c index 707de1c2581..a79a0ed32bf 100644 --- a/source/blender/python/intern/bpy_rna.c +++ b/source/blender/python/intern/bpy_rna.c @@ -1462,10 +1462,6 @@ PyObject *pyrna_prop_to_py(PointerRNA *ptr, PropertyRNA *prop) return ret; } -/** - * This function is used by operators and converting dicts into collections. - * It takes keyword args and fills them with property values. - */ int pyrna_pydict_to_props(PointerRNA *ptr, PyObject *kw, const bool all_args, @@ -7545,7 +7541,6 @@ PyObject *pyrna_prop_CreatePyObject(PointerRNA *ptr, PropertyRNA *prop) return (PyObject *)pyrna; } -/* Utility func to be used by external modules, sneaky! */ PyObject *pyrna_id_CreatePyObject(ID *id) { if (id) { @@ -7777,9 +7772,6 @@ static struct PyModuleDef bpy_types_module_def = { NULL, /* m_free */ }; -/** - * Accessed from Python as 'bpy.types' - */ PyObject *BPY_rna_types(void) { PyObject *submodule = PyModule_Create(&bpy_types_module_def); @@ -7864,11 +7856,6 @@ StructRNA *pyrna_struct_as_srna(PyObject *self, const bool parent, const char *e } /* Orphan functions, not sure where they should go. */ -/** - * Get the SRNA for methods attached to types. - * - * Caller needs to raise error. - */ StructRNA *srna_from_self(PyObject *self, const char *error_prefix) { @@ -9094,9 +9081,6 @@ static PyObject *pyrna_unregister_class(PyObject *UNUSED(self), PyObject *py_cla Py_RETURN_NONE; } -/** - * Extend RNA types with C/API methods, properties. - */ void pyrna_struct_type_extend_capi(struct StructRNA *srna, struct PyMethodDef *method, struct PyGetSetDef *getset) diff --git a/source/blender/python/intern/bpy_rna_array.c b/source/blender/python/intern/bpy_rna_array.c index fcc796d4545..270c9ad431c 100644 --- a/source/blender/python/intern/bpy_rna_array.c +++ b/source/blender/python/intern/bpy_rna_array.c @@ -990,9 +990,10 @@ PyObject *pyrna_py_from_array(PointerRNA *ptr, PropertyRNA *prop) return pyrna_prop_CreatePyObject(ptr, prop); } -/* TODO: multi-dimensional arrays. */ int pyrna_array_contains_py(PointerRNA *ptr, PropertyRNA *prop, PyObject *value) { + /* TODO: multi-dimensional arrays. */ + const int len = RNA_property_array_length(ptr, prop); int type; int i; diff --git a/source/blender/python/intern/bpy_rna_driver.c b/source/blender/python/intern/bpy_rna_driver.c index 3bddd0ad8c0..0bb8b1ba3e1 100644 --- a/source/blender/python/intern/bpy_rna_driver.c +++ b/source/blender/python/intern/bpy_rna_driver.c @@ -34,9 +34,6 @@ #include "bpy_rna_driver.h" /* own include */ -/** - * A version of #driver_get_variable_value which returns a PyObject. - */ PyObject *pyrna_driver_get_variable_value(struct ChannelDriver *driver, struct DriverTarget *dtar) { PyObject *driver_arg = NULL; diff --git a/source/blender/python/intern/bpy_rna_driver.h b/source/blender/python/intern/bpy_rna_driver.h index cc2c4550870..e34c7e4597c 100644 --- a/source/blender/python/intern/bpy_rna_driver.h +++ b/source/blender/python/intern/bpy_rna_driver.h @@ -28,6 +28,9 @@ struct PathResolvedRNA; extern "C" { #endif +/** + * A version of #driver_get_variable_value which returns a #PyObject. + */ PyObject *pyrna_driver_get_variable_value(struct ChannelDriver *driver, struct DriverTarget *dtar); PyObject *pyrna_driver_self_from_anim_rna(struct PathResolvedRNA *anim_rna); diff --git a/source/blender/python/mathutils/mathutils.c b/source/blender/python/mathutils/mathutils.c index 0043fc36162..6eee9ceebb8 100644 --- a/source/blender/python/mathutils/mathutils.c +++ b/source/blender/python/mathutils/mathutils.c @@ -77,11 +77,6 @@ static int mathutils_array_parse_fast(float *array, return size; } -/** - * helper function that returns a Python `__hash__`. - * - * \note consistent with the equivalent tuple of floats (CPython's 'tuplehash') - */ Py_hash_t mathutils_array_hash(const float *array, size_t array_len) { int i; @@ -114,7 +109,6 @@ Py_hash_t mathutils_array_hash(const float *array, size_t array_len) return x; } -/* helper function returns length of the 'value', -1 on error */ int mathutils_array_parse( float *array, int array_min, int array_max, PyObject *value, const char *error_prefix) { @@ -211,7 +205,6 @@ int mathutils_array_parse( return size; } -/* on error, -1 is returned and no allocation is made */ int mathutils_array_parse_alloc(float **array, int array_min, PyObject *value, @@ -279,7 +272,6 @@ int mathutils_array_parse_alloc(float **array, return ret; } -/* parse an array of vectors */ int mathutils_array_parse_alloc_v(float **array, int array_dim, PyObject *value, @@ -321,7 +313,6 @@ int mathutils_array_parse_alloc_v(float **array, return size; } -/* Parse an sequence array_dim integers into array. */ int mathutils_int_array_parse(int *array, int array_dim, PyObject *value, const char *error_prefix) { int size, i; @@ -357,7 +348,6 @@ int mathutils_int_array_parse(int *array, int array_dim, PyObject *value, const return size; } -/* Parse sequence of array_dim sequences of integers and return allocated result. */ int mathutils_array_parse_alloc_vi(int **array, int array_dim, PyObject *value, @@ -395,12 +385,6 @@ int mathutils_array_parse_alloc_vi(int **array, return size; } -/* Parse sequence of variable-length sequences of int and return allocated - * triple of arrays to represent the result: - * The flattened sequences are put into *array. - * The start index of each sequence goes into start_table. - * The length of each index goes into len_table. - */ int mathutils_array_parse_alloc_viseq( int **array, int **start_table, int **len_table, PyObject *value, const char *error_prefix) { @@ -560,7 +544,6 @@ int EXPP_VectorsAreEqual(const float *vecA, const float *vecB, int size, int flo } #ifndef MATH_STANDALONE -/* dynstr as python string utility functions, frees 'ds'! */ PyObject *mathutils_dynstr_to_py(struct DynStr *ds) { const int ds_len = BLI_dynstr_get_len(ds); /* space for \0 */ diff --git a/source/blender/python/mathutils/mathutils.h b/source/blender/python/mathutils/mathutils.h index 4aa26dcc5be..d73d2afe69b 100644 --- a/source/blender/python/mathutils/mathutils.h +++ b/source/blender/python/mathutils/mathutils.h @@ -162,28 +162,56 @@ void _BaseMathObject_RaiseNotFrozenExc(const BaseMathObject *self); 0) /* utility func */ +/** + * Helper function. + * \return length of `value`, -1 on error. + */ int mathutils_array_parse( float *array, int array_min, int array_max, PyObject *value, const char *error_prefix); +/** + * \return -1 is returned on error and no allocation is made. + */ int mathutils_array_parse_alloc(float **array, int array_min, PyObject *value, const char *error_prefix); +/** + * Parse an array of vectors. + */ int mathutils_array_parse_alloc_v(float **array, int array_dim, PyObject *value, const char *error_prefix); +/** + * Parse an sequence array_dim integers into array. + */ int mathutils_int_array_parse(int *array, int array_dim, PyObject *value, const char *error_prefix); +/** + * Parse sequence of array_dim sequences of integers and return allocated result. + */ int mathutils_array_parse_alloc_vi(int **array, int array_dim, PyObject *value, const char *error_prefix); +/** + * Parse sequence of variable-length sequences of int and return allocated + * triple of arrays to represent the result: + * The flattened sequences are put into *array. + * The start index of each sequence goes into start_table. + * The length of each index goes into len_table. + */ int mathutils_array_parse_alloc_viseq( int **array, int **start_table, int **len_table, PyObject *value, const char *error_prefix); int mathutils_any_to_rotmat(float rmat[3][3], PyObject *value, const char *error_prefix); +/** + * helper function that returns a Python `__hash__`. + * + * \note consistent with the equivalent tuple of floats (CPython's 'tuplehash') + */ Py_hash_t mathutils_array_hash(const float *float_array, size_t array_len); /* zero remaining unused elements of the array */ @@ -194,9 +222,21 @@ Py_hash_t mathutils_array_hash(const float *float_array, size_t array_len); #define MU_ARRAY_FLAGS (MU_ARRAY_ZERO | MU_ARRAY_SPILL) +/** + * Column vector multiplication (Matrix * Vector). + * 
+ * [1][4][7]   [a]
+ * [2][5][8] * [b]
+ * [3][6][9]   [c]
+ *
+ * + * \note Vector/Matrix multiplication is not commutative. + * \note Assume read callbacks have been done first. + */ int column_vector_multiplication(float r_vec[4], VectorObject *vec, MatrixObject *mat); #ifndef MATH_STANDALONE /* dynstr as python string utility functions */ +/* dynstr as python string utility functions, frees 'ds'! */ PyObject *mathutils_dynstr_to_py(struct DynStr *ds); #endif diff --git a/source/blender/python/mathutils/mathutils_Matrix.c b/source/blender/python/mathutils/mathutils_Matrix.c index 28b91e13d47..4396e2f9c7b 100644 --- a/source/blender/python/mathutils/mathutils_Matrix.c +++ b/source/blender/python/mathutils/mathutils_Matrix.c @@ -3382,9 +3382,6 @@ PyObject *Matrix_CreatePyObject_cb( return (PyObject *)self; } -/** - * \param mat: Initialized matrix value to use in-place, allocated with #PyMem_Malloc - */ PyObject *Matrix_CreatePyObject_alloc(float *mat, const ushort num_col, const ushort num_row, diff --git a/source/blender/python/mathutils/mathutils_Matrix.h b/source/blender/python/mathutils/mathutils_Matrix.h index 588c0b94891..56bb4d39d01 100644 --- a/source/blender/python/mathutils/mathutils_Matrix.h +++ b/source/blender/python/mathutils/mathutils_Matrix.h @@ -75,6 +75,9 @@ PyObject *Matrix_CreatePyObject_cb(PyObject *user, unsigned char cb_type, unsigned char cb_subtype) ATTR_WARN_UNUSED_RESULT; +/** + * \param mat: Initialized matrix value to use in-place, allocated with #PyMem_Malloc + */ PyObject *Matrix_CreatePyObject_alloc(float *mat, const ushort num_col, const ushort num_row, diff --git a/source/blender/python/mathutils/mathutils_Vector.c b/source/blender/python/mathutils/mathutils_Vector.c index 23758c5603e..daaf3b3da26 100644 --- a/source/blender/python/mathutils/mathutils_Vector.c +++ b/source/blender/python/mathutils/mathutils_Vector.c @@ -1676,17 +1676,6 @@ static PyObject *Vector_isub(PyObject *v1, PyObject *v2) /*------------------------obj * obj------------------------------ * multiplication */ -/** - * Column vector multiplication (Matrix * Vector). - * 
- * [1][4][7]   [a]
- * [2][5][8] * [b]
- * [3][6][9]   [c]
- *
- * - * \note Vector/Matrix multiplication is not commutative. - * \note Assume read callbacks have been done first. - */ int column_vector_multiplication(float r_vec[MAX_DIMENSIONS], VectorObject *vec, MatrixObject *mat) { float vec_cpy[MAX_DIMENSIONS]; @@ -3166,11 +3155,6 @@ PyObject *Vector_CreatePyObject(const float *vec, const int size, PyTypeObject * return (PyObject *)self; } -/** - * Create a vector that wraps existing memory. - * - * \param vec: Use this vector in-place. - */ PyObject *Vector_CreatePyObject_wrap(float *vec, const int size, PyTypeObject *base_type) { VectorObject *self; @@ -3194,10 +3178,6 @@ PyObject *Vector_CreatePyObject_wrap(float *vec, const int size, PyTypeObject *b return (PyObject *)self; } -/** - * Create a vector where the value is defined by registered callbacks, - * see: #Mathutils_RegisterCallback - */ PyObject *Vector_CreatePyObject_cb(PyObject *cb_user, int size, uchar cb_type, uchar cb_subtype) { VectorObject *self = (VectorObject *)Vector_CreatePyObject(NULL, size, NULL); @@ -3212,9 +3192,6 @@ PyObject *Vector_CreatePyObject_cb(PyObject *cb_user, int size, uchar cb_type, u return (PyObject *)self; } -/** - * \param vec: Initialized vector value to use in-place, allocated with #PyMem_Malloc - */ PyObject *Vector_CreatePyObject_alloc(float *vec, const int size, PyTypeObject *base_type) { VectorObject *self; diff --git a/source/blender/python/mathutils/mathutils_Vector.h b/source/blender/python/mathutils/mathutils_Vector.h index 09fc429f9cc..fb420b32df4 100644 --- a/source/blender/python/mathutils/mathutils_Vector.h +++ b/source/blender/python/mathutils/mathutils_Vector.h @@ -35,14 +35,26 @@ typedef struct { PyObject *Vector_CreatePyObject(const float *vec, const int size, PyTypeObject *base_type) ATTR_WARN_UNUSED_RESULT; +/** + * Create a vector that wraps existing memory. + * + * \param vec: Use this vector in-place. + */ PyObject *Vector_CreatePyObject_wrap(float *vec, const int size, PyTypeObject *base_type) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1); +/** + * Create a vector where the value is defined by registered callbacks, + * see: #Mathutils_RegisterCallback + */ PyObject *Vector_CreatePyObject_cb(PyObject *user, int size, unsigned char cb_type, unsigned char subtype) ATTR_WARN_UNUSED_RESULT; +/** + * \param vec: Initialized vector value to use in-place, allocated with #PyMem_Malloc + */ PyObject *Vector_CreatePyObject_alloc(float *vec, const int size, PyTypeObject *base_type) ATTR_WARN_UNUSED_RESULT -- cgit v1.2.3