[Add] Documented outfits.

src/dialogue.c

@@ -1,7 +1,19 @@
 /**
  * @file dialogue.c.
  *
- * @brief Handles dialogue stuff.
+ * @brief Is a hight level api around toolkit.c for easy window creation.
+ *
+ * Only one dialogue may be open at once or behaviour is unspecified.
+ *
+ * All these dialogues use what I'm calling the secondary main loop hack.
+ * Basically they spawn another main lopp identical to the primary whose only
+ * difference is that it breaks on loop_done. Therefore this loop hijacks
+ * the main lopp until it's over, making these functions seem to be blocking
+ * without really being blocking.
+ *
+ * @todo Make dialogue system more flexible.
+ *
+ * @sa toolkit.c
  */
 #include <stdarg.h>
 #include "lephisto.h"
@@ -24,7 +36,7 @@ static void dialogue_inputClose(char* str);
 static void dialogue_inputCancel(char* str);
 
 /* Secondary loop hack. */
-static int loop_done;
+static int loop_done;   /**< Used to indicate the secondary loop is finished. */
 static int toolkit_loop(void);
 
 /**
@@ -92,8 +104,14 @@ static glFont* dialogue_getSize(char* msg, int* w, int* h) {
   return font;
 }
 
-/* Displays an alert popup with only an ok button and a message. */
+static unsigned int msg_wid = 0; /**< Stores the message window id. */
-static unsigned int msg_wid = 0;
+/**
+ * @fn void dialogue_msg(char* caption, const char* fmt, ...)
+ *
+ * @brief Open a dialogue window with an OK button and a message.
+ *    @param caption Window title.
+ *    @param fmt Printf syle message to display.
+ */
 void dialogue_msg(char* caption, const char* fmt, ...) {
   char msg[4096];
   va_list ap;

src/outfit.h

@@ -2,40 +2,51 @@
 #include "opengl.h"
 #include "sound.h"
 
-#define outfit_isProp(o,p)  ((o)->properties & p)
+#define outfit_isProp(o,p)  ((o)->properties & p) /**< Check an outfit for property. */
 /* Property flags. */
-#define OUTFIT_PROP_WEAP_SECONDARY (1<<0)
+#define OUTFIT_PROP_WEAP_SECONDARY (1<<0) /**< Is a secondary weapon? */
 
-/* Outfit types. */
+/**
+ * @enum OutfitType
+ *
+ * @brief Different types of existing outfits.
+ *
+ * Outfits are organized by the order here.
+ */
 typedef enum OutfitType_ {
-  OUTFIT_TYPE_NULL,
+  OUTFIT_TYPE_NULL,                       /**< NULL type. */
-  OUTFIT_TYPE_BOLT,
+  OUTFIT_TYPE_BOLT,                       /**< @todo Fixed bolt cannon. */
-  OUTFIT_TYPE_BEAM,
+  OUTFIT_TYPE_BEAM,                       /**< Fixed beam cannon. */
-  OUTFIT_TYPE_TURRET_BOLT,
+  OUTFIT_TYPE_TURRET_BOLT,                /**< @todo Rotaty bolt turret. */
-  OUTFIT_TYPE_TURRET_BEAM,
+  OUTFIT_TYPE_TURRET_BEAM,                /**< Rotary bolt turret. */
-  OUTFIT_TYPE_MISSILE_DUMB,
+  OUTFIT_TYPE_MISSILE_DUMB,               /**< Dumb missile launcher. */
-  OUTFIT_TYPE_MISSILE_DUMB_AMMO,
+  OUTFIT_TYPE_MISSILE_DUMB_AMMO,          /**< Dumb missile ammo. */
-  OUTFIT_TYPE_MISSILE_SEEK,
+  OUTFIT_TYPE_MISSILE_SEEK,               /**< Seeker missile launcher. */
-  OUTFIT_TYPE_MISSILE_SEEK_AMMO,
+  OUTFIT_TYPE_MISSILE_SEEK_AMMO,          /**< Seeker missile ammo. */
-  OUTFIT_TYPE_MISSILE_SEEK_SMART,
+  OUTFIT_TYPE_MISSILE_SEEK_SMART,         /**< ATM equivalent to SEEK. */
-  OUTFIT_TYPE_MISSILE_SEEK_SMART_AMMO,
+  OUTFIT_TYPE_MISSILE_SEEK_SMART_AMMO,    /**< @todo atm equivalent to SEEK_AMMI. */
-  OUTFIT_TYPE_MISSILE_SWARM,
+  OUTFIT_TYPE_MISSILE_SWARM,              /**< @todo Swarm missile launcher. */
-  OUTFIT_TYPE_MISSILE_SWARM_AMMO,
+  OUTFIT_TYPE_MISSILE_SWARM_AMMO,         /**< @todo Swarm missile ammo. */
-  OUTFIT_TYPE_MISSILE_SWARM_SMART,
+  OUTFIT_TYPE_MISSILE_SWARM_SMART,        /**< @todo Same as SWARM. */
-  OUTFIT_TYPE_MISSILE_SWARM_SMART_AMMO,
+  OUTFIT_TYPE_MISSILE_SWARM_SMART_AMMO,   /**< @todo Same as SWARM_AMMO. */
-  OUTFIT_TYPE_MODIFICATION,
+  OUTFIT_TYPE_MODIFICATION,               /**< Modifies the ship afterburn capability. */
-  OUTFIT_TYPE_AFTERBURNER,
+  OUTFIT_TYPE_AFTERBURNER,                /**< Gives the ship afterburn capability. */
-  OUTFIT_TYPE_MAP,
+  OUTFIT_TYPE_JAMMER,                     /**< Used to nullify seeker missiles. */
-  OUTFIT_TYPE_JAMMER,
+  OUTFIT_TYPE_MAP,                        /**< Give the player more knowledge about systems. */
-  OUTFIT_TYPE_SENTINEL  /* Indicates last type. */
+  OUTFIT_TYPE_SENTINEL                    /**< Indicates last type. */
 } OutfitType;
 
+/**
+ * @enum DamageType
+ *
+ * @brief Different types of damage.
+ */
 typedef enum DamageType_ {
-  DAMAGE_TYPE_NULL,
+  DAMAGE_TYPE_NULL,       /**< NULL. */ 
-  DAMAGE_TYPE_ENERGY,
+  DAMAGE_TYPE_ENERGY,     /**< Energy-based weapons. */
-  DAMAGE_TYPE_KINETIC,
+  DAMAGE_TYPE_KINETIC,    /**< Physic impact weapons. */
-  DAMAGE_TYPE_ION,
+  DAMAGE_TYPE_ION,        /**< Ion-based weapons. */
-  DAMAGE_TYPE_RADIATION
+  DAMAGE_TYPE_RADIATION   /**< Radioactive weapons. */
 } DamageType;
 
 /**
@@ -183,25 +194,29 @@ typedef struct OutfitJammerData_ {
   double energy;      /**< Energy it uses to run. */
 } OutfitJammerData;
 
-/* An outfit depends a lot on the type. */
+/**
+ * @struct Outfit
+ *
+ * @brief A ship outfit, depends radically on the type.
+ */
 typedef struct Outfit_ {
-  char* name;
+  char* name;               /**< Name of the outfit. */
 
   /* General specs. */
-  int max;
+  int max;                  /**< Max amount one can own. */
-  int tech;
+  int tech;                 /**< Tech needed to sell it. */
-  int mass;
+  int mass;                 /**< How much weapon capacity is needed. */
 
   /* Store stuff. */
-  unsigned int price;
+  unsigned int price;       /**< Base sell price. */
-  char* description;
+  char* description;        /**< Store description. */
 
-  glTexture* gfx_store; /* Store graphic. */
+  glTexture* gfx_store;     /**< Store graphic. */
 
-  int properties; /* Properties stored bitwise. */
+  int properties;           /**< Properties stored bitwise. */
 
   /* Type dependant. */
-  OutfitType type;
+  OutfitType type;          /**< Properties stored bitwise. */
   union {
     OutfitBoltData          blt;  /**< BOLT. */
     OutfitBeamData          bem;  /**< BEAM. */