[Bf-blender-cvs] [30d8829780d] master: Docs: mathutils docstrings

[Campbell Barton]

Commit: 30d8829780d9ab01340254c697985e9d00104347
Author: Campbell Barton
Date:   Sat Sep 9 11:02:26 2017 +1000
Branches: master
https://developer.blender.org/rB30d8829780d9ab01340254c697985e9d00104347

Docs: mathutils docstrings

===================================================================

M	source/blender/python/mathutils/mathutils.h
M	source/blender/python/mathutils/mathutils_Vector.c

===================================================================

diff --git a/source/blender/python/mathutils/mathutils.h b/source/blender/python/mathutils/mathutils.h
index 6ac75565c66..d1fb6dcdb82 100644
--- a/source/blender/python/mathutils/mathutils.h
+++ b/source/blender/python/mathutils/mathutils.h
@@ -41,9 +41,18 @@ extern char BaseMathObject_owner_doc[];
 	(struct_name *)((base_type ? (base_type)->tp_alloc(base_type, 0) : _PyObject_GC_New(&(root_type))));
 
 
-/* BaseMathObject.flag */
+/** BaseMathObject.flag */
 enum {
+	/**
+	 * Do not own the memory used in this vector,
+	 * \note This is error prone if the memory may be freed while this vector is in use.
+	 * Prefer using callbacks where possible, see: #Mathutils_RegisterCallback
+	 */
 	BASE_MATH_FLAG_IS_WRAP    = (1 << 0),
+	/**
+	 * Prevent changes to the vector so it can be used as a set or dictionary key for example.
+	 * (typical use cases for tuple).
+	 */
 	BASE_MATH_FLAG_IS_FROZEN  = (1 << 1),
 };
 #define BASE_MATH_FLAG_DEFAULT 0
diff --git a/source/blender/python/mathutils/mathutils_Vector.c b/source/blender/python/mathutils/mathutils_Vector.c
index 48f8d55f10a..5d46dc284f4 100644
--- a/source/blender/python/mathutils/mathutils_Vector.c
+++ b/source/blender/python/mathutils/mathutils_Vector.c
@@ -3029,6 +3029,11 @@ PyObject *Vector_CreatePyObject(
 	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)
@@ -3055,6 +3060,10 @@ PyObject *Vector_CreatePyObject_wrap(
 	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,
         unsigned char cb_type, unsigned char cb_subtype)
@@ -3071,6 +3080,9 @@ PyObject *Vector_CreatePyObject_cb(
 	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)