Cleanup: move doc-strings into headers, remove duplicates

In some cases move implementation details into the function body.

source/blender/python/generic/py_capi_utils.c

@@ -536,7 +536,6 @@ const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *ite
   return NULL;
 }
 
-/* Silly function, we don't use arg. just check its compatible with `__deepcopy__`. */
 int PyC_CheckArgs_DeepCopy(PyObject *args)
 {
   PyObject *dummy_pydict;
@@ -553,7 +552,6 @@ int PyC_CheckArgs_DeepCopy(PyObject *args)
  * 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)
 {
   const char *null_str = "<null>";
@@ -707,9 +705,10 @@ void PyC_FileAndNum_Safe(const char **r_filename, int *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, ...)
 {
+  /* NOTE: Would be nice if python had this built in. */
+
   Py_ssize_t i;
   PyObject *item = o;
   const char *attr;
@@ -1154,11 +1153,11 @@ bool PyC_IsInterpreterActive(void)
 /** \name #Py_SetPythonHome Wrapper
  * \{ */
 
-/* Would be nice if python had this built in
- * See: https://wiki.blender.org/wiki/Tools/Debugging/PyFromC
- */
 void PyC_RunQuicky(const char *filepath, int n, ...)
 {
+  /* NOTE: Would be nice if python had this built in
+   * See: https://wiki.blender.org/wiki/Tools/Debugging/PyFromC */
+
   FILE *fp = fopen(filepath, "r");
 
   if (fp) {
@@ -1303,7 +1302,6 @@ void PyC_RunQuicky(const char *filepath, int n, ...)
   }
 }
 
-/* generic function to avoid depending on RNA */
 void *PyC_RNA_AsPointer(PyObject *value, const char *type_name)
 {
   PyObject *as_pointer;

source/blender/python/generic/py_capi_utils.h

@@ -15,6 +15,7 @@ extern "C" {
 #include "BLI_sys_types.h"
 #include "BLI_utildefines_variadic.h"
 
+/** Useful to print Python objects while debugging. */
 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).
@@ -146,6 +147,9 @@ void PyC_MainModule_Restore(PyObject *main_mod);
 
 bool PyC_IsInterpreterActive(void);
 
+/**
+ * Generic function to avoid depending on RNA.
+ */
 void *PyC_RNA_AsPointer(PyObject *value, const char *type_name);
 
 /* flag / set --- interchange */
@@ -211,6 +215,9 @@ struct PyC_StringEnum {
 int PyC_ParseStringEnum(PyObject *o, void *p);
 const char *PyC_StringEnum_FindIDFromValue(const struct PyC_StringEnumItems *items, int value);
 
+/**
+ * Silly function, we don't use arg. just check its compatible with `__deepcopy__`.
+ */
 int PyC_CheckArgs_DeepCopy(PyObject *args);
 
 /* Integer parsing (with overflow checks), -1 on error. */

source/blender/python/intern/bpy_rna.c

@@ -84,6 +84,7 @@
  * `bpy.app.handler` callbacks for example.
  * Even though this is arguably "correct", it's going to cause problems for existing scripts,
  * so accept having this for the time being. */
+
 BPy_StructRNA *bpy_context_module = NULL; /* for fast access */
 
 static PyObject *pyrna_struct_Subtype(PointerRNA *ptr);
@@ -6515,10 +6516,6 @@ static PyObject *pyrna_func_doc_get(BPy_FunctionRNA *self, void *UNUSED(closure)
   return ret;
 }
 
-/**
- * Sub-classes of #pyrna_struct_Type which support idprop definitions use this as a meta-class.
- * \note tp_base member is set to `&PyType_Type` on initialization.
- */
 PyTypeObject pyrna_struct_meta_idprop_Type = {
     PyVarObject_HEAD_INIT(NULL, 0)
     /*tp_name*/ "bpy_struct_meta_idprop",
@@ -6578,6 +6575,7 @@ PyTypeObject pyrna_struct_meta_idprop_Type = {
 };
 
 /*-----------------------BPy_StructRNA method def------------------------------*/
+
 PyTypeObject pyrna_struct_Type = {
     PyVarObject_HEAD_INIT(NULL, 0)
     /*tp_name*/ "bpy_struct",
@@ -6644,6 +6642,7 @@ PyTypeObject pyrna_struct_Type = {
 };
 
 /*-----------------------BPy_PropertyRNA method def------------------------------*/
+
 PyTypeObject pyrna_prop_Type = {
     PyVarObject_HEAD_INIT(NULL, 0)
     /*tp_name*/ "bpy_prop",
@@ -6870,6 +6869,7 @@ static PyTypeObject pyrna_prop_collection_idprop_Type = {
 };
 
 /*-----------------------BPy_PropertyRNA method def------------------------------*/
+
 PyTypeObject pyrna_func_Type = {
     PyVarObject_HEAD_INIT(NULL, 0)
     /*tp_name*/ "bpy_func",
@@ -7316,6 +7316,7 @@ static PyObject *pyrna_struct_Subtype(PointerRNA *ptr)
 }
 
 /*-----------------------CreatePyObject---------------------------------*/
+
 PyObject *pyrna_struct_CreatePyObject(PointerRNA *ptr)
 {
   BPy_StructRNA *pyrna = NULL;
@@ -7837,6 +7838,7 @@ int pyrna_struct_as_ptr_or_null_parse(PyObject *o, void *p)
 }
 
 /* Orphan functions, not sure where they should go. */
+
 StructRNA *srna_from_self(PyObject *self, const char *error_prefix)
 {
 
@@ -8680,13 +8682,12 @@ static void bpy_class_free(void *pyob_ptr)
   PyGILState_Release(gilstate);
 }
 
-/**
- * \note This isn't essential to run on startup, since sub-types will lazy initialize.
- * But keep running in debug mode so we get immediate notification of bad class hierarchy
- * or any errors in "bpy_types.py" at load time, so errors don't go unnoticed.
- */
 void pyrna_alloc_types(void)
 {
+  /* NOTE: This isn't essential to run on startup, since sub-types will lazy initialize.
+   * But keep running in debug mode so we get immediate notification of bad class hierarchy
+   * or any errors in "bpy_types.py" at load time, so errors don't go unnoticed. */
+
 #ifdef DEBUG
   PyGILState_STATE gilstate;
 

source/blender/python/intern/bpy_rna.h

@@ -56,6 +56,10 @@ struct ID;
 extern "C" {
 #endif
 
+/**
+ * Sub-classes of #pyrna_struct_Type which support idprop definitions use this as a meta-class.
+ * \note tp_base member is set to `&PyType_Type` on initialization.
+ */
 extern PyTypeObject pyrna_struct_meta_idprop_Type;
 extern PyTypeObject pyrna_struct_Type;
 extern PyTypeObject pyrna_prop_Type;

source/blender/python/mathutils/mathutils.c

@@ -511,6 +511,7 @@ int EXPP_FloatsAreEqual(float af, float bf, int maxDiff)
 
 /*---------------------- EXPP_VectorsAreEqual -------------------------
  * Builds on EXPP_FloatsAreEqual to test vectors */
+
 int EXPP_VectorsAreEqual(const float *vecA, const float *vecB, int size, int floatSteps)
 {
   int x;
@@ -570,9 +571,10 @@ int _BaseMathObject_CheckCallback(BaseMathObject *self)
   return -1;
 }
 
-/* use macros to check for NULL */
 int _BaseMathObject_ReadCallback(BaseMathObject *self)
 {
+  /* NOTE: use macros to check for NULL. */
+
   Mathutils_Callback *cb = mathutils_callbacks[self->cb_type];
   if (LIKELY(cb->get(self, self->cb_subtype) != -1)) {
     return 0;
@@ -636,7 +638,8 @@ void _BaseMathObject_RaiseNotFrozenExc(const BaseMathObject *self)
       PyExc_TypeError, "%s is not frozen (mutable), call freeze first", Py_TYPE(self)->tp_name);
 }
 
-/* BaseMathObject generic functions for all mathutils types */
+/* #BaseMathObject generic functions for all mathutils types. */
+
 char BaseMathObject_owner_doc[] = "The item this is wrapping or None  (read-only).";
 PyObject *BaseMathObject_owner_get(BaseMathObject *self, void *UNUSED(closure))
 {

source/blender/python/mathutils/mathutils_geometry.c

@@ -1804,6 +1804,7 @@ static struct PyModuleDef M_Geometry_module_def = {
 };
 
 /*----------------------------MODULE INIT-------------------------*/
+
 PyMODINIT_FUNC PyInit_mathutils_geometry(void)
 {
   PyObject *submodule = PyModule_Create(&M_Geometry_module_def);

source/blender/python/mathutils/mathutils_interpolate.c

@@ -100,6 +100,7 @@ static struct PyModuleDef M_Interpolate_module_def = {
 };
 
 /*----------------------------MODULE INIT-------------------------*/
+
 PyMODINIT_FUNC PyInit_mathutils_interpolate(void)
 {
   PyObject *submodule = PyModule_Create(&M_Interpolate_module_def);

source/blender/python/mathutils/mathutils_noise.c

@@ -1096,6 +1096,7 @@ static struct PyModuleDef M_Noise_module_def = {
 };
 
 /*----------------------------MODULE INIT-------------------------*/
+
 PyMODINIT_FUNC PyInit_mathutils_noise(void)
 {
   PyObject *submodule = PyModule_Create(&M_Noise_module_def);