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

Ref T92709

6 files changed, 38 insertions, 27 deletions

diff --git a/source/blender/python/BPY_extern.h b/source/blender/python/BPY_extern.h
index 554d4a4541f..e233a078ea9 100644
--- a/source/blender/python/BPY_extern.h
+++ b/source/blender/python/BPY_extern.h
@@ -75,6 +75,9 @@ void BPY_thread_restore(BPy_ThreadStatePtr tstate);
   (void)0
 
 void BPY_text_free_code(struct Text *text);
+/**
+ * Needed so the #Main pointer in `bpy.data` doesn't become out of date.
+ */
 void BPY_modules_update(void);
 void BPY_modules_load_user(struct bContext *C);
 
@@ -103,6 +106,9 @@ int BPY_context_member_get(struct bContext *C,
                            const char *member,
                            struct bContextDataResult *result);
 void BPY_context_set(struct bContext *C);
+/**
+ * Use for updating while a python script runs - in case of file load.
+ */
 void BPY_context_update(struct bContext *C);
 
 #define BPY_context_dict_clear_members(C, ...) \
@@ -127,6 +133,9 @@ void BPY_context_dict_clear_members_array(void **dict_p,
 
 void BPY_id_release(struct ID *id);
 
+/**
+ * Avoids duplicating keyword list.
+ */
 bool BPY_string_is_keyword(const char *str);
 
 /* bpy_rna_callback.c */
diff --git a/source/blender/python/BPY_extern_python.h b/source/blender/python/BPY_extern_python.h
index c321fd93379..56662ffc040 100644
--- a/source/blender/python/BPY_extern_python.h
+++ b/source/blender/python/BPY_extern_python.h
@@ -32,6 +32,8 @@ extern "C" {
 #include <stdio.h>
 
 /* bpy_interface.c */
+
+/** Call #BPY_context_set first. */
 void BPY_python_start(struct bContext *C, int argc, const char **argv);
 void BPY_python_end(void);
 void BPY_python_reset(struct bContext *C);
diff --git a/source/blender/python/BPY_extern_run.h b/source/blender/python/BPY_extern_run.h
index b65b5d61b9d..8eb8674d058 100644
--- a/source/blender/python/BPY_extern_run.h
+++ b/source/blender/python/BPY_extern_run.h
@@ -31,6 +31,10 @@ struct Text;
 struct bContext;
 
 /* bpy_interface_run.c */
+
+/**
+ * Can run a file or text block.
+ */
 bool BPY_run_filepath(struct bContext *C, const char *filepath, struct ReportList *reports);
 bool BPY_run_text(struct bContext *C,
                   struct Text *text,
@@ -39,7 +43,14 @@ bool BPY_run_text(struct bContext *C,
 
 /* Use the 'eval' for simple single-line expressions,
  * otherwise 'exec' for full multi-line scripts. */
+
+/**
+ * Run an entire script, matches: `exec(compile(..., "exec"))`
+ */
 bool BPY_run_string_exec(struct bContext *C, const char *imports[], const char *expr);
+/**
+ * Run an expression, matches: `exec(compile(..., "eval"))`
+ */
 bool BPY_run_string_eval(struct bContext *C, const char *imports[], const char *expr);
 
 /**
@@ -59,16 +70,28 @@ struct BPy_RunErrInfo {
 };
 
 /* Run, evaluating to fixed type result. */
+
+/**
+ * \return success
+ */
 bool BPY_run_string_as_number(struct bContext *C,
                               const char *imports[],
                               const char *expr,
                               struct BPy_RunErrInfo *err_info,
                               double *r_value);
+/**
+ * Support both int and pointers.
+ *
+ * \return success
+ */
 bool BPY_run_string_as_intptr(struct bContext *C,
                               const char *imports[],
                               const char *expr,
                               struct BPy_RunErrInfo *err_info,
                               intptr_t *r_value);
+/**
+ * \return success
+ */
 bool BPY_run_string_as_string_and_size(struct bContext *C,
                                        const char *imports[],
                                        const char *expr,
diff --git a/source/blender/python/intern/bpy_capi_utils.h b/source/blender/python/intern/bpy_capi_utils.h
index 318b168ec5b..0e4a28fb657 100644
--- a/source/blender/python/intern/bpy_capi_utils.h
+++ b/source/blender/python/intern/bpy_capi_utils.h
@@ -47,6 +47,9 @@ bool BPy_errors_to_report(struct ReportList *reports);
 struct bContext *BPY_context_get(void);
 
 extern void bpy_context_set(struct bContext *C, PyGILState_STATE *gilstate);
+/**
+ * Context should be used but not now because it causes some bugs.
+ */
 extern void bpy_context_clear(struct bContext *C, const PyGILState_STATE *gilstate);
 
 #ifdef __cplusplus
diff --git a/source/blender/python/intern/bpy_interface.c b/source/blender/python/intern/bpy_interface.c
index 7f1917ce6a6..faa668df775 100644
--- a/source/blender/python/intern/bpy_interface.c
+++ b/source/blender/python/intern/bpy_interface.c
@@ -80,6 +80,7 @@
 #include "../mathutils/mathutils.h"
 
 /* Logging types to use anywhere in the Python modules. */
+
 CLG_LOGREF_DECLARE_GLOBAL(BPY_LOG_CONTEXT, "bpy.context");
 CLG_LOGREF_DECLARE_GLOBAL(BPY_LOG_INTERFACE, "bpy.interface");
 CLG_LOGREF_DECLARE_GLOBAL(BPY_LOG_RNA, "bpy.rna");
@@ -103,7 +104,6 @@ static double bpy_timer_run;     /* time for each python script run */
 static double bpy_timer_run_tot; /* accumulate python runs */
 #endif
 
-/* use for updating while a python script runs - in case of file load */
 void BPY_context_update(bContext *C)
 {
   /* don't do this from a non-main (e.g. render) thread, it can cause a race
@@ -141,7 +141,6 @@ void bpy_context_set(bContext *C, PyGILState_STATE *gilstate)
   }
 }
 
-/* context should be used but not now because it causes some bugs */
 void bpy_context_clear(bContext *UNUSED(C), const PyGILState_STATE *gilstate)
 {
   py_call_level--;
@@ -228,9 +227,6 @@ void BPY_text_free_code(Text *text)
   }
 }
 
-/**
- * Needed so the #Main pointer in `bpy.data` doesn't become out of date.
- */
 void BPY_modules_update(void)
 {
 #if 0 /* slow, this runs all the time poll, draw etc 100's of time a sec. */
@@ -323,7 +319,6 @@ static void pystatus_exit_on_error(PyStatus status)
 }
 #endif
 
-/* call BPY_context_set first */
 void BPY_python_start(bContext *C, int argc, const char **argv)
 {
 #ifndef WITH_PYTHON_MODULE
@@ -871,9 +866,6 @@ static void bpy_module_free(void *UNUSED(mod))
 
 #endif
 
-/**
- * Avoids duplicating keyword list.
- */
 bool BPY_string_is_keyword(const char *str)
 {
   /* list is from...
diff --git a/source/blender/python/intern/bpy_interface_run.c b/source/blender/python/intern/bpy_interface_run.c
index f7d6a33c904..e9e5e9634d6 100644
--- a/source/blender/python/intern/bpy_interface_run.c
+++ b/source/blender/python/intern/bpy_interface_run.c
@@ -212,7 +212,6 @@ static bool python_script_exec(
 /** \name Run Text / Filename / String
  * \{ */
 
-/* Can run a file or text block */
 bool BPY_run_filepath(bContext *C, const char *filepath, struct ReportList *reports)
 {
   return python_script_exec(C, filepath, NULL, reports, false);
@@ -271,17 +270,11 @@ static bool bpy_run_string_impl(bContext *C,
   return ok;
 }
 
-/**
- * Run an expression, matches: `exec(compile(..., "eval"))`
- */
 bool BPY_run_string_eval(bContext *C, const char *imports[], const char *expr)
 {
   return bpy_run_string_impl(C, imports, expr, Py_eval_input);
 }
 
-/**
- * Run an entire script, matches: `exec(compile(..., "exec"))`
- */
 bool BPY_run_string_exec(bContext *C, const char *imports[], const char *expr)
 {
   return bpy_run_string_impl(C, imports, expr, Py_file_input);
@@ -330,9 +323,6 @@ static void run_string_handle_error(struct BPy_RunErrInfo *err_info)
   Py_XDECREF(py_err_str);
 }
 
-/**
- * \return success
- */
 bool BPY_run_string_as_number(bContext *C,
                               const char *imports[],
                               const char *expr,
@@ -364,9 +354,6 @@ bool BPY_run_string_as_number(bContext *C,
   return ok;
 }
 
-/**
- * \return success
- */
 bool BPY_run_string_as_string_and_size(bContext *C,
                                        const char *imports[],
                                        const char *expr,
@@ -406,11 +393,6 @@ bool BPY_run_string_as_string(bContext *C,
   return BPY_run_string_as_string_and_size(C, imports, expr, err_info, r_value, &value_dummy_size);
 }
 
-/**
- * Support both int and pointers.
- *
- * \return success
- */
 bool BPY_run_string_as_intptr(bContext *C,
                               const char *imports[],
                               const char *expr,