font-edit: Improve the type descriptions (#29)

Currently, there is a lack of description for geometric types and
functions.

pt_t is used to describe a geometric object—a point, while pts_t is
used to describe a dynamically configurable array. n is used to
describe the current number of configured points, and s is used to
describe the maximum configurable memory limit, measured in bytes.

spline_t is used to describe cubic spline interpolation based on four
points.

new_pts, dispose_pts, and add_pt are methods for the pt_t and pts_t
types.

distance_to_point, distance_to_line, and distance_to_segment are used to
describe the distance relationships between geometric objects.

lerp is a function for computing linear interpolation points.

fit is used to compute a spline with a specific error tolerance.

Author: jouae

tools/font-edit/twin-fedit.c

@@ -105,7 +105,7 @@ static cmd_t *insert_cmd(cmd_t **prev)
 {
     cmd_t *n = malloc(sizeof(cmd_t));
 
-    n->op = OpNoop;
+    n->op = op_noop;
     n->next = *prev;
     *prev = n;
     return n;
@@ -187,17 +187,17 @@ static char_t *read_char(void)
         switch (line[5]) {
         case 'm':
             cmd = append_cmd(c);
-            cmd->op = OpMove;
+            cmd->op = op_move;
             sscanf(line + 8, "%lf, %lf", &cmd->pt[0].x, &cmd->pt[0].y);
             break;
         case 'l':
             cmd = append_cmd(c);
-            cmd->op = OpLine;
+            cmd->op = op_line;
             sscanf(line + 8, "%lf, %lf", &cmd->pt[0].x, &cmd->pt[0].y);
             break;
         case 'c':
             cmd = append_cmd(c);
-            cmd->op = OpCurve;
+            cmd->op = op_curve;
             sscanf(line + 8, "%lf, %lf, %lf, %lf, %lf, %lf", &cmd->pt[0].x,
                    &cmd->pt[0].y, &cmd->pt[1].x, &cmd->pt[1].y, &cmd->pt[2].x,
                    &cmd->pt[2].y);
@@ -257,13 +257,13 @@ static void draw_char(char_t *c)
             alpha = 0.5;
 
         switch (cmd->op) {
-        case OpMove:
+        case op_move:
             dot(cr, cmd->pt[0].x, cmd->pt[0].y, 1, 1, 0, alpha);
             break;
-        case OpLine:
+        case op_line:
             dot(cr, cmd->pt[0].x, cmd->pt[0].y, 1, 0, 0, alpha);
             break;
-        case OpCurve:
+        case op_curve:
             dot(cr, cmd->pt[0].x, cmd->pt[0].y, 0, 0, 1, alpha);
             dot(cr, cmd->pt[1].x, cmd->pt[1].y, 0, 0, 1, alpha);
             dot(cr, cmd->pt[2].x, cmd->pt[2].y, 0, 1, 0, alpha);
@@ -280,13 +280,13 @@ static void draw_char(char_t *c)
             double alpha = 1;
 
             switch (cmd->op) {
-            case OpMove:
+            case op_move:
                 spot(cr, cmd->pt[0].x, cmd->pt[0].y, 1, 1, 0, alpha);
                 break;
-            case OpLine:
+            case op_line:
                 spot(cr, cmd->pt[0].x, cmd->pt[0].y, 1, 0, 0, alpha);
                 break;
-            case OpCurve:
+            case op_curve:
                 spot(cr, cmd->pt[0].x, cmd->pt[0].y, 0, 0, 1, alpha);
                 spot(cr, cmd->pt[1].x, cmd->pt[1].y, 0, 0, 1, alpha);
                 spot(cr, cmd->pt[2].x, cmd->pt[2].y, 0, 1, 0, alpha);
@@ -301,13 +301,13 @@ static void draw_char(char_t *c)
 
     for (cmd = c->cmd; cmd; cmd = cmd->next) {
         switch (cmd->op) {
-        case OpMove:
+        case op_move:
             cairo_move_to(cr, cmd->pt[0].x, cmd->pt[0].y);
             break;
-        case OpLine:
+        case op_line:
             cairo_line_to(cr, cmd->pt[0].x, cmd->pt[0].y);
             break;
-        case OpCurve:
+        case op_curve:
             cairo_curve_to(cr, cmd->pt[0].x, cmd->pt[0].y, cmd->pt[1].x,
                            cmd->pt[1].y, cmd->pt[2].x, cmd->pt[2].y);
             break;
@@ -321,7 +321,7 @@ static void draw_char(char_t *c)
         double tx, ty;
         char buf[10];
 
-        if (cmd->op == OpCurve) {
+        if (cmd->op == op_curve) {
             tx = cmd->pt[2].x;
             ty = cmd->pt[2].y;
         } else {
@@ -359,7 +359,7 @@ static cmd_t *pos_to_cmd(char_t *c, cmd_t *start, int ix, int iy)
 
     cmd = start;
     while (cmd) {
-        int i = cmd->op == OpCurve ? 2 : 0;
+        int i = cmd->op == op_curve ? 2 : 0;
         double dx = cmd->pt[i].x - x;
         double dy = cmd->pt[i].y - y;
         double err = sqrt(dx * dx + dy * dy);
@@ -404,7 +404,7 @@ static void replace_with_spline(char_t *c, cmd_t *first, cmd_t *last)
 
     order(&first, &last);
     for (cmd = first; cmd != last->next; cmd = cmd->next) {
-        int i = cmd->op == OpCurve ? 2 : 0;
+        int i = cmd->op == op_curve ? 2 : 0;
         add_pt(pts, &cmd->pt[i]);
     }
 
@@ -421,7 +421,7 @@ static void replace_with_spline(char_t *c, cmd_t *first, cmd_t *last)
 
     cmd = insert_cmd(&first->next);
 
-    cmd->op = OpCurve;
+    cmd->op = op_curve;
     cmd->pt[0] = s.b;
     cmd->pt[1] = s.c;
     cmd->pt[2] = s.d;
@@ -436,12 +436,12 @@ static void split(char_t *c, cmd_t *first, cmd_t *last)
 
     push(c);
     cmd = insert_cmd(&first->next);
-    cmd->op = OpLine;
+    cmd->op = op_line;
     cmd->pt[0] = lerp(&first->pt[0], &last->pt[0]);
-    if (last->op == OpMove) {
+    if (last->op == op_move) {
         cmd_t *extra = insert_cmd(&last->next);
 
-        extra->op = OpLine;
+        extra->op = op_line;
         extra->pt[0] = last->pt[0];
         last->pt[0] = cmd->pt[0];
     }
@@ -533,9 +533,9 @@ static void play(char_t *c)
                 }
             } else {
                 cmd_t *spline;
-                if (c->first && c->first->op == OpCurve)
+                if (c->first && c->first->op == op_curve)
                     spline = c->first;
-                else if (c->last && c->last->op == OpCurve)
+                else if (c->last && c->last->op == op_curve)
                     spline = c->last;
                 else
                     spline = 0;
@@ -586,15 +586,15 @@ static void write_char(char_t *c)
 
     for (cmd = c->cmd; cmd; cmd = cmd->next) {
         switch (cmd->op) {
-        case OpMove:
+        case op_move:
             printf("    'm', %g, %g,\n", cmd->pt[0].x, cmd->pt[0].y);
             offset += 3;
             break;
-        case OpLine:
+        case op_line:
             printf("    'l', %g, %g,\n", cmd->pt[0].x, cmd->pt[0].y);
             offset += 3;
             break;
-        case OpCurve:
+        case op_curve:
             printf("    'c', %g, %g, %g, %g, %g, %g,\n", cmd->pt[0].x,
                    cmd->pt[0].y, cmd->pt[1].x, cmd->pt[1].y, cmd->pt[2].x,
                    cmd->pt[2].y);

tools/font-edit/twin-fedit.h

@@ -35,12 +35,44 @@
 #include <string.h>
 #include <unistd.h>
 
-typedef enum _op { OpMove, OpLine, OpCurve, OpNoop } op_t;
+/* Geometric types */
 
-typedef struct {
+/*
+ * pt_t - Point in a 2-D coordinate system
+ * @x: x-component
+ * @y: y-component
+ */
+typedef struct _pt {
     double x, y;
 } pt_t;
 
+/*
+ * pts_t - Points in a 2-D coordinate system
+ * @n: numeber of the stored points
+ * @s: size of the storage
+ * @pt: pointer of pt_ts
+ */
+typedef struct _pts {
+    int n;
+    int s;
+    pt_t *pt;
+} pts_t;
+
+/*
+ * spline_t - Cubic spline type
+ * @a: starting point.
+ * @b: first control point.
+ * @c: last control point.
+ * @d: ending point.
+ */
+typedef struct _spline {
+    pt_t a, b, c, d;
+} spline_t;
+
+/* Command line tpyes */
+
+typedef enum { op_move, op_line, op_curve, op_noop } op_t;
+
 typedef struct _cmd {
     struct _cmd *next;
     op_t op;
@@ -59,30 +91,74 @@ typedef struct _char {
     cmd_t *last;
 } char_t;
 
-typedef struct _pts_t {
-    int n;
-    int s;
-    pt_t *pt;
-} pts_t;
-
-typedef struct _spline {
-    pt_t a, b, c, d;
-} spline_t;
-
-spline_t fit(pt_t *p, int n);
+/* Geometric functions */
 
+/*
+ * new_pts() - Allocate and initialize a new point
+ *
+ * Return: pts_t type, allocated point.
+ */
 pts_t *new_pts(void);
 
+/*
+ * dispose_pts() - Free all storage used by pts_t
+ * @pts: the points to be free
+ */
 void dispose_pts(pts_t *pts);
 
+/*
+ * add_pt() - Add a point to pts_t
+ * @pts: the object that receives the added points
+ * @pt: the point to be added
+ */
 void add_pt(pts_t *pts, pt_t *pt);
 
+/*
+ * distance_to_point() - Calculate distance between two points
+ * @a: point in 2-D coordinate
+ * @b: point in 2-D coordinate
+ *
+ * Return: double type, the distance between point a and point b.
+ */
 double distance_to_point(pt_t *a, pt_t *b);
 
+/*
+ * distance_to_line() - Calculate distance from a point to a line
+ * @p: point outside the line
+ * @p1: one of the points used to calculate the line
+ * @p2: one of the points used to calculate the line
+ *
+ * Return: double type, the distance from point p to the line.
+ */
 double distance_to_line(pt_t *p, pt_t *p1, pt_t *p2);
 
+/*
+ * distance_to_segment() - Calculate shortest distance from a point
+ *                         to a line segment
+ * @p: point outside the line segment
+ * @p1: one of the points used to calculate the line segment
+ * @p2: one of the points used to calculate the line segment
+ *
+ * Return: double type, the distance from point p to the line segment.
+ */
 double distance_to_segment(pt_t *p, pt_t *p1, pt_t *p2);
 
+/*
+ * lerp() - Interpolate linearly a point between two points
+ * @a: one of the point to be interpolated
+ * @b: one of the point to be interpolated
+ *
+ * Return: pt_t type, a interpolation point by two points.
+ */
 pt_t lerp(pt_t *a, pt_t *b);
 
+/*
+ * fit() - Fit a spline within a specified tolerance
+ * @a: points
+ * @n: number of points
+ *
+ * Return: spline_t type, a cubic spline of points.
+ */
+spline_t fit(pt_t *p, int n);
+
 #endif /* _TWIN_FEDIT_H_ */