Docs: add doc-strings for some GPU_matrix functions

Also note the use of flat-array length for PyRNA foreach get/set.

source/blender/gpu/GPU_matrix.h

@@ -23,11 +23,23 @@ void GPU_matrix_reset(void);
 
 /* ModelView Matrix (2D or 3D) */
 
-void GPU_matrix_push(void); /* TODO: PushCopy vs PushIdentity? */
+/**
+ * Push a new matrix unto the stack (copying the previous matrix).
+ *
+ * \note A function `GPU_matrix_push_identity` could be added
+ * instead of calling #GPU_matrix_identity_set after pushing.
+ */
+void GPU_matrix_push(void);
 void GPU_matrix_pop(void);
 
+/**
+ * Set the model-view to an identity matrix.
+ */
 void GPU_matrix_identity_set(void);
 
+/**
+ * Scale the model-view matrix.
+ */
 void GPU_matrix_scale_1f(float factor);
 
 /* 3D ModelView Matrix */

source/blender/python/intern/bpy_rna.cc

@@ -5718,6 +5718,8 @@ static PyObject *pyprop_array_foreach_getset(BPy_PropertyArrayRNA *self,
     return nullptr;
   }
 
+  /* NOTE: in this case it's important to use the flat-array size and *not* the result of
+   * `len()`, which uses #pyrna_prop_array_length, see !116457 for details. */
   size = RNA_property_array_length(&self->ptr, self->prop);
   seq_size = PySequence_Size(seq);