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

6 files changed, 55 insertions, 43 deletions

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).
+ * <pre>
+ * [1][4][7]   [a]
+ * [2][5][8] * [b]
+ * [3][6][9]   [c]
+ * </pre>
+ *
+ * \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).
- * <pre>
- * [1][4][7]   [a]
- * [2][5][8] * [b]
- * [3][6][9]   [c]
- * </pre>
- *
- * \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