From b44fb505cdb5fab298e799fe0c137b81b3bb7113 Mon Sep 17 00:00:00 2001 From: Allanis Date: Mon, 9 Sep 2013 01:31:14 +0100 Subject: [PATCH] [Add] Documented Pilot.h --- src/pilot.h | 99 ++++++++++++++++++++++++++++++++++------------------- 1 file changed, 63 insertions(+), 36 deletions(-) diff --git a/src/pilot.h b/src/pilot.h index c4bf37b..abaef21 100644 --- a/src/pilot.h +++ b/src/pilot.h @@ -7,29 +7,29 @@ #include "sound.h" #include "economy.h" -#define PLAYER_ID 1 +#define PLAYER_ID 1 /**< Player pilot ID. */ -#define HYPERSPACE_ENGINE_DELAY 3000 /* Warm up the engines. */ -#define HYPERSPACE_FLY_DELAY 5000 /* Time taken to hyperspace. */ -#define HYPERSPACE_STARS_BLUR 2000 /* Time stars blur. */ -#define HYPERSPACE_STARS_LENGTH 1000 /* Length the stars blur to at max. */ -#define HYPERSPACE_FADEOUT 1000 /* Time fadeout. */ -#define HYPERSPACE_FUEL 100 /* Amount of fuel taken. */ +#define HYPERSPACE_ENGINE_DELAY 3000 /**< Warm up the engines. */ +#define HYPERSPACE_FLY_DELAY 5000 /**< Time taken to hyperspace. */ +#define HYPERSPACE_STARS_BLUR 2000 /**< Time stars blur. */ +#define HYPERSPACE_STARS_LENGTH 1000 /**< Length the stars blur to at max. */ +#define HYPERSPACE_FADEOUT 1000 /**< Time fadeout. */ +#define HYPERSPACE_FUEL 100 /**< Amount of fuel taken. */ /* Aproximation for pilot size. */ -#define PILOT_SIZE_APROX 0.8 -#define PILOT_DISABLED_ARMOUR 0.3 /* Based on armour percentage. */ +#define PILOT_SIZE_APROX 0.8 /**< Approximation for pilot size. */ +#define PILOT_DISABLED_ARMOUR 0.3 /**< Armour % that makes it disabled. */ /* Hooks. */ -#define PILOT_HOOK_NONE 0 /* No hook. */ -#define PILOT_HOOK_DEATH 1 /* Pilot died. */ -#define PILOT_HOOK_BOARD 2 /* Pilot got boarded. */ -#define PILOT_HOOK_DISABLE 3 /* Pilot got disabled. */ +#define PILOT_HOOK_NONE 0 /**< No hook. */ +#define PILOT_HOOK_DEATH 1 /**< Pilot died. */ +#define PILOT_HOOK_BOARD 2 /**< Pilot got boarded. */ +#define PILOT_HOOK_DISABLE 3 /**< Pilot got disabled. */ /* Flags. */ -#define pilot_isFlag(p,f) (p->flags & (f)) -#define pilot_setFlag(p,f) (p->flags |= (f)) -#define pilot_rmFlag(p,f) (p->flags ^= (f)) +#define pilot_isFlag(p,f) (p->flags & (f)) /**< Check if flag f is set on pilot p. */ +#define pilot_setFlag(p,f) (p->flags |= (f)) /**< Set flag f on pilot p. */ +#define pilot_rmFlag(p,f) (p->flags ^= (f)) /**< Remove flag f on pilot p. */ /* Creation. */ #define PILOT_PLAYER (1<<0) /**< Pilot is a player. */ #define PILOT_HASTURRET (1<<20) /**< Pilot has turrets. */ @@ -50,20 +50,30 @@ #define PILOT_DELETE (1<<15) /**< Pilot will get delete asap. */ /* Just makes life simpler. */ -#define pilot_isPlayer(p) ((p)->flags & PILOT_PLAYER) -#define pilot_isDisabled(p) ((p)->flags & PILOT_DISABLED) +#define pilot_isPlayer(p) ((p)->flags & PILOT_PLAYER) /**< Check if pilot is a player. */ +#define pilot_isDisabled(p) ((p)->flags & PILOT_DISABLED) /**< Check if pilot is disabled. */ +/** + * @struct PilotOutfit + * + * @brief Store an outfit the pilot has. + */ typedef struct PilotOutfit_ { - Outfit* outfit; /* Associated outfit. */ - int quantity; /* Number of outfits of this type that the pilot has. */ - unsigned int timer; /* Used to store last used weapon time. */ + Outfit* outfit; /**< Associated outfit. */ + int quantity; /**< Number of outfits of this type that the pilot has. */ + + unsigned int timer; /**< Used to store last used weapon time. */ } PilotOutfit; -/* Pilot commodity. */ +/** + * @struct PilotCommodity + * + * @brief Store a pilot commodity. + */ typedef struct PilotCommodity_ { - Commodity* commodity; - int quantity; - unsigned int id; /* Special mission id for cargo. */ + Commodity* commodity; /**< Assotiated commodity. */ + int quantity; /**< Amount player has. */ + unsigned int id; /**< Special mission id for cargo, 0 means none. */ } PilotCommodity; /** @@ -74,7 +84,7 @@ typedef struct PilotCommodity_ { typedef struct Pilot_ { unsigned int id; /**< Pilots id. */ char* name; /**< Pilot's name (if unique). */ - char* title; /**< Title - Usuall indicating special properties - TODO. */ + char* title; /**< Title - Usuall indicating special properties - @todo. */ int faction; /**< Pilot faction. */ @@ -142,22 +152,39 @@ typedef struct Pilot_ { Task* task; /**< Current action. */ } Pilot; -/* Fleets. */ +/** + * @struct FleetPilot + * + * @brief Represents a pilot in a fleet. + * + * @sa Fleet + * @sa Pilot + */ typedef struct FleetPilot_ { - Ship* ship; /* Ship that the pilot is flying. */ - char* name; /* For special 'unique' names. */ - int chance; /* Chance of this pilot appearing in the fleet. */ - AI_Profile* ai; /* AI different of fleets global ai. */ + Ship* ship; /**< Ship that the pilot is flying. */ + char* name; /**< For special 'unique' names. */ + int chance; /**< Chance of this pilot appearing in the fleet. */ + AI_Profile* ai; /**< AI different of fleets global ai. */ } FleetPilot; +/** + * @struct Fleet + * + * @brief Represents a fleet. + * + * Fleets are used to create pilots, both from being in a system and from + * mission triggers. + * + * @sa FleetPilot + */ typedef struct Fleet_ { - char* name; /* Fleet name, used as an identifier. */ - int faction; /* Faction of the fleet. */ + char* name; /**< Fleet name, used as an identifier. */ + int faction; /**< Faction of the fleet. */ - AI_Profile* ai; /* A useable profile. */ + AI_Profile* ai; /**< AI profile to use. */ - FleetPilot* pilots; /* The pilots in the fleet. */ - int npilots; /* Total number of pilots. */ + FleetPilot* pilots; /**< The pilots in the fleet. */ + int npilots; /**< Total number of pilots. */ } Fleet; /* Grabing pilot crap. */