Cleanup/Docs: Add comments to Mesh header, rearrange fields

Most of the fields in Mesh had no comments, or outdated misleading
comments. For example, "BMESH ONLY" referred to the BMesh project,
not the data structure. Given how much these structs are used, it should
save a lot of time to have proper comments.

I also rearranged the fields in mesh to have a more logical order. Now
the most important fields come first. In the process I was able to
remove 19 bytes of unnecessary padding (31->12). I just had to
change a `short` flag to `char`.

Differential Revision: https://developer.blender.org/D13454

1 files changed, 18 insertions, 8 deletions

diff --git a/source/blender/makesdna/DNA_meshdata_types.h b/source/blender/makesdna/DNA_meshdata_types.h
index bc6b35c8e43..d32470c0dcc 100644
--- a/source/blender/makesdna/DNA_meshdata_types.h
+++ b/source/blender/makesdna/DNA_meshdata_types.h
@@ -106,19 +106,15 @@ enum {
 };
 
 /**
- * Mesh Loops.
- * Each loop represents the corner of a polygon (#MPoly).
+ * Mesh Face Corners.
+ * "Loop" is an internal name for the corner of a polygon (#MPoly).
  *
  * Typically accessed from #Mesh.mloop.
  */
 typedef struct MLoop {
-  /** Vertex index. */
+  /** Vertex index into an #MVert array. */
   unsigned int v;
-  /**
-   * Edge index.
-   *
-   * \note The e here is because we want to move away from relying on edge hashes.
-   */
+  /** Edge index into an #MEdge array. */
   unsigned int e;
 } MLoop;
 
@@ -291,8 +287,22 @@ typedef struct MDeformWeight {
   float weight;
 } MDeformWeight;
 
+/**
+ * Stores all of an element's vertex groups, and their weight values.
+ */
 typedef struct MDeformVert {
+  /**
+   * Array of weight indices and values.
+   * - There must not be any duplicate #def_nr indices.
+   * - Groups in the array are unordered.
+   * - Indices outside the usable range of groups are ignored.
+   */
   struct MDeformWeight *dw;
+  /**
+   * The length of the #dw array.
+   * \note This is not necessarily the same length as the total number of vertex groups.
+   * However, generally it isn't larger.
+   */
   int totweight;
   /** Flag is only in use as a run-time tag at the moment. */
   int flag;