[Bf-blender-cvs] [87594726abb] master: Cleanup: Improve documentation in Curves DNA header

[Hans Goudey]

Commit: 87594726abb3090e228aef4cf3b7cfc5fef5182f
Author: Hans Goudey
Date:   Tue Dec 27 10:31:40 2022 -0500
Branches: master
https://developer.blender.org/rB87594726abb3090e228aef4cf3b7cfc5fef5182f

Cleanup: Improve documentation in Curves DNA header

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

M	source/blender/makesdna/DNA_curves_types.h

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

diff --git a/source/blender/makesdna/DNA_curves_types.h b/source/blender/makesdna/DNA_curves_types.h
index fea994e2739..5ecc816f4ea 100644
--- a/source/blender/makesdna/DNA_curves_types.h
+++ b/source/blender/makesdna/DNA_curves_types.h
@@ -78,17 +78,23 @@ typedef enum KnotsMode {
 
 /** Method used to calculate the normals of a curve's evaluated points. */
 typedef enum NormalMode {
+  /** Calculate normals with the smallest twist around the curve tangent across the whole curve. */
   NORMAL_MODE_MINIMUM_TWIST = 0,
+  /**
+   * Calculate normals perpendicular to the Z axis and the curve tangent. If a series of points
+   * is vertical, the X axis is used.
+   */
   NORMAL_MODE_Z_UP = 1,
 } NormalMode;
 
 /**
  * A reusable data structure for geometry consisting of many curves. All control point data is
- * stored contiguously for better efficiency. Data for each curve is stored as a slice of the
- * main #point_data array.
+ * stored contiguously for better efficiency when there are many curves. Multiple curve types are
+ * supported, as described in #CurveType. Data for each curve is accessed by slicing the main
+ * #point_data arrays.
  *
  * The data structure is meant to separate geometry data storage and processing from Blender
- * focussed ID data-block handling. The struct can also be embedded to allow reusing it.
+ * focused ID data-block handling. The struct can also be embedded to allow reusing it.
  */
 typedef struct CurvesGeometry {
   /**
@@ -120,7 +126,7 @@ typedef struct CurvesGeometry {
    */
   int point_num;
   /**
-   * The number of curves in the data-block.
+   * The number of curves.
    */
   int curve_num;
 
@@ -130,6 +136,11 @@ typedef struct CurvesGeometry {
   CurvesGeometryRuntimeHandle *runtime;
 } CurvesGeometry;
 
+/**
+ * A data-block corresponding to a number of curves of various types with various attributes.
+ * Geometry data (as opposed to pointers to other data-blocks and higher level data for user
+ * interaction) is embedded in the #CurvesGeometry struct.
+ */
 typedef struct Curves {
   ID id;
   /** Animation data (must be immediately after #id). */
@@ -151,8 +162,8 @@ typedef struct Curves {
    */
   char symmetry;
   /**
-   * #eAttrDomain. The active selection mode domain. At most one selection mode can be active
-   * at a time.
+   * #eAttrDomain. The active domain for edit/sculpt mode selection. Only one selection mode can
+   * be active at a time.
    */
   char selection_domain;
   char _pad[4];
@@ -168,7 +179,7 @@ typedef struct Curves {
 
   /**
    * The name of the attribute on the surface #Mesh used to give meaning to the UV attachment
-   * coordinates stored on each curve. Expected to be a 2D vector attribute on the face corner
+   * coordinates stored for each curve. Expected to be a 2D vector attribute on the face corner
    * domain.
    */
   char *surface_uv_map;