[Bf-blender-cvs] [845a3573f54] master: Cleanup: Improve curves comments

[Hans Goudey]

Commit: 845a3573f546bde930c5110712086f7f795e1c55
Author: Hans Goudey
Date:   Wed Nov 16 17:54:51 2022 -0600
Branches: master
https://developer.blender.org/rB845a3573f546bde930c5110712086f7f795e1c55

Cleanup: Improve curves comments

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

M	source/blender/blenkernel/BKE_curves.hh
M	source/blender/makesdna/DNA_curves_types.h

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

diff --git a/source/blender/blenkernel/BKE_curves.hh b/source/blender/blenkernel/BKE_curves.hh
index 50543092aef..9382a912c02 100644
--- a/source/blender/blenkernel/BKE_curves.hh
+++ b/source/blender/blenkernel/BKE_curves.hh
@@ -65,9 +65,7 @@ struct BasisCache {
 }  // namespace curves::nurbs
 
 /**
- * Contains derived data, caches, and other information not saved in files, besides a few pointers
- * to arrays that are kept in the non-runtime struct to avoid dereferencing this whenever they are
- * accessed.
+ * Contains derived data, caches, and other information not saved in files.
  */
 class CurvesGeometryRuntime {
  public:
diff --git a/source/blender/makesdna/DNA_curves_types.h b/source/blender/makesdna/DNA_curves_types.h
index 6c38d316508..a72a9bf4c68 100644
--- a/source/blender/makesdna/DNA_curves_types.h
+++ b/source/blender/makesdna/DNA_curves_types.h
@@ -25,9 +25,33 @@ typedef struct CurvesGeometryRuntimeHandle CurvesGeometryRuntimeHandle;
 #endif
 
 typedef enum CurveType {
+  /**
+   * Catmull Rom curves provide automatic smoothness, like Bezier curves with automatic handle
+   * positions. This is the default type for the hair system because of the simplicity of
+   * interaction and data storage.
+   */
   CURVE_TYPE_CATMULL_ROM = 0,
+  /**
+   * Poly curves (often called "polylines") have no interpolation at all. They evaluate to the same
+   * set of points as the original control points. They are a good choice for high-resolution
+   * data-sets or when constrained by performance.
+   */
   CURVE_TYPE_POLY = 1,
+  /**
+   * Bezier curves provide a common intuitive control system made up of handles and control points.
+   * Handles are stored separately from positions, and do not store extra generic attribute values.
+   * Bezier curves also give the flexibility to set handle types (see #HandleType) that influence
+   * the number of evaluated points in each segment.
+   */
   CURVE_TYPE_BEZIER = 2,
+  /**
+   * NURBS curves offer the most flexibility at the cost of increased complexity. Given the choice
+   * of different knot modes (see #KnotsMode) and different orders (see "nurbs_order" attribute),
+   * any of the other types can theoretically be created with a NURBS curve.
+   *
+   * Note that Blender currently does not support custom knot vectors, though that should be
+   * supported in the long term.
+   */
   CURVE_TYPE_NURBS = 3,
 } CurveType;
 /* The number of supported curve types. */
@@ -63,8 +87,8 @@ typedef enum NormalMode {
  * stored contiguously for better efficiency. Data for each curve is stored as a slice of the
  * main #point_data array.
  *
- * The data structure is meant to be embedded in other data-blocks to allow reusing
- * curve-processing algorithms for multiple Blender data-block types.
+ * 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.
  */
 typedef struct CurvesGeometry {
   /**
@@ -108,9 +132,10 @@ typedef struct CurvesGeometry {
 
 typedef struct Curves {
   ID id;
-  /* Animation data (must be immediately after id). */
+  /** Animation data (must be immediately after #id). */
   struct AnimData *adt;
 
+  /** Geometry data. */
   CurvesGeometry geometry;
 
   int flag;
@@ -148,7 +173,7 @@ typedef struct Curves {
    */
   char *surface_uv_map;
 
-  /* Draw Cache. */
+  /* Draw cache to store data used for viewport drawing. */
   void *batch_cache;
 } Curves;