Add simple documentation in comments, refactor.

Change all `unsigned int` and `unsigned long` types to `size_t`.
Fix names alignment in headers.

Add documentation and simple description:
Painter - painter.h
Main - tetris.c
Unicode - unicode.h
IDList - idlist.h
Engine - engine.c

Minor changes:
tetris.c - fix indentation and code blocks separation with newlines,
remove unused includes.
idlist.h - fix structure field name alignment.
field.h, engine.c - define aliases for ghost and active shapes indexes
in the field.
engine.c - rename menuTick to snake case, fix curly braces style of
functions.
Makefile - switch SFML deprecated warnings off.

7 files changed, 100 insertions, 73 deletions

diff --git a/src/engine.c b/src/engine.c
index 482c6df..46507c1 100644
--- a/src/engine.c
+++ b/src/engine.c
@@ -1,3 +1,22 @@
+/*
+ * engine.c
+ *
+ * Engine module - business logic. A couple of functions are exposed to use in
+ * the main tetris module (tetris.c), see engine.h.
+ *
+ * The game has simple state machine:
+ *
+ * Menu --[start]-> Started --[pause]-> Paused
+ *   ^                |  ^                |
+ *   +---[gameover]---+  +---[unpause]----+
+ *
+ * Transitions between states are implemented in a distinct functions. Each
+ * transition function name starts with "transition_". State functions has names
+ * with suffix "_loop" except for "main_loop" function - it is just an
+ * aggregator of state functions.
+ *
+ * */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -66,10 +85,10 @@ int rmlines_score[] = {
 };
 
 /* Externs from main.c */
-extern struct game    game;
-extern struct field   fld, nxt;
-extern struct idlist *texts;
-char                  arrKeys = 0;
+extern struct game      game;
+extern struct field     fld, nxt;
+extern struct idlist   *texts;
+char                    arrKeys = 0;
 
 static void render_score_value(void *obj)
 {
@@ -91,13 +110,13 @@ static void render_level_value(void *obj)
         if (!text->text)
             text->text = calloc(BUFSIZ, sizeof(char));
         char *a = calloc(BUFSIZ, sizeof(char));
-        sprintf(a, "%d", game.level);
+        sprintf(a, "%ld", game.level);
         utf8to32_strcpy(text->text, a);
         free(a);
     }
 }
 
-static int get_level_latency(unsigned int level)
+static int get_level_latency(size_t level)
 {
     if (level > 29)
         return level_move_latency[29];
@@ -181,8 +200,8 @@ static void transition_game_over()
     nxt.attr |= FLD_ATTR_INVISIBLE;
     painter_update_field(nxt.id, &nxt);
 
-    fld.shape[0].y = fld.size.y;
-    fld.shape[1].y = fld.size.y;
+    fld.shape[GHOST_SHAPE_INDEX].y = fld.size.y;
+    fld.shape[ACTIVE_SHAPE_INDEX].y = fld.size.y;
     field_fill_random(&fld);
     painter_update_field(fld.id, &fld);
 
@@ -192,13 +211,13 @@ static void transition_game_over()
     list_foreach(texts, update_game_text);
 }
 
-static void project_ghost_shape(struct field *fld, unsigned int idreal, unsigned int idghost)
+static void project_ghost_shape(struct field *fld, size_t idreal, size_t idghost)
 {
     fld->shape[idghost].t = fld->shape[idreal].t;
     fld->shape[idghost].x = fld->shape[idreal].x;
     fld->shape[idghost].y = fld->shape[idreal].y;
-    for (unsigned int j = 0; j < 4; j++)
-        for (unsigned int i = 0; i < 4; i++)
+    for (size_t j = 0; j < 4; j++)
+        for (size_t i = 0; i < 4; i++)
             fld->shape[idghost].c[j][i] = fld->shape[idreal].c[j][i];
     do {
         --fld->shape[idghost].y;
@@ -208,14 +227,14 @@ static void project_ghost_shape(struct field *fld, unsigned int idreal, unsigned
 
 static void transition_put_shape()
 {
-    field_put_shape(&fld, &fld.shape[1]);
+    field_put_shape(&fld, &fld.shape[ACTIVE_SHAPE_INDEX]);
     int removedLines = field_rm_lines(&fld);
     game.lines += removedLines;
     game.scoreCurrent += rmlines_score[removedLines] * game.level;
-    fld.shape[1].t = nxt.shape[0].t;
+    fld.shape[ACTIVE_SHAPE_INDEX].t = nxt.shape[0].t;
     field_reset_walking_shape(&fld, 1);
     project_ghost_shape(&fld, 1, 0);
-    for (unsigned int s = 0; s < nxt.shape_cnt - 1; ++s) {
+    for (size_t s = 0; s < nxt.shape_cnt - 1; ++s) {
         nxt.shape[s] = nxt.shape[s + 1];
         nxt.shape[s].y = 4 - s * 3;
     }
@@ -252,7 +271,7 @@ static void game_tick()
         sfClock_restart(game.putTick);
     }
     if (sfClock_getElapsedTime(game.putTick).microseconds >= PUT_LATENCY) {
-        if (field_shape_out_of_bounds(&fld, &fld.shape[1]))
+        if (field_shape_out_of_bounds(&fld, &fld.shape[ACTIVE_SHAPE_INDEX]))
             transition_game_over();
         else
             transition_put_shape();
@@ -276,7 +295,7 @@ static void signal_harddrop()
 {
     while (field_move_shape_down(&fld, 1))
         game.scoreCurrent++;
-    if (field_shape_out_of_bounds(&fld, &fld.shape[1]))
+    if (field_shape_out_of_bounds(&fld, &fld.shape[ACTIVE_SHAPE_INDEX]))
         transition_game_over();
     else
         transition_put_shape();
@@ -418,7 +437,7 @@ static void pause_keys()
     }
 }
 
-static void menuTick()
+static void menu_tick()
 {
     sfClock_restart(game.mTick);
     field_fill_random(&fld);
@@ -438,11 +457,11 @@ static void transition_game_start()
     game.started = 1;
     game.paused = 0;
     field_clear(&fld);
-    shape_gen_random(&fld.shape[1]);
+    shape_gen_random(&fld.shape[ACTIVE_SHAPE_INDEX]);
     field_reset_walking_shape(&fld, 1);
     project_ghost_shape(&fld, 1, 0);
-    shape_load(&fld.shape[1]);
-    for (unsigned int i = 0; i < nxt.shape_cnt; ++i)
+    shape_load(&fld.shape[ACTIVE_SHAPE_INDEX]);
+    for (size_t i = 0; i < nxt.shape_cnt; ++i)
         shape_gen_random(&nxt.shape[i]);
     nxt.attr &= ~FLD_ATTR_INVISIBLE;
     list_foreach(texts, hide_menu_text);
@@ -455,14 +474,16 @@ static void transition_game_start()
     sfClock_restart(game.gameTick);
 }
 
-static void menu_loop() {
+static void menu_loop()
+{
     if (sfClock_getElapsedTime(game.mTick).microseconds >= basicLatency)
-        menuTick();
+        menu_tick();
     if (sfKeyboard_isKeyPressed(sfKeyS) == 1)
         transition_game_start();
 }
 
-static void game_loop() {
+static void game_loop()
+{
     game_keys();
     if (sfClock_getElapsedTime(game.gameTick).microseconds >= game.moveLatency)
         game_tick();
@@ -473,7 +494,8 @@ static void game_loop() {
     painter_update_field(nxt.id, &nxt);
 }
 
-static void pause_loop() {
+static void pause_loop()
+{
     pause_keys();
 }
 
diff --git a/src/field.c b/src/field.c
index ebe61d5..9be2954 100644
--- a/src/field.c
+++ b/src/field.c
@@ -21,9 +21,9 @@ static int out_of_bounds(struct field *fld, struct shape *active);
 void field_init(struct field *fld)
 {
     fld->c = calloc(fld->bound.y, sizeof(struct cell *));
-    for (unsigned int j = 0; j < fld->bound.y; j++) {
+    for (size_t j = 0; j < fld->bound.y; j++) {
         fld->c[j] = calloc(fld->bound.x, sizeof(struct cell));
-        for (unsigned int i = 0; i < fld->size.x; i++)
+        for (size_t i = 0; i < fld->size.x; i++)
             fld->c[j][i].a = 0;
     }
     fld->shape = calloc(fld->shape_cnt, sizeof(struct shape));
@@ -38,8 +38,8 @@ void field_deinit(struct field *fld) {
 
 void field_clear(struct field *fld)
 {
-    for (unsigned int j = 0; j < fld->bound.y; j++)
-        for (unsigned int i = 0; i < fld->bound.x; i++) {
+    for (size_t j = 0; j < fld->bound.y; j++)
+        for (size_t i = 0; i < fld->bound.x; i++) {
             fld->c[j][i].a = 0;
             fld->c[j][i].color = 0;
         }
@@ -47,8 +47,8 @@ void field_clear(struct field *fld)
 
 void field_fill_random(struct field *fld)
 {
-    for (unsigned int j = 0; j < fld->size.y; j++)
-        for (unsigned int i = 0; i < fld->size.x; i++) {
+    for (size_t j = 0; j < fld->size.y; j++)
+        for (size_t i = 0; i < fld->size.x; i++) {
             fld->c[j][i].a = 1;
             fld->c[j][i].color = rand() % 7 + 1;
         }
@@ -100,7 +100,7 @@ void shape_load(struct shape *shape)
     }
 }
 
-void field_reset_walking_shape(struct field *fld, unsigned int index)
+void field_reset_walking_shape(struct field *fld, size_t index)
 {
     struct shape *shape = &fld->shape[index];
     shape_load(shape);
@@ -221,7 +221,7 @@ static int wall_kick(struct field *fld, struct shape *shape)
     return 0;
 }
 
-void field_rotate_shape_clockwise(struct field *fld, unsigned int index)
+void field_rotate_shape_clockwise(struct field *fld, size_t index)
 {
     struct shape *shape = &fld->shape[index];
     rotate_shape_right(shape);
@@ -230,7 +230,7 @@ void field_rotate_shape_clockwise(struct field *fld, unsigned int index)
             rotate_shape_left(shape);
 }
 
-int field_move_shape_down(struct field *fld, unsigned int index)
+int field_move_shape_down(struct field *fld, size_t index)
 {
     fld->shape[index].y--;
     if (field_shape_collision(fld, &fld->shape[index])) {
@@ -240,7 +240,7 @@ int field_move_shape_down(struct field *fld, unsigned int index)
     return -1;
 }
 
-int field_move_shape_left(struct field *fld, unsigned int index)
+int field_move_shape_left(struct field *fld, size_t index)
 {
     fld->shape[index].x--;
     if (field_shape_collision(fld, &fld->shape[index])) {
@@ -250,7 +250,7 @@ int field_move_shape_left(struct field *fld, unsigned int index)
     return -1;
 }
 
-int field_move_shape_right(struct field *fld, unsigned int index)
+int field_move_shape_right(struct field *fld, size_t index)
 {
     fld->shape[index].x++;
     if (field_shape_collision(fld, &fld->shape[index])) {
@@ -262,16 +262,16 @@ int field_move_shape_right(struct field *fld, unsigned int index)
 
 int field_rm_lines(struct field *fld)
 {
-    unsigned int lines = 0;
-    for (unsigned int j = 0; j < fld->bound.y; j++) {
-        unsigned int cells = 0;
-        for (unsigned int i = 0; i < fld->bound.x; i++)
+    size_t lines = 0;
+    for (size_t j = 0; j < fld->bound.y; j++) {
+        size_t cells = 0;
+        for (size_t i = 0; i < fld->bound.x; i++)
             if (fld->c[j][i].a)
                 ++cells;
         if (cells == fld->bound.x) {
             ++lines;
-            for (unsigned int n = j; n < fld->bound.y - 1; n++)
-                for (unsigned int m = 0; m < fld->bound.x; m++) {
+            for (size_t n = j; n < fld->bound.y - 1; n++)
+                for (size_t m = 0; m < fld->bound.x; m++) {
                     fld->c[n][m].a = fld->c[n + 1][m].a;
                     fld->c[n][m].color = fld->c[n + 1][m].color;
                 }
diff --git a/src/idlist.c b/src/idlist.c
index b9d551a..14db85f 100644
--- a/src/idlist.c
+++ b/src/idlist.c
@@ -21,7 +21,7 @@ struct idlist *list_append(struct idlist *list)
     return last->next;
 }
 
-struct idlist *list_get(const struct idlist *list, unsigned long id)
+struct idlist *list_get(const struct idlist *list, size_t id)
 {
     const struct idlist *sought = list;
     if (sought) {
diff --git a/src/painter.c b/src/painter.c
index 9dabeb8..dea9b69 100644
--- a/src/painter.c
+++ b/src/painter.c
@@ -39,14 +39,14 @@ struct field_drawable {
 
     sfRectangleShape ***p;
     struct vector2ui    size;
-    unsigned int        attr;
+    size_t        attr;
 };
 
 struct text_drawable {
     struct drawable;
 
     sfText *text;
-    unsigned long attr;
+    size_t attr;
 };
 
 static sfRenderWindow *window;
@@ -73,7 +73,7 @@ void painter_destroy_font()
     sfFont_destroy(font);
 }
 
-unsigned long painter_register_field(struct field *fld)
+size_t painter_register_field(struct field *fld)
 {
     struct idlist *last;
     if (!drawables)
@@ -85,9 +85,9 @@ unsigned long painter_register_field(struct field *fld)
     f->t = TYPE_FIELD;
     f->size = fld->size;
     f->p = calloc(f->size.y, sizeof(sfRectangleShape **));
-    for (unsigned int j = 0; j < f->size.y; j++) {
+    for (size_t j = 0; j < f->size.y; j++) {
         f->p[j] = calloc(f->size.x, sizeof(sfRectangleShape *));
-        for (unsigned int i = 0; i < f->size.x; i++) {
+        for (size_t i = 0; i < f->size.x; i++) {
             f->p[j][i] = sfRectangleShape_create();
             sfVector2f cell_pos;
             cell_pos.x = fld->pos.x + (i * (CELL_SIZE.x + 2 * OUT_THICK));
@@ -104,15 +104,15 @@ unsigned long painter_register_field(struct field *fld)
     return last->id;
 }
 
-void painter_update_field(unsigned long id, struct field *fld)
+void painter_update_field(size_t id, struct field *fld)
 {
     struct idlist *node = list_get(drawables, id);
     if (!node)
         return;
     struct field_drawable *f = node->obj;
     f->attr = fld->attr;
-    for (unsigned int j = 0; j < fld->size.y; j++) {
-        for (unsigned int i = 0; i < fld->size.x; i++) {
+    for (size_t j = 0; j < fld->size.y; j++) {
+        for (size_t i = 0; i < fld->size.x; i++) {
             sfVector2f cell_pos;
             cell_pos.x = fld->pos.x + (i * (CELL_SIZE.x + 2 * OUT_THICK));
             cell_pos.y = fld->pos.y - (j * (CELL_SIZE.y + 2 * OUT_THICK));
@@ -129,7 +129,7 @@ void painter_update_field(unsigned long id, struct field *fld)
             }
         }
     }
-    for (unsigned int s = 0; s < fld->shape_cnt; ++s) {
+    for (size_t s = 0; s < fld->shape_cnt; ++s) {
         sfColor fill_color = shape_color_map[fld->shape[s].t];
         sfColor outline_color = (sfColor)UIFGACTIVECOLOR;
         if (fld->shape[s].attr && SHP_ATTR_GHOST) {
@@ -153,16 +153,16 @@ static void draw_field_drawable(struct drawable *d)
 {
     struct field_drawable *f = (void *)d;
     if (!(f->attr & FLD_ATTR_INVISIBLE))
-        for (unsigned int j = 0; j < f->size.y; j++)
-            for (unsigned int i = 0; i < f->size.x; i++)
+        for (size_t j = 0; j < f->size.y; j++)
+            for (size_t i = 0; i < f->size.x; i++)
                 sfRenderWindow_drawRectangleShape(window, f->p[j][i], NULL);
 }
 
 static void destroy_field_drawable(struct drawable *d)
 {
     struct field_drawable *f = (void *)d;
-    for (unsigned int j = 0; j < f->size.y; j++) {
-        for (unsigned int i = 0; i < f->size.x; i++)
+    for (size_t j = 0; j < f->size.y; j++) {
+        for (size_t i = 0; i < f->size.x; i++)
              sfRectangleShape_destroy(f->p[j][i]);
         free(f->p[j]);
     }
@@ -170,7 +170,7 @@ static void destroy_field_drawable(struct drawable *d)
     free(f);
 }
 
-unsigned long painter_register_text(struct text *txt)
+size_t painter_register_text(struct text *txt)
 {
     struct idlist *last;
     if (!drawables)
@@ -191,7 +191,7 @@ unsigned long painter_register_text(struct text *txt)
     return last->id;
 }
 
-void painter_update_text(unsigned long id, struct text *txt)
+void painter_update_text(size_t id, struct text *txt)
 {
     struct idlist *node = list_get(drawables, id);
     if (!node)
@@ -259,7 +259,7 @@ static void destroy_drawable(void *obj)
     }
 }
 
-void painter_destroy_drawable(unsigned long id)
+void painter_destroy_drawable(size_t id)
 {
     struct idlist *node = list_get(drawables, id);
     destroy_drawable(node->obj);
diff --git a/src/target/tetris.c b/src/target/tetris.c
index 2419c8d..eab3c7d 100644
--- a/src/target/tetris.c
+++ b/src/target/tetris.c
@@ -1,10 +1,13 @@
+/*
+ * tetris.c
+ *
+ * The main file. Here all the resources are initialized, run and destroyed.
+ *
+ * */
+
 #include <SFML/System/Clock.h>
-#include <SFML/Window/Keyboard.h>
 #include <SFML/Graphics/RenderWindow.h>
-#include <SFML/Graphics/Font.h>
-#include <stdio.h>
 #include <stdlib.h>
-#include <string.h>
 #include <time.h>
 
 #include "common.h"
@@ -17,10 +20,9 @@
 #include "tet_conf.h"
 
 sfRenderWindow *window;
-struct idlist *texts;
-
-struct field  fld, nxt;
-struct game   game = {
+struct idlist  *texts;
+struct field    fld, nxt;
+struct game     game = {
     .started = 0,
     .paused = 0,
     .scoreCurrent = 0,
@@ -51,10 +53,12 @@ int main()
     game.repPushDown = sfClock_create();
     game.repKeyLeft = sfClock_create();
     game.repKeyRight = sfClock_create();
+
     painter_load_font("dat/arial.ttf");
 
     sfVideoMode mode = (sfVideoMode){450, 570, 32};
-    window = sfRenderWindow_create(mode, windowName_conf, sfResize | sfClose, NULL);
+    window = sfRenderWindow_create(mode, windowName_conf, sfResize | sfClose,
+                                                                        NULL);
     if (!window)
         exit(EXIT_FAILURE);
     sfRenderWindow_setFramerateLimit(window, 60);
@@ -84,7 +88,6 @@ int main()
     painter_update_field(nxt.id, &nxt);
 
     texts = load_texts("dat/texts.yaml");
-
     list_foreach(texts, register_text);
 
     transition_init();
@@ -105,11 +108,13 @@ int main()
         window = 0;
     }
     painter_destroy_font();
+
     sfClock_destroy(game.gameTick);
     sfClock_destroy(game.putTick);
     sfClock_destroy(game.mTick);
     sfClock_destroy(game.repPushDown);
     sfClock_destroy(game.repKeyLeft);
     sfClock_destroy(game.repKeyRight);
+
     return EXIT_SUCCESS;
 }
diff --git a/src/text.c b/src/text.c
index f66ad2d..a879d51 100644
--- a/src/text.c
+++ b/src/text.c
@@ -62,7 +62,7 @@ struct idlist *load_texts(char *filename)
                 text->scene = malloc(sizeof(char) * (strlen((char *)ev.data.scalar.value) + 1));
                 strcpy(text->scene, (char *)ev.data.scalar.value);
             } else if (!strcmp((char *)event.data.scalar.value, "text")) {
-                text->text = calloc((utf8_strlen((char *)ev.data.scalar.value)) + 1, sizeof(unsigned int));
+                text->text = calloc((utf8_strlen((char *)ev.data.scalar.value)) + 1, sizeof(size_t));
                 utf8to32_strcpy(text->text, (char *)ev.data.scalar.value);
             } else if (!strcmp((char *)event.data.scalar.value, "font")) {
                 text->font = malloc(sizeof(char) * (strlen((char *)ev.data.scalar.value) + 1));
diff --git a/src/unicode.c b/src/unicode.c
index 8bde67d..8e4309d 100644
--- a/src/unicode.c
+++ b/src/unicode.c
@@ -3,7 +3,7 @@
 
 #include "unicode.h"
 
-static inline unsigned int utf8_char_len(unsigned char c)
+static inline size_t utf8_char_len(unsigned char c)
 {
     if (c > 0x00 && c < 0xC0)
         return 1;
@@ -17,9 +17,9 @@ static inline unsigned int utf8_char_len(unsigned char c)
         return 0;
 }
 
-unsigned long utf8_strlen(char *string)
+size_t utf8_strlen(char *string)
 {
-    unsigned long len = 0, keep = 0;
+    size_t len = 0, keep = 0;
     for (char *c = string; *c; (keep ? --keep : ++len), ++c)
         if (!keep)
             keep = (keep = utf8_char_len(*c)) ? keep - 1 : keep;
@@ -30,7 +30,7 @@ void utf8to32_strcpy(wchar_t *dest, char *src)
 {
     wchar_t *dc = dest;
     char *c = src;
-    unsigned long len = 0;
+    size_t len = 0;
     while (*c) {
         int clen = utf8_char_len(*c);
         if (clen == 1) {