From ca4c910ec878c7fff92093d1a815493c842fef36 Mon Sep 17 00:00:00 2001 From: Allanis Date: Sat, 31 Aug 2013 14:19:36 +0100 Subject: [PATCH] [Add] Preliminary doxygen support. --- bin/Makefile | 15 ++++-- src/ai.c | 112 ++++++++++++++++++++++++++++++++++--------- src/lephisto.c | 127 +++++++++++++++++++++++++++++++++---------------- src/lephisto.h | 36 ++++++++------ 4 files changed, 208 insertions(+), 82 deletions(-) diff --git a/bin/Makefile b/bin/Makefile index f344cc3..3e9b69c 100644 --- a/bin/Makefile +++ b/bin/Makefile @@ -62,6 +62,8 @@ DATA = data DATAFILES = $(VERSIONFILE) $(DATA_AI) $(DATA_GFX) $(DATA_XML) $(DATA_SND) $(DATA_MISN) # TARGETS. +.PHONY: all lua pack mkspr data utils docs clean purge + %.o: %.c %.h @$(CC) -c $(CFLAGS) -o $@ $< @echo -e "\tCC $@" @@ -89,10 +91,17 @@ data: pack $(DATAFILES) ../src/pack.c ../utils/pack/main.c utils: mksprite +docs: + @(cd docs/doxygen; doxygen) + clean: - @echo -e "\tRemoving data.." - rm -rf $(OBJS) $(APPNAME) $(DATA) pack core mksprite *.out a.txt - @echo -e "\tCleaning utils." + @echo -e "\tRemoving data" + @rm -f $(DATA) + @echo -e "\tRemoving object files" + @rm -f $(OBJS) + +purge: clean + @echo -e "\tCleaning utilites" @(cd ../utils/pack; $(MAKE) clean) @(cd ../utils/mkspr; $(MAKE) clean) @echo -e "\tCleaning Lua" diff --git a/src/ai.c b/src/ai.c index d205296..3c2e082 100644 --- a/src/ai.c +++ b/src/ai.c @@ -20,7 +20,12 @@ #include "lluadef.h" #include "ai.h" -/* == AI ====================================================== +/** + * @file ai.c + * + * @brief Controls the Pilot AI. + * + * == AI ====================================================== * * -- Goal (Task) based AI with additional optimization. * AI uses the goal (task) based AI approach with tasks scripted @@ -43,7 +48,7 @@ * -- If task is NULL, AI will run "control" task. * -- Task is continued every frame. * -- "control" task is a special task that *must* exist in - * any given Pilot AI (missiles, and suck will use "seek". + * any given Pilot AI (missiles, and suck will use "seek". * -- "control" task is not permanent, but transitory. * -- "control" task sets another task. * -- "control" task is also run at a set rate (depending on @@ -51,24 +56,28 @@ * (task). */ -/* Register a number constant n to name s (syntax is just like lua_regfunc). */ +/** + * @def lua_regnumber(l, s, n) + * + * @brief Register a number constant n to name s (syntax is just like lua_regfunc). + */ #define lua_regnumber(l,s,n) (lua_pushnumber(l,n), lua_setglobal(l,s)) /* Ai flags. */ -#define ai_setFlag(f) (pilot_flags |= f) -#define ai_isFlag(f) (pilot_flags & f) +#define ai_setFlag(f) (pilot_flags |= f) /**< Set pilot flag f */ +#define ai_isFlag(f) (pilot_flags & f) /**< Check pilot flag f */ /* Flags. */ -#define AI_PRIMARY (1<<0) /* Firing primary weapon. */ -#define AI_SECONDARY (1<<1) /* Firing secondary weapon. */ +#define AI_PRIMARY (1<<0) /**< Firing primary weapon. */ +#define AI_SECONDARY (1<<1) /**< Firing secondary weapon. */ /* file info. */ -#define AI_PREFIX "../scripts/ai/" -#define AI_SUFFIX ".lua" -#define AI_INCLUDE "include/" +#define AI_PREFIX "../scripts/ai/" /**< AI file prefix. */ +#define AI_SUFFIX ".lua" /**< AI file suffix. */ +#define AI_INCLUDE "include/" /**< Where to search for includes. */ /* AI profiles. */ -static AI_Profile* profiles = NULL; -static int nprofiles = 0; +static AI_Profile* profiles = NULL; /**< Array of AI_Profiles loaded. */ +static int nprofiles = 0; /**< Number of AI_Profiles loaded. */ /* Extern pilot hacks. */ extern Pilot** pilot_stack; @@ -211,11 +220,18 @@ static int pilot_flags = 0; static int pilot_target = 0; /* Ai status: 'Create' functions that can't be used elsewhere. */ -#define AI_STATUS_NORMAL 1 -#define AI_STATUS_CREATE 2 +#define AI_STATUS_NORMAL 1 /**< Normal AI function behaviour. */ +#define AI_STATUS_CREATE 2 /**< AI is running create function. */ static int ai_status = AI_STATUS_NORMAL; -/* Attempt to run a function. */ +/** + * @fn static void ai_run(lua_State* L, const char* funcname) + * + * @brief Attemps to run a function. + * + * @param[in] L Lua state to run function on. + * @param[in] funcname Function to run. + */ static void ai_run(lua_State* L, const char* funcname) { lua_getglobal(L, funcname); if(lua_pcall(L, 0, 0, 0)) @@ -224,13 +240,25 @@ static void ai_run(lua_State* L, const char* funcname) { cur_pilot->name, funcname, lua_tostring(L,-1)); } -/* Destroy the AI part of the pilot. */ +/** + * @fn void ai_destroy(Pilot* p) + * + * @brief Destroys the ai part of the pilot. + * + * @param[in] p Pilot to destroy it's AI part. + */ void ai_destroy(Pilot* p) { if(p->task) ai_freetask(p->task); } -/* Init the AI stuff. Which is basically Lua. */ +/** + * @fn int ai_init(void) + * + * @brief Initializes the AI stuff which is basically Lua. + * + * @return 0 on no errors. + */ int ai_init(void) { char** files; uint32_t nfiles, i; @@ -258,7 +286,14 @@ int ai_init(void) { return 0; } -/* Init an IA_Profile and add it to the stack. */ +/** + * @fn static int ai_loadProfile(char* filename) + * + * @brief Initializes an AI_Profile and adds it to the stack. + * + * @param[in] filename File to create the profile from. + * @return 0 on no error. + */ static int ai_loadProfile(char* filename) { char* buf = NULL; uint32_t bufsize = 0; @@ -308,7 +343,13 @@ static int ai_loadProfile(char* filename) { return 0; } -/* Get the AI_Profile with name. */ +/* @fn AI_Profile* ai_getProfile(char* name) + * + * @brief Get the AI_Profile by name. + * + * @param[in] name Name of the profile to get. + * @return The profile or NULL on error. + */ AI_Profile* ai_getProfile(char* name) { if(profiles == NULL) return NULL; @@ -321,7 +362,11 @@ AI_Profile* ai_getProfile(char* name) { return NULL; } -/* Clean up global AI */ +/** + * @fn void ai_exit(void) + * + * @brief Clean up the gloabl AI. + */ void ai_exit(void) { int i; for(i = 0; i < nprofiles; i++) { @@ -331,7 +376,13 @@ void ai_exit(void) { free(profiles); } -/* Heart of hearts of the ai!! Brains of the pilot. */ +/** + * @fn void ai_think(Pilot* pilot) + * + * @brief Heart of the AI, brains of the pilot. + * + * @param pilot Pilot that needs to think. + */ void ai_think(Pilot* pilot) { lua_State* L; @@ -370,7 +421,14 @@ void ai_think(Pilot* pilot) { if(ai_isFlag(AI_SECONDARY)) pilot_shoot(pilot, pilot_target, 1); /* Secondary. */ } -/* Pilot is attacked. */ +/** + * @fn void ai_attacked(Pilot* attacked, const unsigned int attacker) + * + * @brief Trigger the attacked() function in the Pilots AI. + * + * @param attacked Pilot that is attacked. + * @param[in] attacker ID of the attacker. + */ void ai_attacked(Pilot* attacked, const unsigned int attacker) { lua_State* L; @@ -382,7 +440,15 @@ void ai_attacked(Pilot* attacked, const unsigned int attacker) { WARN("Pilot '%s' ai -> 'attacked' : %s", cur_pilot->name, lua_tostring(L, -1)); } -/* Pilot was just created. */ +/** + * @fn void ai_create(Pilot* pilot) + * + * @brief Run the create() function in the pilot. + * + * Should create all the gear and such the pilot has. + * + * @param pilot Pilot to "create". + */ void ai_create(Pilot* pilot) { lua_State* L; diff --git a/src/lephisto.c b/src/lephisto.c index 2f59f03..0cb909a 100644 --- a/src/lephisto.c +++ b/src/lephisto.c @@ -1,3 +1,14 @@ +/** + * @mainpage LEPHISTO + * + * Doxygen documentation for the Lephisto project. (c) SaraCraft. + */ +/** + * @file lephisto.c + * + * @brief Control the overall game flow: data loading/unloading and game loop. + */ + #include #include @@ -34,30 +45,29 @@ #include "nebulae.h" -#define XML_START_ID "Start" -#define START_DATA "../dat/start.xml" +#define XML_START_ID "Start" /**< XML document tag of module start file. */ +#define START_DATA "../dat/start.xml" /**< Path to module start file. */ -#define CONF_FILE "conf" -#define VERSION_FILE "VERSION" -#define VERSION_LEN 10 -#define MINIMUM_FPS 0.5 -#define FONT_SIZE 12 -#define FONT_SIZE_SMALL 10 +#define CONF_FILE "conf" /**< Configuration file by default. */ +#define VERSION_FILE "VERSION" /**< Version file by default. */ +#define VERSION_LEN 10 /**< Max length of the version file. */ +#define FONT_SIZE 12 /**< Normal font size. */ +#define FONT_SIZE_SMALL 10 /**< Small font size. */ -#define LEPHISTO_INIT_DELAY 3000 /* Minimum amount of time to wait with loading screen. */ +#define LEPHISTO_INIT_DELAY 3000 /**< Minimum amount of time to wait with loading screen. */ -static int quit = 0; /* Primary loop. */ -unsigned int gtime = 0; /* Calculate FPS and movement. */ +static int quit = 0; /**< For primary loop. */ +unsigned int time = 0; /**< USed to calculate FPS and movement, in pause.c */ static char version[VERSION_LEN]; /* Just some default crap. */ -char* data = NULL; -char dataname[DATA_NAME_LEN] = ""; -int nosound = 0; -int show_fps = 1; /* Default - True. */ -int max_fps = 0; -int indjoystick = -1; -char* namjoystick = NULL; +char* data = NULL; /**< Path to datafile. */ +char dataname[DATA_NAME_LEN] = ""; /**< Name of data file. */ +int nosound = 0; /**< Disable sound when loaded. */ +int show_fps = 1; /**< Shows fps - default true. */ +int max_fps = 0; /**< Default FPS limit, 0 is no limit. */ +int indjoystick = -1; /**< Index of joystick to use, -1 is none. */ +char* namjoystick = NULL; /**< Name of joystick to use, NULL is none. */ /* Prototypes. */ static void print_SDLversion(void); @@ -76,10 +86,13 @@ static void render_all(void); /** + * @fn int main(int argc, char** argv) + * * @brief The entry point of Lephisto. - * @param[in] argc Number of arguments. - * @param[in] argv Array of argc arguments. - * @return EXIT_SUCCESS on success. + * + * @param[in] argc Number of arguments. + * @param[in] argv Array of argc arguments. + * @return EXIT_SUCCESS on success. */ #ifdef WIN32 int WINAPI WinMain(HINSTANCE hInst, HINSTANCE hPrevInst, LPSTR lpCmdLine, @@ -132,7 +145,7 @@ int main(int argc, char** argv) { } window_caption(); load_screen(); - gtime = SDL_GetTicks(); + time = SDL_GetTicks(); /* OpenAL sound. */ if(nosound) { @@ -185,9 +198,9 @@ int main(int argc, char** argv) { menu_main(); /* Force a minimum delay with loading screen. */ - if((SDL_GetTicks() - gtime) < LEPHISTO_INIT_DELAY) - SDL_Delay(LEPHISTO_INIT_DELAY - (SDL_GetTicks() - gtime)); - gtime = SDL_GetTicks(); /* Init the time. */ + if((SDL_GetTicks() - time) < LEPHISTO_INIT_DELAY) + SDL_Delay(LEPHISTO_INIT_DELAY - (SDL_GetTicks() - time)); + time = SDL_GetTicks(); /* Init the time. */ /* Main loop. */ SDL_Event event; @@ -234,6 +247,8 @@ int main(int argc, char** argv) { } /** + * @fn void load_scren(void) + * * @brief Display a loading screen. */ void load_screen(void) { @@ -275,6 +290,8 @@ void load_screen(void) { } /** + * @fn void load_all(void) + * * @brief Load all the data, makes main() simpler. */ void load_all(void) { @@ -290,6 +307,8 @@ void load_all(void) { } /** + * @fn void unload_all(void) + * * @brief Unloads all data, simplifies main(). */ void unload_all(void) { @@ -305,6 +324,8 @@ void unload_all(void) { } /** + * @fn void main_loop(void) + * * @brief Split main loop from main() for secondary loop hack in toolkit.c. */ void main_loop(void) { @@ -326,6 +347,8 @@ void main_loop(void) { static double fps_dt = 1.; static double cur_dt = 0.; /** + * @fn static void fps_control(void) + * * @brief Controls the FPS. */ static void fps_control(void) { @@ -334,8 +357,8 @@ static void fps_control(void) { /* dt in ms/1000. */ t = SDL_GetTicks(); - cur_dt = (double)(t-gtime)/1000.; - gtime = t; + cur_dt = (double)(t-time)/1000.; + time = t; if(paused) SDL_Delay(10); /* Drop paused FPS to be nice to the CPU. */ @@ -349,6 +372,8 @@ static void fps_control(void) { static const double fps_min = 1./50.0; /** + * @fn static void update_all(void) + * * @brief Updates the game itself (player flying around etc). */ static void update_all(void) { @@ -377,7 +402,10 @@ static void update_all(void) { } /** + * @fn static void update_routine(double dt) + * * @brief Actually runs the update. + * @param[in] dt Current delta tick. */ static void update_routine(double dt) { space_update(dt); @@ -387,22 +415,25 @@ static void update_routine(double dt) { } /** + * @fn static void render_all(void) + * * @brief Renders the game itself (player flying around etc). * * Blitting order. (layers) * - * BG | Stars and planets. - * | Background player stuff (planet targetting) - * | Background particles. - * | Back layer weapons. - * X - * N | NPC ships. - * | Front layer weapons. - * | Normal layer particles (above ships). - * X - * FG | Player. - * | Foreground particles. - * | Text and GUI. + * - BG + * -- Stars and planets. + * -- Background player stuff (planet targetting) + * -- Background particles. + * -- Back layer weapons. + * - N + * -- NPC ships. + * -- Front layer weapons. + * -- Normal layer particles (above ships). + * - FG + * -- Player. + * -- Foreground particles. + * -- Text and GUI. */ static void render_all(void) { /* Setup. */ @@ -428,7 +459,11 @@ static void render_all(void) { static double fps = 0.; static double fps_cur = 0.; /** + * @fn static void display_fps(const double dt) + * * @brief Displays FPS on the screen. + * + * @param[in] dt Current delta tick. */ static void display_fps(const double dt) { double x, y; @@ -447,6 +482,8 @@ static void display_fps(const double dt) { } /** + * @fn static void data_name(void) + * * @brief Set the data module's name. */ static void data_name(void) { @@ -502,6 +539,8 @@ static void data_name(void) { } /** + * @fn static void window_caption(void) + * * @brief Set the window caption. */ static void window_caption(void) { @@ -511,10 +550,14 @@ static void window_caption(void) { SDL_WM_SetCaption(tmp, NULL); } -static char human_version[50]; +static char human_version[50]; /**< Stores human readable version string. */ /** + * @fn char* lephisto_version(void) + * * @brief Return the version in a human readable string. + * + * @return The human readable version string. */ char* lephisto_version(void) { if(human_version[0] == '\0') @@ -524,7 +567,9 @@ char* lephisto_version(void) { } /** - * @bief Print the SDL version. + * @fn static void print print_SDLversion. + * + * @bief Print the SDL version to console. */ static void print_SDLversion(void) { const SDL_version* linked; diff --git a/src/lephisto.h b/src/lephisto.h index 407d2d9..e9d5f15 100644 --- a/src/lephisto.h +++ b/src/lephisto.h @@ -1,31 +1,37 @@ #pragma once -#define APPNAME "Lephisto" +/** + * @file lephisto.h + * + * @brief Header file with generic functions and lephisto-specifics. + */ -#define MALLOC_L(type)(malloc(sizeof(type))) -#define CALLOC_L(type)(calloc(1, sizeof(type))) +#define APPNAME "Lephisto" /**< Application name. */ -#define ABS(x) (((x)<0)?-(x):(x)) -#define FABS(x) (((x)<0.)?-(x):(x)) +#define MALLOC_L(type)(malloc(sizeof(type))) /**< Deprecated. */ +#define CALLOC_L(type)(calloc(1, sizeof(type))) /**< Deprecated. */ -#define MAX(x,y) (((x)>(y))?(x):(y)) -#define MIN(x,y) (((x)>(y))?(y):(x)) +#define ABS(x) (((x)<0)?-(x):(x)) /**< Return absulute value. */ +#define FABS(x) (((x)<0.)?-(x):(x)) /**< Return float absolute value. */ -#define pow2(x) ((x)*(x)) +#define MAX(x,y) (((x)>(y))?(x):(y)) /**< Return maximum. */ +#define MIN(x,y) (((x)>(y))?(y):(x)) /**< Return minumum. */ -#define DATA_DEF "data" /* Default data packfile. */ -extern char* data; /* Modifiable datafile. */ -#define DATA data /* Data file. */ -#define DATA_NAME_LEN 32 /* Max length of data name. */ -extern char dataname[DATA_NAME_LEN]; +#define pow2(x) ((x)*(x)) /**< ^2 */ + +#define DATA_DEF "data" /**< Default data packfile. */ +extern char* data; /**< Modifiable datafile. */ +#define DATA data /**< Standard data file to use. */ +#define DATA_NAME_LEN 32 /**< Max length of data name. */ +extern char dataname[DATA_NAME_LEN]; /**< Datafile name. */ /* Max filename path. */ #ifndef PATH_MAX -# define PATH_MAX 128 +# define PATH_MAX 128 /**< If not already defined. */ #endif #ifndef M_PI -#define M_PI 3.14159265358979323846 /* Pi. */ +#define M_PI 3.14159265358979323846 /**< If not already defined. */ #endif char* lephisto_version(void);