[Add] Documented faction.c

src/faction.c

@@ -1,3 +1,9 @@
+/**
+ * @file faction.c
+ *
+ * @brief Handle the Lephisto factions.
+ */
+
 #include <malloc.h>
 #include <string.h>
 
@@ -11,27 +17,32 @@
 #define XML_FACTION_ID    "Factions" /* XML section id. */
 #define XML_FACTION_TAG   "faction"
 
-#define FACTION_DATA "../dat/faction.xml"
+#define FACTION_DATA "../dat/faction.xml" /**< Faction xml file. */
 
-#define PLAYER_ALLY   70 /* Above this, player is considered ally. */
+#define PLAYER_ALLY   70 /**< Above this, player is considered ally. */
 
+/**
+ * @struct Faction.
+ *
+ * @brief Represents a faction.
+ */
 typedef struct Faction_ {
-  char* name;     /* Normal name. */
+  char* name;     /**< Normal name. */
-  char* longname; /* Long name. */
+  char* longname; /**< Long name. */
 
   /* Enemies. */
-  int*  enemies;
+  int*  enemies;    /**< Enemies by ID of the faction. */
-  int   nenemies;
+  int   nenemies;   /**< Number of enemies. */
 
   /* Allies. */
-  int*  allies;
+  int*  allies;     /**< Allies by ID of the faction. */
-  int   nallies;
+  int   nallies;    /**< Number of allies. */
 
-  int player; /* Standing with player - from -100 to 100. */
+  int player;       /**< Standing with player - from -100 to 100. */
 } Faction;
 
-static Faction* faction_stack = NULL;
+static Faction* faction_stack = NULL;   /**< Faction stack. */
-static int faction_nstack = 0;
+static int faction_nstack = 0;          /**< Number of factions in the faction stack. */
 
 /* Static. */
 static int faction_isFaction(int f);
@@ -42,7 +53,13 @@ static void faction_parseSocial(xmlNodePtr parent);
 int pfaction_save(xmlTextWriterPtr writer);
 int pfaction_load(xmlNodePtr parent);
 
-/* Return the faction of name "name". */
+/**
+ * @fn int faction_get(const char* name)
+ *
+ * @brief Get a faction ID by name.
+ *    @param name Name of the faction to seek.
+ *    @return ID of the faction.
+ */
 int faction_get(const char* name) {
   int i;
   for(i = 0; i < faction_nstack; i++)
@@ -56,7 +73,13 @@ int faction_get(const char* name) {
   return -1;
 }
 
-/* Return the faction's name. */
+/**
+ * @fn char* faction_name(int f)
+ *
+ * @brief Get a factions short name.
+ *    @param f Faction to get the name of.
+ *    @return Name of the faction.
+ */
 char* faction_name(int f) {
   if((f < 0) || (f >= faction_nstack)) {
     WARN("Faction id '%d' is invalid.", f);
@@ -65,14 +88,25 @@ char* faction_name(int f) {
   return faction_stack[f].name;
 }
 
-/* Return the faction's long name (formal). */
+/**
+ * @fn char* faction_longname(int f)
+ *
+ * @brief Get the factions long name (formal).
+ *    @param f Faction to get the name of.
+ *    @return The factions long name.
+ */
 char* faction_longname(int f) {
   if(faction_stack[f].longname != NULL)
     return faction_stack[f].longname;
   return faction_stack[f].name;
 }
 
-/* Sanitize player faction standing. */
+/**
+ * @fn static void faction_sanitizePlayer(Faction* faction)
+ *
+ * @brief Sanitizes player faction standing.
+ *    @param faction Faction to sanitize.
+ */
 static void faction_sanitizePlayer(Faction* faction) {
   if(faction->player > 100)
     faction->player = 100;
@@ -80,7 +114,17 @@ static void faction_sanitizePlayer(Faction* faction) {
     faction->player = -100;
 }
 
-/* Modify the player's standing with a faction. */
+/**
+ * @fn void faction_modPlayer(int f, int mod)
+ *
+ * @brief Modifies the players standing with a faction.
+ *
+ * Affects enemies and allies too.
+ *    @param f Faction to modify players standing.
+ *    @param mod Modifier to modify by.
+ *
+ * @sa faction_modPlayerRaw
+ */
 void faction_modPlayer(int f, int mod) {
   int i;
   Faction* faction, *ally, *enemy;
@@ -113,7 +157,15 @@ void faction_modPlayer(int f, int mod) {
   }
 }
 
-/* Modifies a players standing with a faction without affecting others. */
+/**
+ * @fn void faction_modPlayerRaw(int f, int mod)
+ *
+ * @brief Modifies the players standing without affecting others.
+ *    @param f Faction whose standing to modify.
+ *    @param mod Amount to modify standing by.
+ *
+ * @sa faction_modPlayer
+ */
 void faction_modPlayerRaw(int f, int mod) {
   Faction* faction;
 
@@ -128,7 +180,13 @@ void faction_modPlayerRaw(int f, int mod) {
   faction_sanitizePlayer(faction);
 }
 
-/* Get the player's standing with a faction. */
+/**
+ * @fn int faction_getPlayer(int f)
+ *
+ * @brief Get the players standing with a faction.
+ *    @param f Faction to get standing from.
+ *    @return The standing the player has with the faction.
+ */
 int faction_getPlayer(int f) {
   if(faction_isFaction(f)) {
     return faction_stack[f].player;
@@ -138,7 +196,15 @@ int faction_getPlayer(int f) {
   }
 }
 
-/* Get the colour of the faction based on its standing with the player. */
+/**
+ * @fn glColour* faction_getColour(int f)
+ *
+ * @brief Get the colour of the faction basewd on its standing with the player.
+ * 
+ * Used to unify the colour checks all over.
+ *    @param f Faction to get the colour of based on players standing.
+ *    @return Pointer to the colour.
+ */
 glColour* faction_getColour(int f) {
   if(f < 0) return &cInert;
   else if(areAllies(FACTION_PLAYER, f))   return &cFriend;
@@ -146,7 +212,13 @@ glColour* faction_getColour(int f) {
   else return &cNeutral;
 }
 
-/* Return the players standing. */
+/**
+ * @fn char* faction_getStanding(int mod)
+ *
+ * @brief Get the players standing in human readable form.
+ *    @param mod Players standing.
+ *    @return Human readable players standing.
+ */
 static char* player_standings[] = {
   "Hero",     /* 0 */
   "Admired",
@@ -174,7 +246,14 @@ char* faction_getStanding(int mod) {
 }
 #undef STANDING
 
-/* Return 1 if Faction a and b are enemies. */
+/**
+ * @fn int areEnemies(int a, int b)
+ *
+ * @brief Check whether two factions are enemies.
+ *    @param a Faction A.
+ *    @param b Faction B.
+ *    @return 1 if A and B are enemies, 0 otherwise.
+ */
 int areEnemies(int a, int b) {
   Faction* fa, *fb;
   int i = 0;
@@ -231,7 +310,14 @@ int areEnemies(int a, int b) {
   return 0;
 }
 
-/* Return 1 if Faction a and b are allies. */
+/**
+ * @fn int areAllies(int a, int b)
+ *
+ * @brief Check whether two factions are allies or not.
+ *    @param a Faction A.
+ *    @param b Faction B.
+ *    @return 1 if A and B are allies, 0 otherwise.
+ */
 int areAllies(int a, int b) {
   Faction* fa, *fb;
   int i;
@@ -291,7 +377,13 @@ int areAllies(int a, int b) {
   return 0;
 }
 
-/* Return true if f is a faction. */
+/**
+ * @fn static int faction_isFaction(int f)
+ *
+ * @brief Check whether or not a faction is valid.
+ *    @param f Faction to check for validity.
+ *    @return 1 if faction is valid, 0 otherwise.
+ */
 static int faction_isFaction(int f) {
   if((f < 0) || (f >= faction_nstack))
     return 0;
@@ -366,7 +458,12 @@ static void faction_parseSocial(xmlNodePtr parent) {
   } while(xml_nextNode(node));
 }
 
-/* Load all the factions. */
+/**
+ * @fn int factions_load(void)
+ *
+ * @brief Loads up all the factions from the data file.
+ *    @return 0 on success.
+ */
 int factions_load(void) {
   uint32_t bufsize;
   char* buf = pack_readfile(DATA, FACTION_DATA, &bufsize);
@@ -423,6 +520,11 @@ int factions_load(void) {
   return 0;
 }
 
+/**
+ * @fn void factions_free(void)
+ *
+ * @brief Frees the factions.
+ */
 void factions_free(void) {
   int i;
 
@@ -438,6 +540,13 @@ void factions_free(void) {
   faction_nstack = 0;
 }
 
+/**
+ * @fn int pfaction_save(xmlTextWriterPtr writer)
+ *
+ * @brief Save players standings with the factions.
+ *    @param writer The XML writer to use.
+ *    @return 0 on success.
+ */
 int pfaction_save(xmlTextWriterPtr writer) {
   int i;
 
@@ -458,6 +567,13 @@ int pfaction_save(xmlTextWriterPtr writer) {
   return 0;
 }
 
+/**
+ * @fn int pfaction_load(xmlNodePtr parent)
+ *
+ * @brief Load up the players faction standings.
+ *    @param parent Parent xml node to read from.
+ *    @return 0 on success.
+ */
 int pfaction_load(xmlNodePtr parent) {
   xmlNodePtr node, cur;
   char* str;

src/pack.c

@@ -9,7 +9,7 @@
 #include "log.h"
 #include "md5.h"
 
-/*
+/**
  * @file pack.c
  *
  * @brief Stores data in funky format.