From c86fed79d5fda0b8ac0c560f71fd6001e6bf7ca8 Mon Sep 17 00:00:00 2001
From: Campbell Barton <ideasman42@gmail.com>
Date: Thu, 6 Aug 2020 13:51:28 +1000
Subject: Cleanup: use doxy sections for py_capi_utils.c

---
 source/blender/python/generic/py_capi_utils.c | 109 ++++++++++++++++++++++++--
 1 file changed, 102 insertions(+), 7 deletions(-)

(limited to 'source/blender/python/generic/py_capi_utils.c')

diff --git a/source/blender/python/generic/py_capi_utils.c b/source/blender/python/generic/py_capi_utils.c
index 406dbdafe22..a5b0e244fde 100644
--- a/source/blender/python/generic/py_capi_utils.c
+++ b/source/blender/python/generic/py_capi_utils.c
@@ -51,6 +51,10 @@
 #  include "BLI_math_base.h" /* isfinite() */
 #endif
 
+/* -------------------------------------------------------------------- */
+/** \name Fast Python to C Array Conversion for Primitive Types
+ * \{ */
+
 /* array utility function */
 int PyC_AsArray_FAST(void *array,
                      PyObject *value_fast,
@@ -137,11 +141,12 @@ int PyC_AsArray(void *array,
   return ret;
 }
 
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name Typed Tuple Packing
  *
  * \note See #PyC_Tuple_Pack_* macros that take multiple arguments.
- *
  * \{ */
 
 /* array utility function */
@@ -192,6 +197,10 @@ PyObject *PyC_Tuple_PackArray_Bool(const bool *array, uint len)
 
 /** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name Tuple/List Filling
+ * \{ */
+
 /**
  * Caller needs to ensure tuple is uninitialized.
  * Handy for filling a tuple with None for eg.
@@ -218,6 +227,12 @@ void PyC_List_Fill(PyObject *list, PyObject *value)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Bool/Enum Argument Parsing
+ * \{ */
+
 /**
  * Use with PyArg_ParseTuple's "O&" formatting.
  *
@@ -274,8 +289,16 @@ int PyC_CheckArgs_DeepCopy(PyObject *args)
   return PyArg_ParseTuple(args, "|O!:__deepcopy__", &PyDict_Type, &dummy_pydict) != 0;
 }
 
+/** \} */
+
 #ifndef MATH_STANDALONE
 
+/* -------------------------------------------------------------------- */
+/** \name Simple Printing (for debugging)
+ *
+ * These are useful to run directly from a debugger to be able to inspect the state.
+ * \{ */
+
 /* for debugging */
 void PyC_ObSpit(const char *name, PyObject *var)
 {
@@ -360,6 +383,12 @@ void PyC_StackSpit(void)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Access Current Frame File Name & Line Number
+ * \{ */
+
 void PyC_FileAndNum(const char **r_filename, int *r_lineno)
 {
   PyFrameObject *frame;
@@ -419,6 +448,12 @@ void PyC_FileAndNum_Safe(const char **r_filename, int *r_lineno)
   PyC_FileAndNum(r_filename, r_lineno);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Object Access Utilities
+ * \{ */
+
 /* Would be nice if python had this built in */
 PyObject *PyC_Object_GetAttrStringArgs(PyObject *o, Py_ssize_t n, ...)
 {
@@ -447,6 +482,12 @@ PyObject *PyC_Object_GetAttrStringArgs(PyObject *o, Py_ssize_t n, ...)
   return item;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Frozen Set Creation
+ * \{ */
+
 PyObject *PyC_FrozenSetFromStrings(const char **strings)
 {
   const char **str;
@@ -463,6 +504,12 @@ PyObject *PyC_FrozenSetFromStrings(const char **strings)
   return ret;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Exception Utilities
+ * \{ */
+
 /**
  * Similar to #PyErr_Format(),
  *
@@ -528,6 +575,12 @@ void PyC_Err_PrintWithFunc(PyObject *py_func)
           _PyUnicode_AsString(((PyFunctionObject *)py_func)->func_name));
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Exception Buffer Access
+ * \{ */
+
 /* returns the exception string as a new PyUnicode object, depends on external traceback module */
 #  if 0
 
@@ -673,6 +726,14 @@ PyObject *PyC_ExceptionBuffer_Simple(void)
   return string_io_buf;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Unicode Conversion
+ *
+ * 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)
 {
@@ -751,6 +812,12 @@ PyObject *PyC_UnicodeFromByte(const char *str)
   return PyC_UnicodeFromByteAndSize(str, strlen(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
@@ -816,6 +883,12 @@ void PyC_MainModule_Restore(PyObject *main_mod)
   Py_XDECREF(main_mod);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name #Py_SetPythonHome Wrapper
+ * \{ */
+
 /**
  * - Must be called before #Py_Initialize.
  * - Expects output of `BKE_appdir_folder_id(BLENDER_PYTHON, NULL)`.
@@ -867,6 +940,12 @@ bool PyC_IsInterpreterActive(void)
   return (PyThreadState_GetDict() != NULL);
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name #Py_SetPythonHome Wrapper
+ * \{ */
+
 /* Would be nice if python had this built in
  * See: https://wiki.blender.org/wiki/Tools/Debugging/PyFromC
  */
@@ -1052,6 +1131,14 @@ void *PyC_RNA_AsPointer(PyObject *value, const char *type_name)
   }
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Flag Set Utilities (#PyC_FlagSet)
+ *
+ * Convert to/from Python set of strings to an int flag.
+ * \{ */
+
 PyObject *PyC_FlagSet_AsString(PyC_FlagSet *item)
 {
   PyObject *py_items = PyList_New(0);
@@ -1152,6 +1239,12 @@ PyObject *PyC_FlagSet_FromBitfield(PyC_FlagSet *items, int flag)
   return ret;
 }
 
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Run String (Evaluate to Primitive Types)
+ * \{ */
+
 /**
  * \return success
  *
@@ -1315,6 +1408,8 @@ bool PyC_RunString_AsString(const char *imports[],
   return PyC_RunString_AsStringAndSize(imports, expr, filename, r_value, &value_size);
 }
 
+/** \} */
+
 #endif /* #ifndef MATH_STANDALONE */
 
 /* -------------------------------------------------------------------- */
@@ -1402,6 +1497,12 @@ uint32_t PyC_Long_AsU32(PyObject *value)
  * PyC_Long_AsU64
  */
 
+#ifdef __GNUC__
+#  pragma warning(pop)
+#endif
+
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name Py_buffer Utils
  *
@@ -1478,9 +1579,3 @@ bool PyC_StructFmt_type_is_bool(char format)
 }
 
 /** \} */
-
-#ifdef __GNUC__
-#  pragma warning(pop)
-#endif
-
-/** \} */
-- 
cgit v1.2.3