From 8bebc4fbbc11ba4b768de88f4277d626ff845c55 Mon Sep 17 00:00:00 2001 From: Allanis Date: Sat, 10 May 2014 17:56:50 +0100 Subject: [PATCH] [Changed] Cleaned up a bunch of doxygen stuff. --- src/ai.c | 15 ++++++++------- src/comm.c | 4 ++-- src/dialogue.c | 40 +++++++++++++++++++++++++++++++++++----- src/economy.c | 6 ++++++ src/escort.c | 2 +- src/explosion.c | 15 ++++++++++----- src/faction.c | 2 +- src/input.c | 4 ++++ src/llua_faction.h | 9 ++++++--- src/llua_pilot.h | 6 ++++-- src/llua_space.h | 10 ++++++++++ src/map.c | 4 +++- src/opengl.c | 5 +++-- src/perlin.c | 20 +++++++++++++------- src/physics.c | 12 +++--------- src/physics.h | 24 ++++++++++++++---------- 16 files changed, 123 insertions(+), 55 deletions(-) diff --git a/src/ai.c b/src/ai.c index a100794..82f28de 100644 --- a/src/ai.c +++ b/src/ai.c @@ -625,7 +625,7 @@ static void ai_freetask(Task* t) { } /** - * @group AI Lua AI Bindings + * @defgroup AI Lua AI Bindings * * @brief Handles how the AI interacts with the universe. * @@ -638,13 +638,14 @@ static void ai_freetask(Task* t) { */ /** - * @fn static int ai_pushtask(lua_State* L) - * - * @brief pushtask(number pos, string func [, data]) - * @param pos Position to push into stack, 0 is front, 1 is back. - * @param func Function to call for task. - * @param data Data to pass to the function. Only lightuserdata or number + * @brief Pushes a task onto the pilots task list. + * @luaparam pos Position to push into stack, 0 is front, 1 is back. + * @luaparam func Function to call for task. + * @luaparam data Data to pass to the function. Only lightuserdata or number * is currently supported. + * + * @luafunc pushtask(pos, func, data) + * @param L Lua state. */ static int ai_pushtask(lua_State* L) { LLUA_MIN_ARGS(2); diff --git a/src/comm.c b/src/comm.c index a35ed86..9c1910f 100644 --- a/src/comm.c +++ b/src/comm.c @@ -24,7 +24,7 @@ static void comm_bribe(unsigned int wid, char* unused); static unsigned int comm_getBribeAmount(void); static char* comm_getBribeString(char* str); /* Extern. */ -void ai_setPilot(Pilot* p); +extern void ai_setPilot(Pilot* p); /** * @brief Open the communication dialogue with a pilot. @@ -114,7 +114,7 @@ int comm_open(unsigned int pilot) { /** * @brief Try to bribe the pilot. * @param wid ID of window calling the function. - * @param str Unused. + * @param unused Unused. */ static void comm_bribe(unsigned int wid, char* unused) { (void)unused; diff --git a/src/dialogue.c b/src/dialogue.c index 08ebbcb..98b9339 100644 --- a/src/dialogue.c +++ b/src/dialogue.c @@ -78,6 +78,7 @@ void dialogue_alert(const char* fmt, ...) { /** * @brief Closes the alert dialogue. + * @param wid Window being closed. * @param str Unused. */ static void dialogue_alertClose(unsigned int wid, char* str) { @@ -87,8 +88,6 @@ static void dialogue_alertClose(unsigned int wid, char* str) { } /** - * @fn static glFont* dialogue_getSize(char* msg, int* w, int* h) - * * @brief Get the size needed for the dialogue. * @param msg Message of the dialogue. * @param[out] w Get the width needed. @@ -159,6 +158,11 @@ void dialogue_msg(char* caption, const char* fmt, ...) { toolkit_loop(); } +/** + * @brief Closes a message dialogue. + * @param wid Window being closed. + * @param str Unused. + */ static void dialogue_msgClose(unsigned int wid, char* str) { (void)str; window_destroy(wid); @@ -207,6 +211,11 @@ int dialogue_YesNo(char* caption, const char* fmt, ...) { return yesno_result; } +/** + * @brief Closes a yesno dialogue. + * @param wid Window being closed. + * @param str Unused. + */ static void dialogue_YesNoClose(unsigned int wid, char* str) { /* Store the result. */ if(strcmp(str, "btnYes")==0) yesno_result = 1; @@ -220,9 +229,18 @@ static void dialogue_YesNoClose(unsigned int wid, char* str) { dialogue_open--; } -/* Toolkit input boxes, returns the input. */ static unsigned int input_wid = 0; static int input_cancelled = 0; +/** + * @brief Create a dialogue that allows the player to write a message. + * + * You must free the result if it's not null. + * @param title Title of the dialogue window. + * @param min Minimum length of the message (must be non-zero). + * @param max Maximum length of the message (must be non-zero). + * @param fmt Printf style message to display on the dialogue. + * @return The message the player typed or NULL if it was cancelled. + */ char* dialogue_input(char* title, int min, int max, const char* fmt, ...) { char msg[512], *input; va_list ap; @@ -284,9 +302,15 @@ char* dialogue_input(char* title, int min, int max, const char* fmt, ...) { input_wid = 0; dialogue_open--; + /* Return the result. */ return input; } +/** + * @brief Closes an input dialogue. + * @param wid Unused. + * @param str Unused. + */ static void dialogue_inputClose(unsigned int wid, char* str) { (void)str; (void)wid; @@ -295,14 +319,20 @@ static void dialogue_inputClose(unsigned int wid, char* str) { loop_done = 1; } +/** + * @brief Cancels an input dialogue. + * @param wid Window being closed. + * @param str Unused. + */ static void dialogue_inputCancel(unsigned int wid, char* str) { input_cancelled = 1; dialogue_inputClose(wid, str); } -/* - * Spawns a secondary loop that only works until the toolkit dies, +/** + * @brief Spawns a secondary loop that only works until the toolkit dies, * alot like the main while loop in lephisto.c + * @return 0 on success. */ static int toolkit_loop(void) { SDL_Event event; diff --git a/src/economy.c b/src/economy.c index 7bbeaeb..2d7f084 100644 --- a/src/economy.c +++ b/src/economy.c @@ -93,6 +93,12 @@ static void commodity_freeOne(Commodity* com) { memset(com, 0, sizeof(Commodity)); } +/** + * @brief Loads a commodity. + * @param tmp Commodity to load data into. + * @param parent XML node to load from. + * @return Commodity loaded from parent. + */ static int commodity_parse(Commodity* tmp, xmlNodePtr parent) { xmlNodePtr node; diff --git a/src/escort.c b/src/escort.c index dda2d9f..145a529 100644 --- a/src/escort.c +++ b/src/escort.c @@ -22,7 +22,7 @@ /* Static. */ static int escort_command(Pilot* parent, int cmd, int param); /* Extern. */ -extern void ai_setPilot(Pilot* p); +extern void ai_setPilot(Pilot* p); /**< From ai.c. */ /** * @fn int escort_create(unsigned int parent, char* ship, diff --git a/src/explosion.c b/src/explosion.c index 978628a..40f9290 100644 --- a/src/explosion.c +++ b/src/explosion.c @@ -10,11 +10,16 @@ #include "explosion.h" /** - * @fn void expl_explode(double x, double y, double vx, double vy, - * double radius, DamageType dtype, double damage, - * unsigned int parent, int mode) - * - * @brief + * @brief Does explosion in a radius (damage and graphics). + * @param x X position of explosion center. + * @param y Y position of explosion center. + * @param vx X velocity of explosion center. + * @param vy Y velocity of explosion center. + * @param radius Radius of the explosion. + * @param dtype Damage type. + * @param damage Damage amount. + * @param parent Parent of the explosion, 0 is none. + * @param mode Defines the explosion behaviour. */ void expl_explode(double x, double y, double vx, double vy, double radius, DamageType dtype, double damage, diff --git a/src/faction.c b/src/faction.c index 413c07b..b0661c8 100644 --- a/src/faction.c +++ b/src/faction.c @@ -259,7 +259,7 @@ glColour* faction_getColour(int f) { * @return Human readable players standing. */ -#define STANDING(m, s) if(mod >= m) return s; +#define STANDING(m, s) if(mod >= m) return s; /**< Hack to get standings easily. */ char* faction_getStanding(double mod) { STANDING( 90., "Here"); STANDING( 70., "Admired"); diff --git a/src/input.c b/src/input.c index 6264dc2..2def5fd 100644 --- a/src/input.c +++ b/src/input.c @@ -20,6 +20,10 @@ #define KEY_RELEASE (-1.) /**< Key is released. */ /* Keybind structure. */ + +/** + * @brief Lephisto Keybinding. + */ typedef struct Keybind_ { char* name; /**< Keybinding name, taken from keybindNames[] */ KeybindType type; /**< type, defined in player.h. */ diff --git a/src/llua_faction.h b/src/llua_faction.h index c537795..6edacf6 100644 --- a/src/llua_faction.h +++ b/src/llua_faction.h @@ -1,10 +1,13 @@ #pragma once +#include "lua.h" -#define FACTION_METATABLE "Faction" +#define FACTION_METATABLE "Faction" /**< Faction metatable identifier. */ -/* Lua wrappers. */ +/** + * @brief Lua wrapper for a faction. + */ typedef struct LuaFaction_s { - int f; + int f; /**< Internal use faction identifier. */ } LuaFaction; /* Load the space library. */ diff --git a/src/llua_pilot.h b/src/llua_pilot.h index 6b8d762..2e52a14 100644 --- a/src/llua_pilot.h +++ b/src/llua_pilot.h @@ -2,9 +2,11 @@ #include "lua.h" #include "pilot.h" -#define PILOT_METATABLE "Pilot" +#define PILOT_METATABLE "Pilot" /**< Pilot metatable identifier. */ -/* Lua wrappers. */ +/** + * @brief Lua wrapper for pilots. + */ typedef struct LuaPilot_s { unsigned int pilot; } LuaPilot; diff --git a/src/llua_space.h b/src/llua_space.h index 40710b8..4e8dd02 100644 --- a/src/llua_space.h +++ b/src/llua_space.h @@ -7,12 +7,22 @@ #define VECTOR_METATABLE "Vec2" /* Lua wrappers. */ + +/** + * @brief Lua Planet wrapper. + */ typedef struct LuaPlanet_s { Planet* p; } LuaPlanet; +/** + * @brief Lua StarSystem wrapper + */ typedef struct LuaSystem_s { StarSystem* s; } LuaSystem; +/** + * @brief Lua Vec2 wrapper. + */ typedef struct LuaVector_s { Vec2 vec; } LuaVector; diff --git a/src/map.c b/src/map.c index 585a014..1af0f72 100644 --- a/src/map.c +++ b/src/map.c @@ -624,7 +624,9 @@ void map_select(StarSystem* sys) { /* A* Algorithm fo shortest path finding. */ -/* The node struct. */ +/** + * @brief Node structure for A* pathfinding. + */ typedef struct SysNode_ { struct SysNode_* next, *gnext; diff --git a/src/opengl.c b/src/opengl.c index a7dfbb5..d531241 100644 --- a/src/opengl.c +++ b/src/opengl.c @@ -26,8 +26,9 @@ Vec2* gl_camera; /**< Camera we are using. */ extern double gui_xoff; extern double gui_yoff; -/* - * Graphic list. +/* Graphic list. */ +/** + * @brief Represents a node in the texture list. */ typedef struct glTexList_ { struct glTexList_* next; /**< Next in linked list */ diff --git a/src/perlin.c b/src/perlin.c index 108f1f4..747ef38 100644 --- a/src/perlin.c +++ b/src/perlin.c @@ -26,17 +26,23 @@ #include "perlin.h" -#define NOISE_MAX_OCTAVES 4 -#define NOISE_DEFAULT_HURST 0.5 -#define NOISE_DEFAULT_LACUNARITY 2. +#define NOISE_MAX_OCTAVES 4 /**< Default octaves for noise. */ +#define NOISE_DEFAULT_HURST 0.5 /**< Default hurst for noise. */ +#define NOISE_DEFAULT_LACUNARITY 2. /**< Default lacunarity for noise. */ +/** + * @brief Ponderates x between a and b. + */ #define LERP(a, b, x) (a + x * (b - a)) +/** + * @brief Clamps x between a and b: a <= x <= b. + */ #define CLAMP(a, b, x) ((x) < (a) ? (a) : ((x) > (b) ? (b) : (x))) -typedef void* noise_t; - -/* Used internally. */ -typedef struct { +/** + * @brief Structure used for generating noise. + */ +typedef struct perlin_data_s { int ndim; /**< Dimension of the noise. */ unsigned char map[256]; /**< Randomized map of indexes into buffer. */ float buffer[256][3]; /**< Random 256x3 buffer. */ diff --git a/src/physics.c b/src/physics.c index c346438..55b8657 100644 --- a/src/physics.c +++ b/src/physics.c @@ -100,10 +100,8 @@ double vect_dot(Vec2* a, Vec2* b) { * SOLID! * ================ */ - -/* ==Update method.======================================== - * @fn static void simple_update(Solid* obj, const double dt) - * +#if defined(FREEBSD) +/** * @brief Update the solids position using a euler integration. * * Simple method. @@ -116,9 +114,7 @@ double vect_dot(Vec2* a, Vec2* b) { * * Since dt isn't actually differential this gives us an * error, so watch out with big values for dt. - * ======================================================== */ -#if defined(FREEBSD) static void simple_update(Solid* obj, const double dt) { double px, py, vx, vy, ax, ay; @@ -156,8 +152,7 @@ static void simple_update(Solid* obj, const double dt) { } #endif /* defined(FREEBSD) */ -/* ==Runge-Kutta 4th method.=============================== - * +/** * @brief Runge-Kutta method of updating a solid based on it's * acceleration. * @@ -178,7 +173,6 @@ static void simple_update(Solid* obj, const double dt) { * a 2D plane. Therefore RK chops it up in chunks and actually * creates a tiny curve instead of aproximating the curve for * a tiny staight line. - * ======================================================== */ #if !defined(FREEBSD) diff --git a/src/physics.h b/src/physics.h index 403b244..ed23d1d 100644 --- a/src/physics.h +++ b/src/physics.h @@ -2,19 +2,21 @@ #include -#define VX(v) ((v).x) -#define VY(v) ((v).y) -#define VMOD(v) ((v).mod) -#define VANGLE(v) ((v).angle) +#define VX(v) ((v).x) /**< Get the X component of a vector. */ +#define VY(v) ((v).y) /**< Get the Y component of a vector. */ +#define VMOD(v) ((v).mod) /**< Get the modulus of a vector. */ +#define VANGLE(v) ((v).angle) /**< Get the angle of a vector. */ -#define MOD(x,y) (sqrt((x)*(x) + (y)*(y))) -#define ANGLE(x,y) (atan2(y,x)) +#define MOD(x,y) (sqrt((x)*(x) + (y)*(y)))/**x-(u)->x, (v)->y-(u)->y) -#define vect_odist(v) MOD((v)->x, (v)->y) +#define vect_dist(v,u) MOD((v)->x-(u)->x, (v)->y-(u)->y)/**x, (v)->y) /**< Get the distance of a vector from the origin. */ -/* Base of 2D vectors. */ +/** + * @brief Represents a 2d vector. + */ typedef struct Vec2_ { double x, y; /* Cartesian values. */ double mod, angle; /* Polar values. */ @@ -36,7 +38,9 @@ void vect_cadd(Vec2* v, const double x, const double y); void vect_reflect(Vec2* r, Vec2* v, Vec2* n); double vect_dot(Vec2* a, Vec2* b); -/* Describe any solid in 2D space. */ +/** + * @brief Represents a solid in the game. + */ typedef struct Solid_ { double mass, dir, dir_vel; /* Properties. */ Vec2 vel, pos, force; /* Position/velocity vectors. */