[Bf-blender-cvs] [ae73bd3d9eb] master: Cleanup: use doxy sections for mathutils types
Campbell Barton
noreply at git.blender.org
Wed May 25 05:44:20 CEST 2022
Commit: ae73bd3d9ebcbbc3729d4f3f23927012c6ac3abd
Author: Campbell Barton
Date: Wed May 25 12:33:15 2022 +1000
Branches: master
https://developer.blender.org/rBae73bd3d9ebcbbc3729d4f3f23927012c6ac3abd
Cleanup: use doxy sections for mathutils types
Also minor improvements & corrections to comments.
===================================================================
M source/blender/python/mathutils/mathutils_Color.c
M source/blender/python/mathutils/mathutils_Color.h
M source/blender/python/mathutils/mathutils_Euler.c
M source/blender/python/mathutils/mathutils_Euler.h
M source/blender/python/mathutils/mathutils_Matrix.c
M source/blender/python/mathutils/mathutils_Matrix.h
M source/blender/python/mathutils/mathutils_Quaternion.c
M source/blender/python/mathutils/mathutils_Quaternion.h
M source/blender/python/mathutils/mathutils_Vector.c
M source/blender/python/mathutils/mathutils_Vector.h
===================================================================
diff --git a/source/blender/python/mathutils/mathutils_Color.c b/source/blender/python/mathutils/mathutils_Color.c
index 0fcde229907..24744d0cb6e 100644
--- a/source/blender/python/mathutils/mathutils_Color.c
+++ b/source/blender/python/mathutils/mathutils_Color.c
@@ -22,8 +22,40 @@
#define COLOR_SIZE 3
-/* ----------------------------------mathutils.Color() ------------------- */
-/* makes a new color for you to play with */
+/* -------------------------------------------------------------------- */
+/** \name Utilities
+ * \{ */
+
+/**
+ * \note #BaseMath_ReadCallback must be called beforehand.
+ */
+static PyObject *Color_to_tuple_ex(ColorObject *self, int ndigits)
+{
+ PyObject *ret;
+ int i;
+
+ ret = PyTuple_New(COLOR_SIZE);
+
+ if (ndigits >= 0) {
+ for (i = 0; i < COLOR_SIZE; i++) {
+ PyTuple_SET_ITEM(ret, i, PyFloat_FromDouble(double_round((double)self->col[i], ndigits)));
+ }
+ }
+ else {
+ for (i = 0; i < COLOR_SIZE; i++) {
+ PyTuple_SET_ITEM(ret, i, PyFloat_FromDouble(self->col[i]));
+ }
+ }
+
+ return ret;
+}
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Type: `__new__` / `mathutils.Color()`
+ * \{ */
+
static PyObject *Color_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
{
float col[3] = {0.0f, 0.0f, 0.0f};
@@ -54,29 +86,11 @@ static PyObject *Color_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
return Color_CreatePyObject(col, type);
}
-/* -----------------------------METHODS---------------------------- */
-
-/* NOTE: BaseMath_ReadCallback must be called beforehand. */
-static PyObject *Color_ToTupleExt(ColorObject *self, int ndigits)
-{
- PyObject *ret;
- int i;
-
- ret = PyTuple_New(COLOR_SIZE);
-
- if (ndigits >= 0) {
- for (i = 0; i < COLOR_SIZE; i++) {
- PyTuple_SET_ITEM(ret, i, PyFloat_FromDouble(double_round((double)self->col[i], ndigits)));
- }
- }
- else {
- for (i = 0; i < COLOR_SIZE; i++) {
- PyTuple_SET_ITEM(ret, i, PyFloat_FromDouble(self->col[i]));
- }
- }
+/** \} */
- return ret;
-}
+/* -------------------------------------------------------------------- */
+/** \name Color Methods: Color Space Conversion
+ * \{ */
PyDoc_STRVAR(Color_from_scene_linear_to_srgb_doc,
".. function:: from_scene_linear_to_srgb()\n"
@@ -190,7 +204,11 @@ static PyObject *Color_from_rec709_linear_to_scene_linear(ColorObject *self)
return Color_CreatePyObject(col, Py_TYPE(self));
}
-/* ---------------------------- Colorspace conversion -------------- */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Methods: Color Copy/Deep-Copy
+ * \{ */
PyDoc_STRVAR(Color_copy_doc,
".. function:: copy()\n"
@@ -218,8 +236,11 @@ static PyObject *Color_deepcopy(ColorObject *self, PyObject *args)
return Color_copy(self);
}
-/* ----------------------------print object (internal)-------------- */
-/* print the object to screen */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Type: `__repr__` & `__str__`
+ * \{ */
static PyObject *Color_repr(ColorObject *self)
{
@@ -229,7 +250,7 @@ static PyObject *Color_repr(ColorObject *self)
return NULL;
}
- tuple = Color_ToTupleExt(self, -1);
+ tuple = Color_to_tuple_ex(self, -1);
ret = PyUnicode_FromFormat("Color(%R)", tuple);
@@ -255,8 +276,12 @@ static PyObject *Color_str(ColorObject *self)
}
#endif
-/* ------------------------tp_richcmpr */
-/* returns -1 exception, 0 false, 1 true */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Type: Rich Compare
+ * \{ */
+
static PyObject *Color_richcmpr(PyObject *a, PyObject *b, int op)
{
PyObject *res;
@@ -295,6 +320,12 @@ static PyObject *Color_richcmpr(PyObject *a, PyObject *b, int op)
return Py_INCREF_RET(res);
}
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Type: Hash (`__hash__`)
+ * \{ */
+
static Py_hash_t Color_hash(ColorObject *self)
{
if (BaseMath_ReadCallback(self) == -1) {
@@ -308,15 +339,19 @@ static Py_hash_t Color_hash(ColorObject *self)
return mathutils_array_hash(self->col, COLOR_SIZE);
}
-/* ---------------------SEQUENCE PROTOCOLS------------------------ */
-/* ----------------------------len(object)------------------------ */
-/* sequence length */
+/** \} */
+
+/* -------------------------------------------------------------------- */
+/** \name Color Type: Sequence & Mapping Protocols Implementation
+ * \{ */
+
+/** Sequence length: `len(object)`. */
static int Color_len(ColorObject *UNUSED(self))
{
return COLOR_SIZE;
}
-/* ----------------------------object[]--------------------------- */
-/* sequence accessor (get) */
+
+/** Sequence accessor (get): `x = object[i]`. */
static PyObject *Color_item(ColorObject *self, int i)
{
if (i < 0) {
@@ -336,8 +371,8 @@ static PyObject *Color_item(ColorObject *self, int i)
return PyFloat_FromDouble(self->col[i]);
}
-/* ----------------------------object[]------------------------- */
-/* sequence accessor (set) */
+
+/** Sequence accessor (set): `object[i] = x`. */
static int Color_ass_item(ColorObject *self, int i, PyObject *value)
{
float f;
@@ -373,8 +408,8 @@ static int Color_ass_item(ColorObject *self, int i, PyObject *value)
return 0;
}
-/* ----------------------------object[z:y]------------------------ */
-/* sequence slice (get) */
+
+/** Sequence slice accessor (get): `x = object[i:j]`. */
static PyObject *Color_slice(ColorObject *self, int begin, int end)
{
PyObject *tuple;
@@ -398,8 +433,8 @@ static PyObject *Color_slice(ColorObject *self, int begin, int end)
return tuple;
}
-/* ----------------------------object[z:y]------------------------ */
-/* sequence slice (set) */
+
+/** Sequence slice accessor (set): `object[i:j] = x`. */
static int Color_ass_slice(ColorObject *self, int begin, int end, PyObject *seq)
{
int i, size;
@@ -436,6 +471,7 @@ static int Color_ass_slice(ColorObject *self, int begin, int end, PyObject *seq)
return 0;
}
+/** Sequence generic subscript (get): `x = object[...]`. */
static PyObject *Color_subscript(ColorObject *self, PyObject *item)
{
if (PyIndex_Check(item)) {
@@ -472,6 +508,7 @@ static PyObject *Color_subscript(ColorObject *self, PyObject *item)
return NULL;
}
+/** Sequence generic subscript (set): `object[...] = x`. */
static int Color_ass_subscript(ColorObject *self, PyObject *item, PyObject *value)
{
if (PyIndex_Check(item)) {
@@ -504,29 +541,13 @@ static int Color_ass_subscript(ColorObject *self, PyObject *item, PyObject *valu
return -1;
}
-/* -----------------PROTCOL DECLARATIONS-------------------------- */
-static PySequenceMethods Color_SeqMethods = {
- (lenfunc)Color_len, /* sq_length */
- (binaryfunc)NULL, /* sq_concat */
- (ssizeargfunc)NULL, /* sq_repeat */
- (ssizeargfunc)Color_item, /* sq_item */
- NULL, /* sq_slice, deprecated */
- (ssizeobjargproc)Color_ass_item, /* sq_ass_item */
- NULL, /* sq_ass_slice, deprecated */
- (objobjproc)NULL, /* sq_contains */
- (binaryfunc)NULL, /* sq_inplace_concat */
- (ssizeargfunc)NULL, /* sq_inplace_repeat */
-};
+/** \} */
-static PyMappingMethods Color_AsMapping = {
- (lenfunc)Color_len,
- (binaryfunc)Color_subscript,
- (objobjargproc)Color_ass_subscript,
-};
-
-/* numeric */
+/* -------------------------------------------------------------------- */
+/** \name Color Type: Numeric Protocol Implementation
+ * \{ */
-/* addition: obj + obj */
+/** Addition: `object + object`. */
static PyObject *Color_add(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL, *color2 = NULL;
@@ -552,7 +573,7 @@ static PyObject *Color_add(PyObject *v1, PyObject *v2)
return Color_CreatePyObject(col, Py_TYPE(v1));
}
-/* addition in-place: obj += obj */
+/** Addition in-place: `object += object`. */
static PyObject *Color_iadd(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL, *color2 = NULL;
@@ -579,7 +600,7 @@ static PyObject *Color_iadd(PyObject *v1, PyObject *v2)
return v1;
}
-/* subtraction: obj - obj */
+/** Subtraction: `object - object`. */
static PyObject *Color_sub(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL, *color2 = NULL;
@@ -605,7 +626,7 @@ static PyObject *Color_sub(PyObject *v1, PyObject *v2)
return Color_CreatePyObject(col, Py_TYPE(v1));
}
-/* subtraction in-place: obj -= obj */
+/** Subtraction in-place: `object -= object`. */
static PyObject *Color_isub(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL, *color2 = NULL;
@@ -639,6 +660,7 @@ static PyObject *color_mul_float(ColorObject *color, const float scalar)
return Color_CreatePyObject(tcol, Py_TYPE(color));
}
+/** Multiplication: `object * object`. */
static PyObject *Color_mul(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL, *color2 = NULL;
@@ -683,6 +705,7 @@ static PyObject *Color_mul(PyObject *v1, PyObject *v2)
return NULL;
}
+/** Division: `object / object`. */
static PyObject *Color_div(PyObject *v1, PyObject *v2)
{
ColorObject *color1 = NULL;
@@ -716,7 +739,7 @@ static PyObject *Color_div(PyObject *v1, PyObject *v2)
return NULL;
}
-/* multiplication in-place: obj *= obj */
+/** Multiplication in-place: `object *= object`. */
static PyObject *Color_imul(PyObject *v1, PyObject *v2)
{
ColorObject *color = (ColorObject *)v1;
@@ -744,7 +767,7 @@ static PyObject *Color_imul(PyObject *v1, PyObject *v2)
return v1;
}
-/* multiplication in-place: obj *= obj */
+/** Division in-place: `object *= object`. */
static PyObject *Color_idiv(PyObject *v1, PyObject *v2)
{
ColorObject *color = (ColorObject *)v1;
@@ -777,8 +800,7 @@ static PyObject *Color_idiv(PyObject *v1, PyObject *v2)
return v1;
}
-/* -obj
- * returns the negative of this object */
+/** Negative (returns the negative of this object): `-object`. */
static PyObjec
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list