Cleanup: Move public docs to BKE_spline.hh header

4 files changed, 99 insertions, 93 deletions

diff --git a/source/blender/blenkernel/BKE_spline.hh b/source/blender/blenkernel/BKE_spline.hh
index 67eaa7c12c9..b8b18f0b50a 100644
--- a/source/blender/blenkernel/BKE_spline.hh
+++ b/source/blender/blenkernel/BKE_spline.hh
@@ -286,6 +286,9 @@ class BezierSpline final : public Spline {
   int resolution() const;
   void set_resolution(const int value);
 
+  /**
+   * \warning Call #reallocate on the spline's attributes after adding all points.
+   */
   void add_point(const blender::float3 position,
                  const HandleType handle_type_left,
                  const blender::float3 handle_position_left,
@@ -321,12 +324,24 @@ class BezierSpline final : public Spline {
    * uninitialized memory while auto-generating handles.
    */
   blender::MutableSpan<blender::float3> handle_positions_right(bool write_only = false);
+  /**
+   * Recalculate all #Auto and #Vector handles with positions automatically
+   * derived from the neighboring control points.
+   */
   void ensure_auto_handles() const;
 
   void translate(const blender::float3 &translation) override;
   void transform(const blender::float4x4 &matrix) override;
 
+  /**
+   * Set positions for the right handle of the control point, ensuring that
+   * aligned handles stay aligned. Has no effect for auto and vector type handles.
+   */
   void set_handle_position_right(const int index, const blender::float3 &value);
+  /**
+   * Set positions for the left handle of the control point, ensuring that
+   * aligned handles stay aligned. Has no effect for auto and vector type handles.
+   */
   void set_handle_position_left(const int index, const blender::float3 &value);
 
   bool point_is_sharp(const int index) const;
@@ -334,7 +349,22 @@ class BezierSpline final : public Spline {
   void mark_cache_invalid() final;
   int evaluated_points_size() const final;
 
+  /**
+   * Returns access to a cache of offsets into the evaluated point array for each control point.
+   * While most control point edges generate the number of edges specified by the resolution,
+   * vector segments only generate one edge.
+   *
+   * \note The length of the result is one greater than the number of points, so that the last item
+   * is the total number of evaluated points. This is useful to avoid recalculating the size of the
+   * last segment everywhere.
+   */
   blender::Span<int> control_point_offsets() const;
+  /**
+   * Returns non-owning access to an array of values containing the information necessary to
+   * interpolate values from the original control points to evaluated points. The control point
+   * index is the integer part of each value, and the factor used for interpolating to the next
+   * control point is the remaining factional part.
+   */
   blender::Span<float> evaluated_mappings() const;
   blender::Span<blender::float3> evaluated_positions() const final;
   struct InterpolationData {
@@ -346,6 +376,11 @@ class BezierSpline final : public Spline {
      */
     float factor;
   };
+  /**
+   * Convert the data encoded in #evaulated_mappings into its parts-- the information necessary
+   * to interpolate data from control points to evaluated points between them. The next control
+   * point index result will not overflow the size of the control point vectors.
+   */
   InterpolationData interpolation_data_from_index_factor(const float index_factor) const;
 
   virtual blender::fn::GVArray interpolate_to_evaluated(
@@ -354,6 +389,9 @@ class BezierSpline final : public Spline {
   void evaluate_segment(const int index,
                         const int next_index,
                         blender::MutableSpan<blender::float3> positions) const;
+  /**
+   * \warning This functional assumes that the spline has more than one point.
+   */
   bool segment_is_vector(const int start_index) const;
 
   /** See comment and diagram for #calculate_segment_insertion. */
@@ -364,6 +402,25 @@ class BezierSpline final : public Spline {
     blender::float3 right_handle;
     blender::float3 handle_next;
   };
+  /**
+   * De Casteljau Bezier subdivision.
+   * \param index: The index of the segment's start control point.
+   * \param next_index: The index of the control point at the end of the segment. Could be 0,
+   * if the spline is cyclic.
+   * \param parameter: The factor along the segment, between 0 and 1. Note that this is used
+   * directly by the calculation, it doesn't correspond to a portion of the evaluated length.
+   *
+   * <pre>
+   *           handle_prev         handle_next
+   *                x----------------x
+   *               /                  \
+   *              /      x---O---x     \
+   *             /        result        \
+   *            /                        \
+   *           O                          O
+   *       point_prev                  point_next
+   * </pre>
+   */
   InsertResult calculate_segment_insertion(const int index,
                                            const int next_index,
                                            const float parameter);
@@ -460,6 +517,9 @@ class NURBSpline final : public Spline {
   uint8_t order() const;
   void set_order(const uint8_t value);
 
+  /**
+   * \warning Call #reallocate on the spline's attributes after adding all points.
+   */
   void add_point(const blender::float3 position,
                  const float radius,
                  const float tilt,
@@ -521,6 +581,9 @@ class PolySpline final : public Spline {
 
   int size() const final;
 
+  /**
+   * \warning Call #reallocate on the spline's attributes after adding all points.
+   */
   void add_point(const blender::float3 position, const float radius, const float tilt);
 
   void resize(const int size) final;
@@ -546,8 +609,12 @@ class PolySpline final : public Spline {
 };
 
 /**
- * A #CurveEval corresponds to the #Curve object data. The name is different for clarity, since
- * more of the data is stored in the splines, but also just to be different than the name in DNA.
+ * A collection of #Spline objects with the same attribute types and names. Most data and
+ * functionality is in splines, but this contains some helpers for working with them as a group.
+ *
+ * \note A #CurveEval corresponds to the #Curve object data. The name is different for clarity,
+ * since more of the data is stored in the splines, but also just to be different than the name in
+ * DNA.
  */
 struct CurveEval {
  private:
@@ -566,9 +633,18 @@ struct CurveEval {
 
   blender::Span<SplinePtr> splines() const;
   blender::MutableSpan<SplinePtr> splines();
+  /**
+   * \return True if the curve contains a spline with the given type.
+   *
+   * \note If you are looping over all of the splines in the same scope anyway,
+   * it's better to avoid calling this function, in case there are many splines.
+   */
   bool has_spline_with_type(const Spline::Type type) const;
 
   void resize(const int size);
+  /**
+   * \warning Call #reallocate on the spline's attributes after adding all splines.
+   */
   void add_spline(SplinePtr spline);
   void remove_splines(blender::IndexMask mask);
 
@@ -576,8 +652,22 @@ struct CurveEval {
   void transform(const blender::float4x4 &matrix);
   void bounds_min_max(blender::float3 &min, blender::float3 &max, const bool use_evaluated) const;
 
+  /**
+   * Return the start indices for each of the curve spline's control points, if they were part
+   * of a flattened array. This can be used to facilitate parallelism by avoiding the need to
+   * accumulate an offset while doing more complex calculations.
+   *
+   * \note The result is one longer than the spline count; the last element is the total size.
+   */
   blender::Array<int> control_point_offsets() const;
+  /**
+   * Exactly like #control_point_offsets, but uses the number of evaluated points instead.
+   */
   blender::Array<int> evaluated_point_offsets() const;
+  /**
+   * Return the accumulated length at the start of every spline in the curve.
+   * \note The result is one longer than the spline count; the last element is the total length.
+   */
   blender::Array<float> accumulated_spline_lengths() const;
 
   float total_length() const;
@@ -585,6 +675,13 @@ struct CurveEval {
 
   void mark_cache_invalid();
 
+  /**
+   * Check the invariants that curve control point attributes should always uphold, necessary
+   * because attributes are stored on splines rather than in a flat array on the curve:
+   *  - The same set of attributes exists on every spline.
+   *  - Attributes with the same name have the same type on every spline.
+   *  - Attributes are in the same order on every spline.
+   */
   void assert_valid_point_attributes() const;
 };
 
diff --git a/source/blender/blenkernel/intern/curve_eval.cc b/source/blender/blenkernel/intern/curve_eval.cc
index 163f8b02b85..02abb097175 100644
--- a/source/blender/blenkernel/intern/curve_eval.cc
+++ b/source/blender/blenkernel/intern/curve_eval.cc
@@ -50,12 +50,6 @@ blender::MutableSpan<SplinePtr> CurveEval::splines()
   return splines_;
 }
 
-/**
- * \return True if the curve contains a spline with the given type.
- *
- * \note If you are looping over all of the splines in the same scope anyway,
- * it's better to avoid calling this function, in case there are many splines.
- */
 bool CurveEval::has_spline_with_type(const Spline::Type type) const
 {
   for (const SplinePtr &spline : this->splines()) {
@@ -72,9 +66,6 @@ void CurveEval::resize(const int size)
   attributes.reallocate(size);
 }
 
-/**
- * \warning Call #reallocate on the spline's attributes after adding all splines.
- */
 void CurveEval::add_spline(SplinePtr spline)
 {
   splines_.append(std::move(spline));
@@ -127,13 +118,6 @@ int CurveEval::total_control_point_size() const
   return count;
 }
 
-/**
- * Return the start indices for each of the curve spline's control points, if they were part
- * of a flattened array. This can be used to facilitate parallelism by avoiding the need to
- * accumulate an offset while doing more complex calculations.
- *
- * \note The result array is one longer than the spline count; the last element is the total size.
- */
 blender::Array<int> CurveEval::control_point_offsets() const
 {
   Array<int> offsets(splines_.size() + 1);
@@ -146,9 +130,6 @@ blender::Array<int> CurveEval::control_point_offsets() const
   return offsets;
 }
 
-/**
- * Exactly like #control_point_offsets, but uses the number of evaluated points instead.
- */
 blender::Array<int> CurveEval::evaluated_point_offsets() const
 {
   Array<int> offsets(splines_.size() + 1);
@@ -161,11 +142,6 @@ blender::Array<int> CurveEval::evaluated_point_offsets() const
   return offsets;
 }
 
-/**
- * Return the accumulated length at the start of every spline in the curve.
- *
- * \note The result is one longer than the spline count; the last element is the total length.
- */
 blender::Array<float> CurveEval::accumulated_spline_lengths() const
 {
   Array<float> spline_lengths(splines_.size() + 1);
@@ -361,13 +337,6 @@ std::unique_ptr<CurveEval> curve_eval_from_dna_curve(const Curve &dna_curve)
   return curve_eval_from_dna_curve(dna_curve, *BKE_curve_nurbs_get_for_read(&dna_curve));
 }
 
-/**
- * Check the invariants that curve control point attributes should always uphold, necessary
- * because attributes are stored on splines rather than in a flat array on the curve:
- *  - The same set of attributes exists on every spline.
- *  - Attributes with the same name have the same type on every spline.
- *  - Attributes are in the same order on every spline.
- */
 void CurveEval::assert_valid_point_attributes() const
 {
 #ifdef DEBUG
diff --git a/source/blender/blenkernel/intern/spline_bezier.cc b/source/blender/blenkernel/intern/spline_bezier.cc
index 0cadab998f5..4f854333c8a 100644
--- a/source/blender/blenkernel/intern/spline_bezier.cc
+++ b/source/blender/blenkernel/intern/spline_bezier.cc
@@ -70,9 +70,6 @@ void BezierSpline::set_resolution(const int value)
   this->mark_cache_invalid();
 }
 
-/**
- * \warning Call #reallocate on the spline's attributes after adding all points.
- */
 void BezierSpline::add_point(const float3 position,
                              const HandleType handle_type_left,
                              const float3 handle_position_left,
@@ -203,10 +200,6 @@ static float3 next_position(Span<float3> positions, const bool cyclic, const int
   return positions[i + 1];
 }
 
-/**
- * Recalculate all #Auto and #Vector handles with positions automatically
- * derived from the neighboring control points.
- */
 void BezierSpline::ensure_auto_handles() const
 {
   if (!auto_handles_dirty_) {
@@ -315,10 +308,6 @@ static void set_handle_position(const float3 &position,
   }
 }
 
-/**
- * Set positions for the right handle of the control point, ensuring that
- * aligned handles stay aligned. Has no effect for auto and vector type handles.
- */
 void BezierSpline::set_handle_position_right(const int index, const blender::float3 &value)
 {
   set_handle_position(positions_[index],
@@ -329,10 +318,6 @@ void BezierSpline::set_handle_position_right(const int index, const blender::flo
                       handle_positions_left_[index]);
 }
 
-/**
- * Set positions for the left handle of the control point, ensuring that
- * aligned handles stay aligned. Has no effect for auto and vector type handles.
- */
 void BezierSpline::set_handle_position_left(const int index, const blender::float3 &value)
 {
   set_handle_position(positions_[index],
@@ -349,9 +334,6 @@ bool BezierSpline::point_is_sharp(const int index) const
          ELEM(handle_types_right_[index], HandleType::Vector, HandleType::Free);
 }
 
-/**
- * \warning This functional assumes that the spline has more than one point.
- */
 bool BezierSpline::segment_is_vector(const int index) const
 {
   /* Two control points are necessary to form a segment, that should be checked by the caller. */
@@ -409,25 +391,6 @@ void BezierSpline::correct_end_tangents() const
   }
 }
 
-/**
- * De Casteljau Bezier subdivision.
- * \param index: The index of the segment's start control point.
- * \param next_index: The index of the control point at the end of the segment. Could be 0,
- * if the spline is cyclic.
- * \param parameter: The factor along the segment, between 0 and 1. Note that this is used
- * directly by the calculation, it doesn't correspond to a portion of the evaluated length.
- *
- * <pre>
- *           handle_prev         handle_next
- *                x----------------x
- *               /                  \
- *              /      x---O---x     \
- *             /        result        \
- *            /                        \
- *           O                          O
- *       point_prev                  point_next
- * </pre>
- */
 BezierSpline::InsertResult BezierSpline::calculate_segment_insertion(const int index,
                                                                      const int next_index,
                                                                      const float parameter)
@@ -493,15 +456,6 @@ void BezierSpline::evaluate_segment(const int index,
   }
 }
 
-/**
- * Returns access to a cache of offsets into the evaluated point array for each control point.
- * While most control point edges generate the number of edges specified by the resolution, vector
- * segments only generate one edge.
- *
- * \note The length of the result is one greater than the number of points, so that the last item
- * is the total number of evaluated points. This is useful to avoid recalculating the size of the
- * last segment everywhere.
- */
 Span<int> BezierSpline::control_point_offsets() const
 {
   if (!offset_cache_dirty_) {
@@ -568,12 +522,6 @@ static void calculate_mappings_linear_resolution(Span<int> offsets,
   }
 }
 
-/**
- * Returns non-owning access to an array of values containing the information necessary to
- * interpolate values from the original control points to evaluated points. The control point
- * index is the integer part of each value, and the factor used for interpolating to the next
- * control point is the remaining factional part.
- */
 Span<float> BezierSpline::evaluated_mappings() const
 {
   if (!mapping_cache_dirty_) {
@@ -659,11 +607,6 @@ Span<float3> BezierSpline::evaluated_positions() const
   return positions;
 }
 
-/**
- * Convert the data encoded in #evaulated_mappings into its parts-- the information necessary
- * to interpolate data from control points to evaluated points between them. The next control
- * point index result will not overflow the size of the control point vectors.
- */
 BezierSpline::InterpolationData BezierSpline::interpolation_data_from_index_factor(
     const float index_factor) const
 {
diff --git a/source/blender/blenkernel/intern/spline_poly.cc b/source/blender/blenkernel/intern/spline_poly.cc
index d495c977285..b5aca0357be 100644
--- a/source/blender/blenkernel/intern/spline_poly.cc
+++ b/source/blender/blenkernel/intern/spline_poly.cc
@@ -45,9 +45,6 @@ int PolySpline::size() const
   return size;
 }
 
-/**
- * \warning Call #reallocate on the spline's attributes after adding all points.
- */
 void PolySpline::add_point(const float3 position, const float radius, const float tilt)
 {
   positions_.append(position);