From eae283417fac0fa010d82ea864d23d47ff429b85 Mon Sep 17 00:00:00 2001 From: Allanis Date: Thu, 5 Sep 2013 13:32:30 +0100 Subject: [PATCH] [Add] Partially documented pilot.c --- src/pilot.c | 168 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 115 insertions(+), 53 deletions(-) diff --git a/src/pilot.c b/src/pilot.c index a229d3b..6f52454 100644 --- a/src/pilot.c +++ b/src/pilot.c @@ -19,30 +19,28 @@ #include "map.h" #include "pilot.h" -#define XML_ID "Fleets" /* XML section identifier. */ -#define XML_FLEET "fleet" +#define XML_ID "Fleets" /**< XML section identifier. */ +#define XML_FLEET "fleet -#define FLEET_DATA "../dat/fleet.xml" +#define FLEET_DATA "../dat/fleet.xml" /**< Where to find fleet data. */ -#define PILOT_CHUNK 32 /* Chunks to increment pilot_stack by. */ +#define PILOT_CHUNK 32 /**< Chunks to increment pilot_stack by. */ -/* Stack of pilot id's to assure uniqueness. */ -static unsigned int pilot_id = PLAYER_ID; - -/* id for special mission cargo. */ -static unsigned int mission_cargo_id = 0; +/* ID generators. */ +static unsigned int pilot_id = PLAYER_ID; /**< Stack of pilod ids to assure uniqueness. */ +static unsigned int mission_cargo_id = 0; /**< ID generator for specail mission cargo. */ /* Stack of pilots. */ -Pilot** pilot_stack = NULL; /* Not static, it is used in player.c and weapon.c and ai.c */ -int pilot_nstack = 0; -static int pilot_mstack = 0; +Pilot** pilot_stack = NULL; /**< Not static, it is used in player.c and weapon.c and ai.c */ +int pilot_nstack = 0; /**< Same. */ +static int pilot_mstack = 0; /** Memory allocated for pilot_stack. */ extern Pilot* player; extern unsigned int player_crating; /* Stack of fleets. */ -static Fleet* fleet_stack = NULL; -static int nfleets = 0; +static Fleet* fleet_stack = NULL; /** Fleet stack. */ +static int nfleets = 0; /** Number of fleets. */ /* External. */ /* AI. */ @@ -67,7 +65,13 @@ static Fleet* fleet_parse(const xmlNodePtr parent); static void pilot_dead(Pilot* p); static int pilot_oquantity(Pilot* p, PilotOutfit* w); -/* Get the next pilot based on id. */ +/** + * @fn unsinged int pilot_getNextID(const unsigned int id) + * + * @brief Get the next pilot on id. + * @param id ID of current pilot. + * @return ID of next pilot of PLAYER_ID if no next pilot. + */ unsigned int pilot_getNextID(const unsigned int id) { /* Binary search. */ int l, m, h; @@ -84,7 +88,11 @@ unsigned int pilot_getNextID(const unsigned int id) { else return pilot_stack[m+1]->id; } -/* Get the nearest enemy to the pilot -- Tamir's (insightful) request. */ +/** + * @brief Get the nearest enemy to the pilot. + * @param p Pilot to get his nearest enemy. + * @param ID of her nearest enemy. + */ unsigned int pilot_getNearestEnemy(const Pilot* p) { unsigned int tp; int i; @@ -101,27 +109,13 @@ unsigned int pilot_getNearestEnemy(const Pilot* p) { return tp; } -/* Get the nearest hostile enemy to the player. */ -unsigned pilot_getNearestHostile(void) { - unsigned int tp; - int i; - double d, td; - - tp = PLAYER_ID; - d = 0; - for(i = 0; i < pilot_nstack; i++) - if(pilot_isFlag(pilot_stack[i], PILOT_HOSTILE) || - areEnemies(FACTION_PLAYER, pilot_stack[i]->faction)) { - td = vect_dist(&pilot_stack[i]->solid->pos, &player->solid->pos); - if(!pilot_isDisabled(pilot_stack[i]) && ((tp == PLAYER_ID) || (td < d))) { - d = td; - tp = pilot_stack[i]->id; - } - } - return tp; -} - -/* Get the nearest pilot. */ +/** + * @fn unsinged int pilot_getNearesetPilot(const Pilot* p) + * + * @brief Get the nearest pilot to a pilot. + * @param p Pilot to get her nearest pilot. + * @return The nearest pilot. + */ unsigned int pilot_getNearestPilot(const Pilot* p) { unsigned int tp; int i; @@ -929,14 +923,21 @@ void pilot_addHook(Pilot* pilot, int type, int hook) { pilot->hook = hook; } -/* ==Init pilot.=========================================== */ -/* ship : Ship pilot is flying. */ -/* name : Pilot's name, if NULL, ships name will be used. */ -/* dir : Initial facing direction. (radians) */ -/* vel : Initial velocity. */ -/* pos : Initial position. */ -/* flags : Tweaking the pilot. */ -/* ======================================================== */ +/** + * @fn void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction, + * AI_Profile* ai, const double dir, const Vec2* pos, + * const Vec2* vel, const int flags) + * + * @brief Initialize pilot. + * @param ship Ship pilot will be flying. + * @param name Pilots name, if NULL ships name will be used. + * @param faction Faction of the pilot. + * @param ai AI profile to use for the pilot. + * @param dir Initial direction to face (radians). + * @param vel Initial velocity. + * @param pos Initial position. + * @param flags Used for tweaking the pilot. + */ void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction, AI_Profile* ai, const double dir, const Vec2* pos, const Vec2* vel, const int flags) { @@ -1028,7 +1029,18 @@ void pilot_init(Pilot* pilot, Ship* ship, char* name, int faction, pilot->update = pilot_update; } -/* Create a new pilot - Params are same as pilot_init. Return pilot's id. */ +/** + * @fn unsigned int pilot_create(Ship* ship, char* name, int faction, + * AI_Profile* ai, const double dir, const Vec2* pos, + * const Vec2* vel, const int flags) + * + * @brief Create a new pilot. + * + * See pilot_init for parameters. + * @return Pilots id. + * + * @sa pilot_init + */ unsigned int pilot_create(Ship* ship, char* name, int faction, AI_Profile* ai, const double dir, const Vec2* pos, const Vec2* vel, const int flags) { @@ -1056,6 +1068,18 @@ unsigned int pilot_create(Ship* ship, char* name, int faction, return dyn->id; } +/** + * @fn Pilot* pilot_CreateEmpty(Ship* ship, char* name, + * int faction, AI_Profile* ai, const int flags) + * + * @brief Create a pilot without adding it to the stack. + * @param ship Ship for the pilot to use. + * @param name Name of the pilot ship (NULL uses ship name). + * @param faction Faction of the ship. + * @param ai AI to use. + * @param flags Flags for tweaking, PILOT_EMPTY is added. + * @return Pointer to the new pilot (not added to stack). + */ Pilot* pilot_createEmpty(Ship* ship, char* name, int faction, AI_Profile* ai, const int flags) { @@ -1065,7 +1089,13 @@ Pilot* pilot_createEmpty(Ship* ship, char* name, return dyn; } -/* Copy src pilot to dest. */ +/** + * @fn Pilot* pilot_copy(Pilot* src) + * + * @brief Copies src pilot to dest. + * @param src Pilot to copy. + * @return Copy of src. + */ Pilot* pilot_copy(Pilot* src) { Pilot* dest = malloc(sizeof(Pilot)); memcpy(dest, src, sizeof(Pilot)); @@ -1097,7 +1127,12 @@ Pilot* pilot_copy(Pilot* src) { return dest; } -/* Frees and cleans up a pilot. */ +/** + * @fn void pilot_free(Pilot* p) + * + * @brief Free and cleans up a pilot. + * @param p Pilot to free. + */ void pilot_free(Pilot* p) { if(player == p) player = NULL; solid_free(p->solid); @@ -1108,7 +1143,12 @@ void pilot_free(Pilot* p) { free(p); } -/* Destroy pilot from stack. */ +/** + * @fn void pilot_destroy(Pilot* p) + * + * @brief Destroy pilot from stack. + * @param p Pilot to destroy. + */ void pilot_destroy(Pilot* p) { int i; @@ -1125,7 +1165,11 @@ void pilot_destroy(Pilot* p) { memmove(&pilot_stack[i], &pilot_stack[i+1], (pilot_nstack-i)*sizeof(Pilot*)); } -/* Free the prisoned pilot! */ +/** + * @fn voud pilots_free(void) + * + * @brief Free the pilot stack. + */ void pilots_free(void) { int i; for(i = 0; i < pilot_nstack; i++) @@ -1136,7 +1180,11 @@ void pilots_free(void) { pilot_nstack = 0; } -/* Clean up the pilots - Leaves the player. */ +/** + * @fn void pilots_clean(void) + * + * @brief Clean up the pilot stack - Leave the player. + */ void pilots_clean(void) { int i; for(i = 0; i < pilot_nstack; i++) @@ -1152,6 +1200,11 @@ void pilots_clean(void) { pilot_nstack = 1; } +/** + * @fn void player_cleanAll(void) + * + * @brief Even cleans up the player. + */ void pilots_cleanAll(void) { pilots_clean(); if(player != NULL) { @@ -1161,7 +1214,12 @@ void pilots_cleanAll(void) { pilot_nstack = 0; } -/* Update all pilots. */ +/** + * @fn void pilots_update(double dt) + * + * @brief Updates all the pilots. + * @param dt Delta tick for the update. + */ void pilots_update(double dt) { int i; for(i = 0; i < pilot_nstack; i++) { @@ -1181,7 +1239,11 @@ void pilots_update(double dt) { } } -/* Render all the pilots. */ +/** + * @fn void pilots_render(void) + * + * @brief Render all the pilots. + */ void pilots_render(void) { int i; for(i = 0; i < pilot_nstack; i++) {