From: Michael Andreen Date: Mon, 15 Apr 2002 02:21:36 +0000 (+0000) Subject: some documentation X-Git-Tag: HBS_0_2_0~5 X-Git-Url: https://ruin.nu/git/?p=hbs.git;a=commitdiff_plain;h=7b5ccf741883c34b2ac96afe460a3d0eda3701bb some documentation --- diff --git a/bs/fleet.h b/bs/fleet.h index 1051731..0a0db41 100644 --- a/bs/fleet.h +++ b/bs/fleet.h @@ -43,11 +43,12 @@ public: virtual ~Fleet(); /**Sets the name that represents this fleet. Might be different a name - * like foobar or some coordinates like 1:1:1. The name doesn't have to be unique, - * since it's up to the rest of the program to handle that part. + * like foobar or some coordinates like 1:1:1. The name doesn't have to be + * unique, since it's up to the rest of the program to handle that part. * \see Name */ void setName(std::string sName); + /**Returns the name of this fleet. * \see setName */ @@ -56,16 +57,24 @@ public: /**The race string decides what type of ships this fleet can have. * The values must be feeded into this class. * \param sRace This is just the name of the race. It's case-sensitive. - * \return If the race is available this function returns true, if not false is returned. The race is set in both cases though. + * \return If the race is available this function returns true, if not false + * is returned. The race is set in both cases though. * \see Race */ bool setRace(std::string sRace); + /**Just returns what race this fleet belongs to.. * \return The race, represented as a string. * \see setRace */ std::string race() const; + /**Returns the ship races allowed for this fleet.. This is not a hard limit + * it's more a indication to the interface what should be shown or not, the + * class can still handle all the different shiptypes. + * \return a vector of ints that can be used to compare with Unittype::race() + * \see Unittype::race() + */ std::vector RacesAllowed() const; /**Returns the total number of ships in this fleet @@ -77,6 +86,7 @@ public: * 10, and the arrival is at 12, then the eta is 2. */ void setETA(int eta); + /**Return the estimated time of arrival. It's counted from the current time (tick). */ int ETA() const; @@ -89,37 +99,175 @@ public: */ unsigned score(int tick = 0) const; + /**This function is used to set the number of units for a specific tic. + * \param untitype the unittype's name, as a std string + * \param number the number of ships + * \param tick what tick to set for. Tick 0 (before battle) is standard, no + * other is hardly used other than inside the engine. + */ void setFleet(std::string unittype, int number, int tick = 0); + /**Returns the numbers of units fo a specific type at a specific tick. + * \param unittype The shipname, as a std string + * \param tick The tick you want to look at, tick 0 (before battle) is default + * \return returns the number of units that params specifies. + */ int fleet(std::string unittype, int tick = 0); + /**Returns the number of free ships, that is: ships that aren't dead and not + * blocked. + * \param unittype The shipname, as a std string + * \param tick The tick you want to look at, tick 0 (before battle) is default + * \return returns the number of units that params specifies. + */ int freeFleet(std:: string unittype, int tick = 0); - static void setRaces(RaceList& races); - static void setUnits(UnitList& units); - - static const RaceList& Races(); - static const UnitList& Units(); - + /** This function takes the vector with fleets and adds all their units of the + * specific tick to the current fleet's first tick. Main usage is for battle + * calculations. + * \param fleets a vector with fleet pointers + * \param tick an int to specify what tick to use. tick 0 (before battle) + * is default + * \todo add another tick parameter to specify what tick to use in the + * current fleet. + */ void addToThis(std::vector fleets, int tick = 0); + /** This function takes a vector with fleets and distribute all ship losses + * between tick 0 and 1 in the current fleet and adds that to the specified + * tick in each fleet. + * \param fleets a vector with fleet pointers that holds the fleets that's + * going to share the losses. + * \param tick the tick to add the losses to for the fleets in the vector. + * \todo add another tick parameter to specify what tick to use in the + * current fleet. + */ void distributeLossesGains(std::vector fleets, int tick = 0); + /** This functions takes the captured roids between tick 0 and 1 in the + * current fleet and divides them between the fleets given as param. + * \param fleets a vector with Fleet pointers, points to the fleets that + * should get parts of the roids. + * \param tick the tick to use in the fleets given as argument, when the + * roids are handed out. + * \todo add another tick parameter to specify what tick to use in the + * current fleet. + */ void distributeCappedRoids(std::vector fleets, int tick = 0); + /** Checks through the vector with fleets to see who's in time for the + * specified tick and staying long enough so they're not too early. + * \param fleets a vector with Fleet pointers to use for the calculations + * \param stays the number of ticks the fleets stays, will be obsolee when + * I get the time. + * \param tick What the current tick is to use for the calculations + * \return returns a vector with the fleet that are in time for the battle + * and are staying long enough. + * \todo add the stays part as a integrated part of each fleet. + */ std::vector calculateSide(std::vector fleets, int stays = 0, int tick = 0); + /** Kill some ships of the specified type in the current fleet. + * \param unittype the name of the unit to kill + * \param number how many ships to kill + * \param tick what tick they where killed. + */ void killFleet(std::string unittype, int number, int tick = 0); + /**Block some ships of the specified type in the current fleet. + * \param unittype the name of the unit to block + * \param number how many ships to block + * \param tick what tick they where blocked. + */ void blockFleet(std::string unittype, int number, int tick = 0); + /** Set the resources of the specified type for the tick. + * + * \param type The name of the resource (in pa: metal, + * crystal and eonium (+ uninit for roids). + * \param number just simply the number of the specified resource. + * \param tick what tick to set + * \sa resource + */ void setResource(std::string type, int number, int tick = 0); + + /** Adds a number ot the specified resource type. + * \param type The name of the resource (in pa: metal, + * crystal and eonium (+ uninit for roids). + * \param number just simply the number of the specified resource. + * \param tick what tick to set + * \sa resource + */ void addResource(std::string type, int number, int tick = 0); + + /** Looks up the how much of a specific resource type the current fleet has. + * + * Resources is a kinda vague word, in general it's used as roid capping + * for hostile fleet and as salvage for friendly. + * \param type The name of the resource (in pa: metal, + * crystal and eonium (+ uninit for roids). + * \param tick what tick to set + * \returns simply returns the number of the specific resource this fleet + * has. + */ int resource(std::string type, int tick = 0)const; + /** This is a little more advanced function. It makes a a number of units + * of a specific unittype shoot at the current fleet and calculates the + * losses. + * + * Atm all calculations are done for tick 0/1 + * \param unittype The name of the unit that shots at the current fleet. + * \param number The number of the specific unittype that shoot. + * \param hitunits a map to count the number of killed units, just if the + * rest of the program needs it. + * \todo add a parameter to specify what tick to calc for and move out as + * much of the code as possible because it's kinda crowded atm and lots of + * very similar stuff in both the take* functions. + * \sa takeEMP + */ void takeShoot(std::string unittype, int number, std::map& hitunits); + + /**This is a little more advanced function. It makes a a number of units + * of a specific unittype shoot at the current fleet and calculates how + * many got blocked.. + * + * Atm all calculations are done for tick 0/1 + * \param unittype The name of the unit that shots at the current fleet. + * \param number The number of the specific unittype that shoot. + * \todo add a parameter to specify what tick to calc for and move out as + * much of the code as possible because it's kinda crowded atm and lots of + * very similar stuff in both the take* functions. + * \sa takeShoot + */ void takeEMP(std::string unittype, int number); + /** This function prints out all the ships in the fleet to stderr, + * mainly used for debugging. + */ void printFleet(); + + //static functions + /** This function is used to set the different races used. + * \param races a Simple RaceList which holds all the info + */ + static void setRaces(RaceList& races); + + /** This function is used to set all the units used in the game. + * \param units This is a simple UnitList holding all info needed. + */ + static void setUnits(UnitList& units); + + /** This function is used to get the list of races used. + * \returns it returns a simple RaceList just like the one that set it. + */ + static const RaceList& Races(); + + /** This function is used to get the list of all the units in the game + * \returns a simple UnitList holding everything. + */ + static const UnitList& Units(); + + protected: diff --git a/bs/planet.h b/bs/planet.h index e5c173e..c729ebf 100644 --- a/bs/planet.h +++ b/bs/planet.h @@ -33,23 +33,64 @@ typedef std::map > RoidList; * planets aren't available in this game). *@author Michael Andreen */ - -class Planet : public Fleet { +class Planet : public Fleet +{ public: Planet(); virtual ~Planet(); + /** The score for the current planet. + * \returns the score as an unsigned int. + * \todo add a param to specify what tick to use. + */ unsigned planetScore() const; - void setPlanetScore(unsigned i); + /** Sets the score for the current fleet. + * \param score this param is a unsigned int holding the score + * \todo add a param to specify what tick to use. + */ + void setPlanetScore(unsigned score); + + /** This function is used to get the number of roids of a specific type. + * \param type the for this roid (for pa: metal, crystal, eonium, uninit) + * \param tick what tick you want to get the number from. + * \returns the number of the specified type at the specified tick + */ int roids(std::string type, int tick = 0) const; + /** Used to set the number of roid at a specific tick + * \param type the for this roid (for pa: metal, crystal, eonium, uninit) + * \param tick what tick you want to get the number from. + * \param number the number of roids you want to set. + */ void setRoids(std::string type, int number, int tick = 0); + /** This function is used to remove a specific number of roids without + * knowing how many the total is. + * \param type the for this roid (for pa: metal, crystal, eonium, uninit) + * \param tick what tick you want to get the number from. + * \param number the number of roids you want to take. + */ void takeRoids(std::string type, int number, int tick = 0); + /** This function is used to start the batlle calculations on the current + * planet. It doesn't touch tick 0 on any of the fleet that fight in the + * battle, but all other ticks might be touched. + * \param friendly a vector with pointers to all friendly Fleet:s. + * \param hostile a vector with pointers to all hostile Fleet:s. + */ void runBattle(std::vector friendly, std::vector hostile); protected: - void calcOneTick(Planet* friendly, Fleet* Hostile, std::map >& stealfriendly, std::map >& stealhostile, int tick = 0); + /** This function is used to start the calculations of a single tick of the + * battle on the current planet. It's protected because it's not really meant + * to be used outside runBattle(), but I might reconsider it. + * \param friendly a pointer to the friendly fleet. + * \param hostile a pointer to the hostile fleet + * \param stealfriendly a container used to store all the stolen units the + * friendly side took this tick. + * \param stealhostile a cointainer used to store all the stole units the + * hostile side took this tick. + */ + void calcOneTick(Planet* friendly, Fleet* hostile, std::map >& stealfriendly, std::map >& stealhostile, int tick = 0); unsigned m_iScore; RoidList m_Roids; diff --git a/bs/unittype.h b/bs/unittype.h index cbb73ba..895b03d 100644 --- a/bs/unittype.h +++ b/bs/unittype.h @@ -27,9 +27,9 @@ /**This class contains a unittype, with all it's attributes + the number you got. * Maybe this actually should be a struct, since this class doen't have much to do, since i want it to be as generic as possible. * It got some data need need to be taken care of which makes me put it as a class. - * \todo need to add some more constructors.. + * \todo need to add some more constructors.., maybe not.. *@author Michael Andreen - *@see Fleet + *\sa Fleet Planet */ class UnitType @@ -43,31 +43,55 @@ public: /** Returns the name of this unittype */ std::string Name() const; - /** This functions sets which race this unittype is, the race is represented with a integer. */ + /** This functions sets which race this unittype is + * \param iRace the race is represented with a integer. + */ void setRace(int iRace); - /** Returns the race this unittype belongs to*/ + /** Used to get what type of race this is + * \returns returns the race as an integer + */ int race() const; - /** Sets the class for the unittype, it's represented as a integer */ + /** Sets the class for the unittype + * \param sClass the class represented as a string + */ void setUnitClass(std::string sClass); + /** used to get what type of class this unit is + * \returns the class as a string + */ std::string unitClass() const; - /** Sets the classes that this unittype targets. a vector is used. */ + /** Sets the classes that this unittype targets + * \param Target the target list, as a vector of strings + */ void setTarget(std::vector Target); - /** This function adds a target class to the end of the target list. */ + + /** This function adds a target class to the end of the target list. + * \param target the target you want to add, as a string. + */ void addTarget(std::string target); + /** This function inserts a target class into the target list. The default is in the beginning. * \param iTarget an integer that represents the target's class. - * \param index where to place the target. 0 being the default and first place. */ + * \param index where to place the target. 0 being the default and first place. + */ void insTarget(std::string iTarget, int index = 0); - /** Returns all targets from the target list */ + /** Used to get the full target list. + * \returns all targets as a vector of strings. + * */ std::vector target() const; /** Returns a specific target - * \param index An index value that represents the target. 0 being the first*/ + * \param index An index value that represents the target. 0 being the first + */ std::string target(int index) const; - /** Sets the initiatve, the lower it is the earlier the unit shots */ + /** Used to set the initiatve, the lower it is the earlier the unit shots + * \param iInit the initiative as an int + */ void setInitiative(int iInit); + /** Used to get the initiative this unittype got, lower shots first. + * \returns the initiative as an int + */ int initiative() const; /** Sets the agility, the higher it is the harder it is to hit the unit */