Finished adding comments to the dialogs code.

src/dialogs.c

@@ -161,8 +161,9 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
     }
     if(call_before_end) return_int = call_before_end(game, i);
     if(end_anim){
-        /* Run another little fancy animation. */
+        /* Run another little fancy animation if we should. */
         for(i=BOX_HEIGHT;i>0;i--){
+            /* It is the same as the start animation. */
             draw(game);
             drect(0, 0, DWIDTH, i*PXSIZE, C_WHITE);
             drect(0, i*PXSIZE, DWIDTH, (i+1)*PXSIZE, C_BLACK);
@@ -180,6 +181,8 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
 
 void showtext_dialog(Game *game, bopti_image_t *face, char *text,
               bool dialog_start, bool dialog_end) {
+    /* Run showtext_opt with some default values. It makes it easier to use in
+     * simple dialogs. */
     showtext_opt(game, face, text, NULL, dialog_start, dialog_end, NULL, 100,
                  true, 0, true);
 }
@@ -187,11 +190,15 @@ void showtext_dialog(Game *game, bopti_image_t *face, char *text,
 #define CHOICE_BOX_HEIGHT 10
 #define CHOICE_BOX_PADDING_TOP 3
 
+/* Some variables and pointers used to get some arguments passed in
+ * showtext_dialog_ask in _choice_call_before_end. */
 char *_choices, *_text;
 int _choices_amount, _default_choice;
 bopti_image_t *_face;
 unsigned int _i;
 
+/* Get where I started drawing a dialog page, to be able to redraw the last page
+ * for the end animation in _choice_call_before_end. */
 void _choice_screen_call(Game *game, unsigned int i) {
     _i = i;
 }
@@ -200,19 +207,37 @@ int _choice_call_before_end(Game *game, unsigned int org_i) {
     int i, key;
     /* Make a little animation because we looove little animations ;) */
     for(i=0;i<DWIDTH/8+1;i++){
+        /* Fill the interaction box with white */
         drect(0, (BOX_HEIGHT+1)*PXSIZE+1, i*(DWIDTH/8),
               (BOX_HEIGHT+CHOICE_BOX_HEIGHT)*PXSIZE, C_WHITE);
+        /* Draw a thick border on the right of the box. */
         drect(i*(DWIDTH/8), BOX_HEIGHT*PXSIZE, i*(DWIDTH/8)+PXSIZE-1,
               (BOX_HEIGHT+CHOICE_BOX_HEIGHT+1)*PXSIZE, C_BLACK);
+        /* Draw a thick border on the bottom of the box. */
         drect(0, (BOX_HEIGHT+CHOICE_BOX_HEIGHT)*PXSIZE, i*(DWIDTH/8),
               (BOX_HEIGHT+CHOICE_BOX_HEIGHT+1)*PXSIZE, C_BLACK);
+        /* Show everyting on screen. */
         blit();
+        /* Wait some ms so that the animation isn't too fast. */
         while(game->frame_duration < 20) sleep();
         game->frame_duration = 0;
     }
+    /* Calculate the maximal size of a choice. */
     const int choice_size = DWIDTH/_choices_amount;
+    /* arrow_width:  The space taken by the arrow that shows the selected item.
+     * arrow_height: The height of the arrow used to show which item is choosen.
+     *               Used to calculate the size of the rectangle used to remove
+     *               him.
+     * selected:     The selected item.
+     * pos:          The position of the item we're drawing in the choice
+     *               string. The choice string is not really a string, it is
+     *               made of multiple '\0' terminated strings, that are in
+     *               memory one after the other.
+     */
     int arrow_width, arrow_height, selected = _default_choice, pos = 0;
+    /* Calculate the size of the arrow. */
     dsize(">", &FONT_USED, &arrow_width, &arrow_height);
+    /* Add the character spacing of the font to it. */
     arrow_width += FONT_USED.char_spacing;
     do{
         /* Display the diffrent choices. */
@@ -227,6 +252,8 @@ int _choice_call_before_end(Game *game, unsigned int org_i) {
         }
         blit();
         key = getkey().key;
+        /* If the player pressed the left arrow key and has not already selected
+         * the first possible choice. */
         if(key == KEY_LEFT && selected > 0){
             /* Remove the old arrow. */
             drect(selected*choice_size+PXSIZE,
@@ -234,8 +261,12 @@ int _choice_call_before_end(Game *game, unsigned int org_i) {
                 selected*choice_size+PXSIZE+arrow_width,
                 (BOX_HEIGHT+CHOICE_BOX_PADDING_TOP)*PXSIZE+arrow_height,
                 C_WHITE);
+            
+            /* Move the selection arrow and update the selected item. */
             selected--;
         }
+        /* If the player pressed the right arrow key and has not already
+         * selected the last possible choice. */
         else if(key == KEY_RIGHT && selected < _choices_amount-1){
             /* Remove the old arrow. */
             drect(selected*choice_size+PXSIZE,
@@ -243,11 +274,16 @@ int _choice_call_before_end(Game *game, unsigned int org_i) {
                 selected*choice_size+PXSIZE+arrow_width,
                 (BOX_HEIGHT+CHOICE_BOX_PADDING_TOP)*PXSIZE+arrow_height,
                 C_WHITE);
+            
+            /* Move the selection arrow and update the selected item. */
             selected++;
         }
+    /* If the user has not validated his choice by pressing EXE, we loop one
+     * more time. */
     }while(key != KEY_EXE);
     /* Make a little animation because we looove little animations ;) */
     for(i=DWIDTH/8+1;i>0;i--){
+        /* I'm drawing the same box as on the start animation */
         draw(game);
         showtext_opt(game, _face, _text, NULL, false, false, NULL, 0, false,
                      _i, false);
@@ -261,17 +297,23 @@ int _choice_call_before_end(Game *game, unsigned int org_i) {
         while(game->frame_duration < 20) sleep();
         game->frame_duration = 0;
     }
+    /* Return the selected item because he'll also be returned by showtext_opt.
+     */
     return selected;
 }
 
 int showtext_dialog_ask(Game *game, bopti_image_t *face, char *text, bool start,
                          bool end, char *choices, int choices_amount,
                          int default_choice) {
+    /* Put some arguments in global pointers and variables to make them
+     * accessible by _choice_call_before_end. */
     _choices = choices;
     _choices_amount = choices_amount;
     _default_choice = default_choice;
     _face = face;
     _text = text;
+    /* Run showtext_opt and return his return value (the return value of
+     *_choice_call_before_end) */
     return showtext_opt(game, face, text, _choice_call_before_end, start, end,
                         _choice_screen_call, 100, true, 0, true);
 }

src/dialogs.h

@@ -9,6 +9,34 @@
 #define F_WIDTH (32*PXSIZE)
 #define F_HEIGHT (32*PXSIZE)
 
+/* showtext_opt()
+ *
+ * Show some text in a box with word wrap for dialogs.
+ *
+ * game:            The game struct of the current game.
+ * face:            A bopti_image_t of the face of the person who's saying this
+ *                  text. This bopti_image_t should have a width of F_WIDTH and
+ *                  a height of F_HEIGHT.
+ * text:            The text to display.
+ * call_before_end: A function called when the end of the text was displayed and
+ *                  the user pressed EXE (or wait_continue was true). His
+ *                  parameter game is the game struct passed to showtext_opt,
+ *                  and i is the current position in text.
+ * start_anim:      A boolean, that, if he's true, makes that a little animation
+ *                  is shown at the start of showtext_opt.
+ * end_anim:        A boolean, that, if he's true, makes that a little animation
+ *                  is shown at the end of showtext_opt.
+ * for_each_screen: A function called before a page of the dialog gets drawn.
+ *                  His parameter game is the game struct passed to
+ *                  showtext_opt, and i is the current position in text.
+ * line_duration:   How many ms showtext_opt will wait after a line has been
+ *                  drawn.
+ * update_screen:   When he's true showtext_opt will update the screen after
+ *                  drawing a line etc.
+ * start_i:         At which position I start displaying the text.
+ * wait_continue:   If I should wait that EXE is pressed after drawing a page.
+ */
+
 int showtext_opt(Game *game, bopti_image_t *face, char *text,
                  int call_before_end(Game *game, unsigned int i),
                  bool start_anim,
@@ -17,9 +45,46 @@ int showtext_opt(Game *game, bopti_image_t *face, char *text,
                  int line_duration, bool update_screen, unsigned int start_i,
                  bool wait_continue);
 
+/* showtext_dialog()
+ *
+ * Calls showtext_opt with default parameters.
+ *
+ * game:         The game struct of the current game.
+ * face:         A bopti_image_t of the face of the person who's saying this
+ *               text. This bopti_image_t should have a width of F_WIDTH and a
+ *               height of F_HEIGHT.
+ * text:         The text to display.
+ * dialog_start: A boolean, that, if he's true, makes that a little animation is
+ *               shown at the start of showtext_opt.
+ * dialog_end:   A boolean, that, if he's true, makes that a little animation is
+ *               shown at the end of showtext_opt.
+ */
+
 void showtext_dialog(Game *game, bopti_image_t *face, char *text,
                      bool dialog_start, bool dialog_end);
 
+/* showtext_dialog_ask()
+ *
+ * Like showtext_dialog, but lets the user choose between multiple possible
+ * choices after displaying the text.
+ *
+ * game:           The game struct of the current game.
+ * face:           A bopti_image_t of the face of the person who's saying this
+ *                 text. This bopti_image_t should have a width of F_WIDTH and a
+ *                 height of F_HEIGHT.
+ * text:           The text to display.
+ * start:          A boolean, that, if he's true, makes that a little animation
+ *                 is shown at the start of showtext_opt.
+ * end:            A boolean, that, if he's true, makes that a little animation
+ *                 is shown at the end of showtext_opt.
+ * choices:        A pointer to null-terminated strings that are one after the
+ *                 other in memory. They should be one null-terminated string
+ *                 for each possible choice.
+ * choice_amount:  The amount of possible choices in the choices zero-terminated
+ *                 strings.
+ * default_choice: The choice choosen by default when the dialog just opened.
+ */
+
 int showtext_dialog_ask(Game *game, bopti_image_t *face, char *text, bool start,
                          bool end, char *choices, int choices_amount,
                          int default_choice);