From f6d142c92002e6ba83961c37805459dfb2caeac3 Mon Sep 17 00:00:00 2001
From: mibi88 <76903855+mibi88@users.noreply.github.com>
Date: Wed, 24 Jul 2024 21:43:21 +0200
Subject: [PATCH] Started refactoring.

---
 PROJECT_STRUCTURE.md |  3 +++
 README.md            |  4 ++++
 STYLE.md             | 29 +++++++++++++++++++++++++++++
 src/config.h         |  8 +++++++-
 src/dialogs.c        | 22 ++++++++++++++++------
 src/dialogs.h        |  4 +++-
 src/events.h         | 29 +++++++++++++++++++++++++++++
 src/game.c           |  3 +--
 src/game.h           | 20 ++++++++++++++++----
 src/main.c           |  2 +-
 src/map.c            |  9 ++++-----
 src/map.h            | 39 +++++++++++++++++++++++++++++++++------
 12 files changed, 146 insertions(+), 26 deletions(-)
 create mode 100644 PROJECT_STRUCTURE.md
 create mode 100644 STYLE.md

diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md
new file mode 100644
index 0000000..f8c9eeb
--- /dev/null
+++ b/PROJECT_STRUCTURE.md
@@ -0,0 +1,3 @@
+# Project structure
+
+TODO: Describe the project structure.
\ No newline at end of file
diff --git a/README.md b/README.md
index 03c5af6..c812169 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,10 @@
 
 Plus d'infos sur ce projet ici : [Le projet Collaboratif de PC](https://www.planet-casio.com/Fr/forums/topic17343-last-projet-collaboratif-avec-toute-la-commu.html)
 
+## Contribuer!
+Style du code [STYLE.md](STYLE.md).
+Structure du projet [PROJECT_STRUCTURE.md](PROJECT_STRUCTURE.md).
+
 ## Avencement du projet
 
 A ce stade, on a déjà implémenté :
diff --git a/STYLE.md b/STYLE.md
new file mode 100644
index 0000000..50e3e1a
--- /dev/null
+++ b/STYLE.md
@@ -0,0 +1,29 @@
+# Style guidelines in Collab RPG
+
+(Mibi88) Fcalva, SlyVTT: What do you think of this?
+
+Wrap the code on 80 columns. Align the wrapped code with the last parantheses,
+etc.
+
+Use curly braces with if, else, while and for statements if they can't hold on a
+single line.
+
+Put the curly braces after if, else, while or for statements and declarations of
+procedures on the same line.
+
+(Mibi88) SlyVTT, Fcalva, should be use a doc generation thing or do we describe
+the procedures as I did so far?
+
+Document your procedures as following:
+
+```C
+/* procedure_name()
+ * 
+ * Describe what this procedure does.
+ * arg1: Describe this argument. If the text is too long, wrap it to the next
+ *       line like this.
+ * arg2: Describe this argument, and so on.
+ */
+```
+
+Have I forgotten something?
diff --git a/src/config.h b/src/config.h
index 94ee6e3..3b9761e 100644
--- a/src/config.h
+++ b/src/config.h
@@ -15,17 +15,23 @@
 
 
 #if GINT_RENDER_RGB
+    /* The tile size */
     #define T_HEIGHT 16
     #define T_WIDTH  16
+    /* The size of a pixel */
     #define PXSIZE   2
     #define PATH_COLOR  C_RED
+    /* The size of the player */
     #define P_WIDTH 16
     #define P_HEIGHT 16
 #else
+    /* The tile size */
     #define T_HEIGHT 8
     #define T_WIDTH  8
+    /* The pixel size */
     #define PXSIZE   1
     #define PATH_COLOR  C_BLACK
+    /* The player size */
     #define P_WIDTH 8
     #define P_HEIGHT 8
 #endif
@@ -35,7 +41,7 @@
  * collisions! */
 #define SPEED (PXSIZE*2)
 
-
+/* The face size (in the dialogs) */
 #define F_WIDTH (32*PXSIZE)
 #define F_HEIGHT (32*PXSIZE)
 
diff --git a/src/dialogs.c b/src/dialogs.c
index c826250..d5f12bb 100644
--- a/src/dialogs.c
+++ b/src/dialogs.c
@@ -35,8 +35,7 @@ extern font_t fontRPG;
 #endif
 
 
-void blit()
-{
+void blit() {
         dupdate();
        
         #if GRAYMODEOK && !defined(GINT_HW_CG)
@@ -150,7 +149,12 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
         if(l>=max_lines_amount-1){
             /* If we drew one entire screen. */
             /* Wait that the SHIFT key is pressed if we should. */
-            if(wait_continue) while(getkey_opt(GETKEY_DEFAULT & ~GETKEY_MOD_SHIFT & ~GETKEY_MOD_ALPHA, NULL).key != KEY_SHIFT) sleep();
+            if(wait_continue){
+                while(getkey_opt(GETKEY_DEFAULT & ~GETKEY_MOD_SHIFT &
+                                 ~GETKEY_MOD_ALPHA, NULL).key != KEY_SHIFT){
+                    sleep();
+                }
+            }
             /* Clear the text area. */
             drect(BOX_HEIGHT*PXSIZE, 0, DWIDTH, (BOX_HEIGHT-1)*PXSIZE-2,
                   C_WHITE);
@@ -174,7 +178,12 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
         dtext(BOX_HEIGHT*PXSIZE, y, NEXT_COLOR, "[SHIFT] : suite...");
         /* Update the screen and wait for SHIFT being pressed, if needed. */
         if(update_screen) blit();
-        if(wait_continue) while(getkey_opt( GETKEY_DEFAULT & ~GETKEY_MOD_SHIFT & ~GETKEY_MOD_ALPHA, NULL).key != KEY_SHIFT) sleep();
+        if(wait_continue){
+            while(getkey_opt(GETKEY_DEFAULT & ~GETKEY_MOD_SHIFT &
+                             ~GETKEY_MOD_ALPHA, NULL).key != KEY_SHIFT){
+                sleep();
+            }
+        }
     }
     if(call_before_end) return_int = call_before_end(game, i);
     if(end_anim){
@@ -186,7 +195,7 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
             drect(0, 0, DWIDTH, i*PXSIZE, C_WHITE);
             drect(0, i*PXSIZE, DWIDTH, (i+1)*PXSIZE, C_BLACK);
             dsubimage(4*PXSIZE, 2*PXSIZE, face, 0, 0, F_WIDTH, (i-8)*PXSIZE,
-                DIMAGE_NONE);
+                      DIMAGE_NONE);
 
             dupdate();
 
@@ -340,7 +349,8 @@ int showtext_dialog_ask(Game *game, bopti_image_t *face, char *text, bool start,
 
 
 
-void initiate_dialog_sequence(Game *game, bopti_image_t *face, uint32_t dialogNumber )
+void initiate_dialog_sequence(Game *game, bopti_image_t *face,
+                              uint32_t dialogNumber )
 {
         Dialog *currentDiag = &game->map_level->dialogs[ dialogNumber ];
 
diff --git a/src/dialogs.h b/src/dialogs.h
index 7259f7a..da65d2f 100644
--- a/src/dialogs.h
+++ b/src/dialogs.h
@@ -87,6 +87,8 @@ int showtext_dialog_ask(Game *game, bopti_image_t *face, char *text, bool start,
                          bool end, char *choices, int choices_amount,
                          int default_choice);
 
-void initiate_dialog_sequence(Game *game, bopti_image_t *face, uint32_t dialogNumber );
+/* TODO: Doc. */
+void initiate_dialog_sequence(Game *game, bopti_image_t *face,
+                              uint32_t dialogNumber);
 
 #endif
diff --git a/src/events.h b/src/events.h
index f43fecf..0cd503d 100644
--- a/src/events.h
+++ b/src/events.h
@@ -1,8 +1,12 @@
 #ifndef EVENTS_H
 #define EVENTS_H
 
+/* The max amount of variables that can be bound. */
 #define MAX_VARIABLES 32
+/* The max. size of the message buffer.
+ * WARNING: Bigger messages will be truncated! */
 #define MESSAGE_BUFFER_SZ 1024
+/* The maximal size of a token. Bigger tokens will be truncated. */
 #define TOKEN_MAX_SZ 1024
 
 typedef struct {
@@ -28,8 +32,33 @@ typedef enum {
     OP_AMOUNT
 } Operation;
 
+/* events_init_handler()
+ *
+ * Initialize an event handler.
+ * handler: The Event handler to initialize.
+ */
 void events_init_handler(EventHandler *handler);
+/* events_bind_variable()
+ * 
+ * Bind a variable. Binding a variable allows it to be modified by messages
+ * passed to the event handler using tags written as following:
+ * `variable+number` (The backticks delimit the tag). Available operators:
+ * '=': Assign a value to the variable.
+ * '+': Addition.
+ * '-': Substraction.
+ * '*': Multiplication.
+ * '/': Division.
+ * '%': Modulo.
+ * handler: The event handler.
+ * var:     A pointer to the variable to bind.
+ * name:    The name of the variable. This is the name that will be used to
+ *          refer to this variable in a tag.
+ */
 int events_bind_variable(EventHandler *handler, int *var, char *name);
+/* events_parse_string()
+ * handler: The event handler.
+ * message: The message to parse.
+ */
 char *events_parse_string(EventHandler *handler, char *message);
 
 #endif
diff --git a/src/game.c b/src/game.c
index 135c336..72313c0 100644
--- a/src/game.c
+++ b/src/game.c
@@ -80,8 +80,7 @@ void game_logic(Game *game) {
 }
 
 
-void render_indicator(Game *game)
-{
+void render_indicator(Game *game) {
     /* nothing to do for the player so we quit */
     if (game->player.canDoSomething==false)
         return;
diff --git a/src/game.h b/src/game.h
index d1cd86e..5935453 100644
--- a/src/game.h
+++ b/src/game.h
@@ -155,14 +155,26 @@ typedef struct {
 /* (Mibi88) TODO: Describe what this function is doing. */
 void game_logic(Game *game);
 
-/* Draws everything on screen. */
+/* draw()
+ *
+ * Draws everything on screen.
+ * game: The game struct.
+ */
 void draw(Game *game);
 
-/* This render a small sign on the upper lecft corner of the screen */
-/* if the player can do an action */
+/* render_indicator()
+ * 
+ * This render a small sign on the upper left corner of the screen
+ * if the player can do an action
+ * game: The game struct.
+ */
 void render_indicator(Game *game);
 
-/* Handle key presses. */
+/* get_inputs()
+ * 
+ * Handle key presses.
+ * game: The game struct.
+ */
 void get_inputs(Game *game);
 
 #endif
diff --git a/src/main.c b/src/main.c
index 25287d5..0e308cf 100644
--- a/src/main.c
+++ b/src/main.c
@@ -44,7 +44,7 @@ Game game = {
     , false, false, false, 100
 }; 
 
-/* screen capture management code */
+/* screen capture management code. TODO: Clean this up! */
 
 #if USB_FEATURE
 
diff --git a/src/map.c b/src/map.c
index d378263..d588264 100644
--- a/src/map.c
+++ b/src/map.c
@@ -218,21 +218,20 @@ Map *get_map_for_coordinates( Game *game, int x, int y )
 {
     /* check if the current map contains the point */
     if (x>= (int)game->map_level->xmin && x< (int)game->map_level->xmax && 
-        y>= (int)game->map_level->ymin && y< (int)game->map_level->ymax)
+        y>= (int)game->map_level->ymin && y< (int)game->map_level->ymax){
         return game->map_level;
+    }
 
     /* else we check in worldRPG if there is a mal containing that point */
     int i = 0;
     Map *current = worldRPG[i];
-    do
-    {
+    do{
         if (x>= (int)current->xmin && x< (int)current->xmax && 
             y>= (int)current->ymin && y< (int)current->ymax)
             return current;
         i++;
         current = worldRPG[i];
-    }
-    while (current!=NULL);
+    }while (current!=NULL);
     
     /* else we return NULL cause the point is a not within a map */
     return NULL;
diff --git a/src/map.h b/src/map.h
index 1586186..6a74df1 100644
--- a/src/map.h
+++ b/src/map.h
@@ -19,21 +19,48 @@
 
 
 
-/* Draws the map map on the entire screen to be viewed by the player player. */
+/* render_map()
+ * 
+ * Draws the map map on the entire screen to be viewed by the player player.
+ * game: The game struct.
+ */
 void render_map(Game *game);
 
-/* Draws the map layer on the entire screen to be viewed by the player player.
+/* render_map_by_layer()
+ * 
+ * Draws the map layer on the entire screen to be viewed by the player player.
+ * game:  The game struct.
+ * layer: The layer to render.
  */
 void render_map_by_layer(Game *game, int layer);
 
-/* Get the tile at (x, y) of the map map. If the tile is located outside of the
- * screen, MAP_OUTSIDE is returned. */
+/* get_tile()
+ * 
+ * Get the tile at (x, y) of the map map. If the tile is located outside of the
+ * screen, MAP_OUTSIDE is returned.
+ * game: The game struct.
+ * x:    The coordinates of the tile.
+ * y:    The coordinates of the tile.
+ * l:    The layer of the tile.
+ */
 short int get_tile(Game *game, int x, int y, int l);
 
-/* Returns what is in the walkable layer at (x, y). */
+/* get_walkable()
+ * 
+ * Returns what is in the walkable layer at (x, y).
+ * game: The game struct.
+ * x:    The coordinates of the tile.
+ * y:    The coordinates of the tile.
+ */
 short int get_walkable(Game *game, int x, int y);
 
-/* return the pointer to the map containing the given position */
+/* get_map_for_coordinates()
+ * 
+ * return the pointer to the map containing the given position.
+ * game: The game struct.
+ * x:    The coordinates to look at.
+ * y:    The coordinates to look at.
+ */
 Map* get_map_for_coordinates(Game *game, int x, int y );
 
 #endif