cedric pushed a commit to branch master.

http://git.enlightenment.org/core/efl.git/commit/?id=274730fc5f7e9e8995554ca02dfe8abd8b45211e

commit 274730fc5f7e9e8995554ca02dfe8abd8b45211e
Author: Bryce Harrington <br...@osg.samsung.com>
Date:   Wed Feb 14 12:00:44 2018 -0800

    eina: improve documentation for eina_bezier.
    
    Summary:
    Adds missing @param docs and fixes an incorrectly documented one.
    Clarifies difference between 'length' and 'position', specifying the
    latter is a number between 0.0 and 1.0.  Improves verbage here and there
    for grammatical correctness and internal consistency.
    
    Subscribers: cedric
    
    Differential Revision: https://phab.enlightenment.org/D5780
    
    Signed-off-by: Cedric Bail <ced...@osg.samsung.com>
---
 src/lib/eina/eina_bezier.c | 10 ++++----
 src/lib/eina/eina_bezier.h | 64 ++++++++++++++++++++++++----------------------
 2 files changed, 39 insertions(+), 35 deletions(-)

diff --git a/src/lib/eina/eina_bezier.c b/src/lib/eina/eina_bezier.c
index b179ceb59e..aade9af4cb 100644
--- a/src/lib/eina/eina_bezier.c
+++ b/src/lib/eina/eina_bezier.c
@@ -40,9 +40,9 @@ _eina_bezier_1st_derivative(const Eina_Bezier *bz,
    *py = 3 * ( a * bz->start.y + b * bz->ctrl_start.y + c * bz->ctrl_end.y + d 
* bz->end.y);
 }
 
-// approximate sqrt(x*x + y*y) using alpha max plus beta min algorithm.
-// With alpha = 1, beta = 3/8, giving results with a largest error less
-// than 7% compared to the exact value.
+// Approximate sqrt(x*x + y*y) using the alpha max plus beta min algorithm.
+// This uses alpha = 1, beta = 3/8, which results in a maximum error of less
+// than 7% compared to the correct value.
 static double
 _line_length(double x1, double y1, double x2, double y2)
 {
@@ -96,9 +96,9 @@ _eina_bezier_length_helper(const Eina_Bezier *b)
    chord = _line_length(b->start.x, b->start.y, b->end.x, b->end.y);
 
    if (fabsf(len - chord) > FLT_MIN) {
-      _eina_bezier_split(b, &left, &right);       /* split in two */
+      _eina_bezier_split(b, &left, &right); /* split in two */
       length =
-        _eina_bezier_length_helper(&left) +  /* try left side */
+        _eina_bezier_length_helper(&left) + /* try left side */
         _eina_bezier_length_helper(&right); /* try right side */
 
       return length;
diff --git a/src/lib/eina/eina_bezier.h b/src/lib/eina/eina_bezier.h
index ab9b8e1b8f..f883fa02ac 100644
--- a/src/lib/eina/eina_bezier.h
+++ b/src/lib/eina/eina_bezier.h
@@ -52,14 +52,14 @@ struct _Eina_Bezier
  * point cubic bezier curve.
  *
  * @param b The floating point bezier.
- * @param start_x x coordinate of start point.
- * @param start_y y coordinate of start point.
- * @param ctrl_start_x x coordinate of 1st control point.
- * @param ctrl_start_y y coordinate of 1st control point.
- * @param ctrl_end_x x coordinate of 2nd control point.
- * @param ctrl_end_y y coordinate of 2nd control point.
- * @param end_x x coordinate of end point.
- * @param end_y y coordinate of end point.
+ * @param start_x The x coordinate of the start point.
+ * @param start_y The y coordinate of the start point.
+ * @param ctrl_start_x The x coordinate of the 1st control point.
+ * @param ctrl_start_y The y coordinate of the 1st control point.
+ * @param ctrl_end_x The X coordinate of the 2nd control point.
+ * @param ctrl_end_y The Y coordinate of the 2nd control point.
+ * @param end_x The X coordinate of the end point.
+ * @param end_y The Y coordinate of the end point.
  *
  * @p b. No check is done on @p b.
  * @since 1.16
@@ -86,8 +86,8 @@ EAPI void eina_bezier_values_set(Eina_Bezier *b, double 
start_x, double start_y,
 EAPI void eina_bezier_values_get(const Eina_Bezier *b, double *start_x, double 
*start_y, double *ctrl_start_x, double *ctrl_start_y, double *ctrl_end_x, 
double *ctrl_end_y, double *end_x, double *end_y) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Returns the length of the given floating
- * point cubic bezier curve.
+ * @brief Calculates the length of the given floating point cubic bezier
+ * curve.
  *
  * @param b The floating point bezier.
  *
@@ -97,11 +97,13 @@ EAPI void eina_bezier_values_get(const Eina_Bezier *b, 
double *start_x, double *
 EAPI double eina_bezier_length_get(const Eina_Bezier *b) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Returns the position of the given bezier
- * at given length.
+ * @brief Returns the relative position on a bezier at a given length.
  *
  * @param b The floating point bezier.
- * @param len The given length.
+ * @param len The length along the bezier curve.
+ *
+ * Calculates the proportional location on @p b as a number from
+ * 0.0 to 1.0 that corresponds to a distance @p len along it.
  *
  * @p b. No check is done on @p b.
  * @since 1.16
@@ -109,11 +111,12 @@ EAPI double eina_bezier_length_get(const Eina_Bezier *b) 
EINA_ARG_NONNULL(1);
 EAPI double eina_bezier_t_at(const Eina_Bezier *b, double len) 
EINA_ARG_NONNULL(1);
 
 /**
- * @brief Gets the point on the bezier curve at
- * position t.
+ * @brief Gets the point on the bezier curve at position t.
  *
  * @param b The floating point bezier.
- * @param t The floating point position.
+ * @param t The floating point position between 0.0 and 1.0.
+ * @param[out] px The corresponding point's X coordinate.
+ * @param[out] py The corresponding point's Y coordinate.
  *
  * @p b. No check is done on @p b.
  * @since 1.16
@@ -121,11 +124,10 @@ EAPI double eina_bezier_t_at(const Eina_Bezier *b, double 
len) EINA_ARG_NONNULL(
 EAPI void eina_bezier_point_at(const Eina_Bezier *b, double t, double *px, 
double *py) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Returns the slope  of the  bezier
- * at given length.
+ * @brief Determines the slope of the bezier at a given position.
  *
  * @param b The floating point bezier.
- * @param len The given length.
+ * @param t The position along the bezier between 0.0 and 1.0.
  *
  * @p b. No check is done on @p b.
  * @since 1.16
@@ -133,10 +135,12 @@ EAPI void eina_bezier_point_at(const Eina_Bezier *b, 
double t, double *px, doubl
 EAPI double eina_bezier_angle_at(const Eina_Bezier *b, double t) 
EINA_ARG_NONNULL(1);
 
 /**
- * @brief Splits the bezier at given length.
+ * @brief Splits the bezier at a given length.
  *
  * @param b The floating point bezier.
- * @param len The given length.
+ * @param len The length along the bezier to make the split.
+ * @param[out] left The resultant split's left portion of the bezier.
+ * @param[out] right The resultant split's right portion of the bezier.
  *
  * @p b. No check is done on @p b.
  * @since 1.16
@@ -144,13 +148,13 @@ EAPI double eina_bezier_angle_at(const Eina_Bezier *b, 
double t) EINA_ARG_NONNUL
 EAPI void eina_bezier_split_at_length(const Eina_Bezier *b, double len, 
Eina_Bezier *left, Eina_Bezier *right) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Gets the bounds of the bezier.
+ * @brief Calculates and returns the bounding box for the bezier.
  *
  * @param b The floating point bezier.
- * @param x x coordinate of bounding box.
- * @param y y coordinate of bounding box.
- * @param w width of bounding box.
- * @param h height of bounding box.
+ * @param x The X coordinate of the bounding box.
+ * @param y The Y coordinate of the bounding box.
+ * @param w The width of the bounding box.
+ * @param h The height of the bounding box.
  *
  * @p b. No check is done on @p b.
  * @since 1.17
@@ -158,12 +162,12 @@ EAPI void eina_bezier_split_at_length(const Eina_Bezier 
*b, double len, Eina_Bez
 EAPI void eina_bezier_bounds_get(const Eina_Bezier *b, double *x, double *y, 
double *w, double *h) EINA_ARG_NONNULL(1);
 
 /**
- * @brief Finds the bezier at the given interval.
+ * @brief Finds the bezier between the given interval.
  *
  * @param b The floating point bezier.
- * @param t0 The start interval.
- * @param t1 The end interval.
- * @param result The result bezier.
+ * @param t0 The start of the interval.
+ * @param t1 The end of the interval.
+ * @param result The resulting bezier.
  *
  * @p b. No check is done on @p b.
  * @since 1.17

-- 


Reply via email to