[Add] Documented menus.

src/menu.c

@@ -1,3 +1,9 @@
+/**
+ * @file menu.h
+ *
+ * @brief Handle the important game menus.
+ */
+
 #include <string.h>
 #include <SDL.h>
 
@@ -16,37 +22,36 @@
 #include "nebulae.h"
 #include "menu.h"
 
-#define MAIN_WIDTH          130
+#define MAIN_WIDTH          130   /**< Main menu width. */
-#define MAIN_HEIGHT         250
+#define MAIN_HEIGHT         250   /**< Main menu height. */
 
-#define MENU_WIDTH          130
+#define MENU_WIDTH          130   /**< Escape menu width. */
-#define MENU_HEIGHT         200
+#define MENU_HEIGHT         200   /**< Escape menu height. */
 
-#define INFO_WIDTH          360
+#define INFO_WIDTH          360   /**< Information menu width. */
-#define INFO_HEIGHT         280
+#define INFO_HEIGHT         280   /**< Information menu height. */
 
-#define OUTFITS_WIDTH       400
+#define OUTFITS_WIDTH       400   /**< Outfit menu width. */
-#define OUTFITS_HEIGHT      200
+#define OUTFITS_HEIGHT      200   /**< Outfit menu height. */
 
-#define CARGO_WIDTH         300
+#define CARGO_WIDTH         300   /**< Cargo menu width. */
-#define CARGO_HEIGHT        300
+#define CARGO_HEIGHT        300   /**< Cargo menu height. */
 
-#define MISSIONS_WIDTH      600
+#define MISSIONS_WIDTH      600   /**< Mission menu width. */
-#define MISSIONS_HEIGHT     400
+#define MISSIONS_HEIGHT     400   /**< Mission menu height. */
 
-#define DEATH_WIDTH         130
+#define DEATH_WIDTH         130   /**< Death menu width. */
-#define DEATH_HEIGHT        150
+#define DEATH_HEIGHT        150   /**< Death menu height. */
 
-#define BUTTON_WIDTH        90
+#define BUTTON_WIDTH        90    /**< Button width, standard across menus. */
-#define BUTTON_HEIGHT       30
+#define BUTTON_HEIGHT       30    /**< Button height, standard across menus. */
 
-#define menu_Open(f)            (menu_open |= (f))
+#define menu_Open(f)            (menu_open |= (f)) /**< Mark a menu as open. */
-#define menu_Close(f)           (menu_open ^= (f))
+#define menu_Close(f)           (menu_open ^= (f)) /**< Mark a menu as closed. */
-
+int menu_open = 0;  /**< Store the opened/closed menus. */
-int menu_open = 0;
 
 /* Main menu. */
-void menu_main_close(void);
+void menu_main_close(void); /**< Externed in save.c */
 static void menu_main_load(char* str);
 static void menu_main_new(char* str);
 static void menu_main_exit(char* str);
@@ -73,6 +78,11 @@ static void menu_death_main(char* str);
 /* Generic. */
 static void menu_generic_close(char* str);
 
+/**
+ * @fn void menu_main(void)
+ *
+ * @brief Open the main menu (titlescreen).
+ */
 void menu_main(void) {
   unsigned int bwid, wid;
   glTexture* tex;
@@ -107,6 +117,11 @@ void menu_main(void) {
   menu_Open(MENU_MAIN);
 }
 
+/**
+ * @fn void menu_main_close(void)
+ *
+ * @brief Close the main menu.
+ */
 void menu_main_close(void) {
   window_destroy(window_get("Main Menu"));
 
@@ -116,12 +131,24 @@ void menu_main_close(void) {
   menu_Close(MENU_MAIN);
 }
 
+/**
+ * @fn static void menu_main_load(char* str)
+ *
+ * @brief Function to activate the load game menu.
+ *    @param str Unused.
+ */
 static void menu_main_load(char* str) {
   (void)str;
 
   load_game_menu();
 }
 
+/**
+ * @fn static void menu_main_new(char* str)
+ *
+ * @brief Function to activate the new game menu.
+ *    @param str Unused.
+ */
 static void menu_main_new(char* str) {
   (void)str;
 
@@ -129,6 +156,12 @@ static void menu_main_new(char* str) {
   player_new();
 }
 
+/**
+ * @fn static void menu_main_new(char* str)
+ *
+ * @brief Function to exit the main menu and game.
+ *    @param str Unused.
+ */
 static void menu_main_exit(char* str) {
   (void)str;
   unsigned int wid;
@@ -149,16 +182,22 @@ static void menu_main_exit(char* str) {
 }
 
 /* Ze ingame menu. */
-/* Small ingame menu. */
+
+/**
+ * @fn void menu_small(void)
+ *
+ * @brief Open the small ingame menu.
+ */
 void menu_small(void) {
+  unsigned int wid;
+
+  /* Check if menu should be openable. */
   if((player == NULL) || player_isFlag(PLAYER_DESTROYED)
       || pilot_isFlag(player, PILOT_DEAD) ||
       (menu_isOpen(MENU_MAIN) ||
        menu_isOpen(MENU_SMALL) ||
        menu_isOpen(MENU_DEATH)))
-    return; /* It's already open.. */
+    return;
-
-  unsigned int wid;
 
   wid = window_create("Menu", -1, -1, MENU_WIDTH, MENU_HEIGHT);
 
@@ -178,12 +217,24 @@ void menu_small(void) {
   menu_Open(MENU_SMALL);
 }
 
+/**
+ * @fn static void menu_small_close(char* str)
+ *
+ * @brief Close the small ingame menu.
+ *    @param str Unused.
+ */
 static void menu_small_close(char* str) {
   (void)str;
   window_destroy(window_get("Menu"));
   menu_Close(MENU_SMALL);
 }
 
+/**
+ * @fn static void menu_small_exit(char* str)
+ *
+ * @brief Close the small ingame menu and go back to the main menu.
+ *    @param str Unused.
+ */
 static void menu_small_exit(char* str) {
   (void)str;
   window_destroy(window_get("Menu"));
@@ -191,13 +242,23 @@ static void menu_small_exit(char* str) {
   menu_main();
 }
 
-/* Edit the options. */
+/**
+ * @fn static void edit_options(char* str)
+ *
+ * @brief Edit the options.
+ *    @param str Unused.
+ * @todo Make the options menu.
+ */
 static void edit_options(char* str) {
   (void)str;
   /* @todo Make options menu */
 }
 
-/* Exit the game. */
+/**
+ * @fn static void exit_game(void)
+ *
+ * @brief Exit the game.
+ */
 static void exit_game(void) {
   /* If landed we must save anyways. */
   if(landed) {
@@ -210,15 +271,20 @@ static void exit_game(void) {
   SDL_PushEvent(&quit);
 }
 
-/* Info menu. */
+/**
+ * @fn void menu_info(void)
+ *
+ * @brief Open the information window.
+ */
 void menu_info(void) {
-  if(menu_isOpen(MENU_INFO)) return;
-
   char str[128];
   char* lt;
   unsigned int wid;
   wid = window_create("Info", -1, -1, INFO_WIDTH, INFO_HEIGHT);
 
+  /* Can't open menu twise. */
+  if(menu_isOpen(MENU_INFO)) return;
+
   /* Pilot generics. */
   lt = ltime_pretty(ltime_get());
   window_addText(wid, 20, 20, 120, INFO_HEIGHT-60,
@@ -268,6 +334,12 @@ void menu_info(void) {
   menu_Open(MENU_INFO);
 }
 
+/**
+ * @fn static void menu_info_close(char* str) 
+ *
+ * @brief Close the information menu.
+ *    @param str Unused.
+ */
 static void menu_info_close(char* str) {
   if(strcmp(str, "btnClose")==0)
     window_destroy(window_get("Info"));
@@ -275,6 +347,12 @@ static void menu_info_close(char* str) {
   menu_Close(MENU_INFO);
 }
 
+/**
+ * @fn static void info_outfits_menu(char* str)
+ *
+ * @brief Show the player what outfits she has.
+ *    @param str Unused.
+ */
 static void info_outfits_menu(char* str) {
   (void) str;
   char* buf;
@@ -301,7 +379,12 @@ static void info_outfits_menu(char* str) {
                    "closeOutfits", "Close", menu_generic_close);
 }
 
-/* Show the players cargo. */
+/**
+ * @fn static void info_cargo_menu(char* str)
+ *
+ * @brief Show the player her cargo.
+ *    @param str Unused.
+ */
 static void info_cargo_menu(char* str) {
   (void)str;
   unsigned int wid;
@@ -346,6 +429,12 @@ static void info_cargo_menu(char* str) {
   cargo_update(NULL);
 }
 
+/**
+ * @fn static void cargo_update(char* str)
+ *
+ * @brief Update the players cargo in the cargo menu.
+ *    @param str Unused.
+ */
 static void cargo_update(char* str) {
   (void)str;
   unsigned int wid;
@@ -363,6 +452,12 @@ static void cargo_update(char* str) {
     window_enableButton(wid, "btnJettisonCargo");
 }
 
+/**
+ * @fn static void cargo_jettison(char* str)
+ *
+ * @brief Make the player jettison the currently selected cargo.
+ *    @param str Unused.
+ */
 static void cargo_jettison(char* str) {
   (void)str;
   unsigned int wid;
@@ -384,7 +479,12 @@ static void cargo_jettison(char* str) {
   info_cargo_menu(NULL);
 }
 
-/* Show the player's active missions. */
+/**
+ * @fn static void info_missions_menu(char* str)
+ *
+ * @brief Show the players active missions.
+ *    @param str Unused.
+ */
 static void info_missions_menu(char* str) {
   (void)str;
   unsigned int wid;
@@ -415,6 +515,12 @@ static void info_missions_menu(char* str) {
   mission_menu_genList(1);
 }
 
+/**
+ * @fn static void mission_menu_genList(int first)
+ *
+ * @brief Create the current mission list for the mission menu.
+ *    @param first 1 if it's the first time run.
+ */
 static void mission_menu_genList(int first) {
   int i, j;
   char** misn_names;
@@ -445,6 +551,12 @@ static void mission_menu_genList(int first) {
   mission_menu_update(NULL);
 }
 
+/**
+ * @fn static void mission_menu_update(char* str)
+ *
+ * @brief Update the mission menu mission info based on what's selected.
+ *    @param str Unused.
+ */
 static void mission_menu_update(char* str) {
   char* active_misn;
   Mission* misn;
@@ -467,6 +579,12 @@ static void mission_menu_update(char* str) {
   window_enableButton(wid, "btnAbortMission");
 }
 
+/**
+ * @fn static void mission_menu_abort(char* str)
+ *
+ * @brief Abort a mission in the mission menu.
+ *    @param str Unused.
+ */
 static void mission_menu_abort(char* str) {
   (void)str;
   char* selected_misn;
@@ -489,7 +607,11 @@ static void mission_menu_abort(char* str) {
   }
 }
 
-/* Pilot dead. */
+/**
+ * @fn void menu_death(void)
+ *
+ * @brief Player death menu, appears when player got killed.
+ */
 void menu_death(void) {
   unsigned int wid;
   wid = window_create("Death", -1, -1, DEATH_WIDTH, DEATH_HEIGHT);
@@ -503,6 +625,12 @@ void menu_death(void) {
   menu_Open(MENU_DEATH);
 }
 
+/**
+ * @fn static void menu_death_main(char* str)
+ *
+ * @brief Close the player death menu.
+ *    @param str Unused.
+ */
 static void menu_death_main(char* str) {
   (void)str;
   unsigned int wid;
@@ -514,7 +642,15 @@ static void menu_death_main(char* str) {
   menu_main();
 }
 
-/* Generic close approach. */
+/**
+ * @fn static void menu_generic_close(char* str)
+ *
+ * @brief Generic function to close the current window.
+ *
+ * Only works if the button is labeled "closeFoo", where "Foo" would be the
+ * window name.
+ *    @param str Used by the button it's assigned to internally.
+ */
 static void menu_generic_close(char* str) {
   window_destroy(window_get(str+5)); /* closeFoo -> Foo. */
 }

src/menu.h

@@ -1,12 +1,13 @@
 #pragma once
 
-#define MENU_MAIN    (1<<0)
+#define MENU_MAIN    (1<<0) /**< Main menu (titlescreen). */
-#define MENU_SMALL   (1<<1)
+#define MENU_SMALL   (1<<1) /**< Small ingame menu. */
-#define MENU_INFO    (1<<2)
+#define MENU_INFO    (1<<2) /**< Player information menu. */
-#define MENU_DEATH   (1<<3)
+#define MENU_DEATH   (1<<3) /**< Player death menu. */
-#define menu_isOpen(f) (menu_open & (f))
+#define menu_isOpen(f) (menu_open & (f)) /**< Check if a certain menu is opened. */
 extern int menu_open;
 
+/* Menu opening routines. */
 void menu_main(void);
 void menu_small(void);
 void menu_info(void);