From 4674fe7248a6a6c8aaa015e7e55ee670eba6b759 Mon Sep 17 00:00:00 2001 From: Allanis Date: Sun, 22 Sep 2013 16:07:44 +0100 Subject: [PATCH] [Add] Documented faction.c --- src/faction.c | 164 ++++++++++++++++++++++++++++++++++++++++++-------- src/pack.c | 2 +- 2 files changed, 141 insertions(+), 25 deletions(-) diff --git a/src/faction.c b/src/faction.c index a9de2e7..79ef5cc 100644 --- a/src/faction.c +++ b/src/faction.c @@ -1,3 +1,9 @@ +/** + * @file faction.c + * + * @brief Handle the Lephisto factions. + */ + #include #include @@ -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* longname; /* Long name. */ + char* name; /**< Normal name. */ + char* longname; /**< Long name. */ /* Enemies. */ - int* enemies; - int nenemies; + int* enemies; /**< Enemies by ID of the faction. */ + int nenemies; /**< Number of enemies. */ /* Allies. */ - int* allies; - int nallies; + int* allies; /**< Allies by ID of the faction. */ + 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 int faction_nstack = 0; +static Faction* faction_stack = NULL; /**< Faction stack. */ +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; diff --git a/src/pack.c b/src/pack.c index ed12afc..5caaa91 100644 --- a/src/pack.c +++ b/src/pack.c @@ -9,7 +9,7 @@ #include "log.h" #include "md5.h" -/* +/** * @file pack.c * * @brief Stores data in funky format.