Cleanup: move public doc-strings into headers for 'python'

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;

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 */

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) {

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,

source/blender/python/intern/bpy_driver.c

@@ -57,19 +57,12 @@
 #  include <opcode.h>
 #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;
 

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

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[],

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;

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

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. */

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);

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)

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;

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;

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);