2007-09-20 Fabian S. <[email protected]>

	* V195
	* admin.c, aipur.c, ast1.c, ast3.c: documentation
	* av.h, data.h, endgame.c, fs.h: documentation
	* future.c, main.c, mis_c.c, mis_m.c: documentation
	* news_sup.c, news_suq.c, port.c, vab.c: documentation

ChangeLog

@@ -1,3 +1,15 @@
+2007-09-20  Fabian S. <[email protected]>
+
+	* V195
+
+	* admin.c, aipur.c, ast1.c, ast3.c: documentation
+
+	* av.h, data.h, endgame.c, fs.h: documentation
+
+	* future.c, main.c, mis_c.c, mis_m.c: documentation
+
+	* news_sup.c, news_suq.c, port.c, vab.c: documentation
+
 2007-09-18  Fabian S. <[email protected]>
 
 	* V195

admin.c

@@ -23,7 +23,9 @@
 // Programmed by Michael K McCarty
 //
 // All Administration Main Files
-
+/** \file admin.c Responsible for the Administration office.
+ * 
+ */
 
 #include "Buzz_inc.h"
 #include "externs.h"
@@ -146,7 +148,7 @@ int GenerateTables(SaveGameType saveType)
 
   memset(buffer,0x00,20480);
 
-  // old code lacked parans, so pointed FList off into space - pace
+  /** \note old code lacked parans, so pointed FList off into space - pace */
   FList=(SFInfo *)(buffer+5000);
   SaveHdr=(SaveFileHdr *) buffer;
 

aipur.c

@@ -22,7 +22,8 @@
 // Designed by Fritz Bronner
 // Programmed by Michael K McCarty
 //
-// AI Purchasing Routines
+/** \file aipur.c AI Purchasing Routines
+ */
 
 #include "Buzz_inc.h"
 #include "externs.h"
@@ -220,7 +221,8 @@ void Stat(char Win)
  return;
 }
 
-// AI Wants to purchase Astronauts
+/** AI Wants to purchase Astronauts
+ */
 void AIAstroPur(char plr)
 {
 	int cost;
@@ -249,7 +251,8 @@ void AIAstroPur(char plr)
 }
 
 
-// Select the best crew for the mission
+/** Select the best crew for the mission
+ */
 void SelectBest(char plr,int pos)
 {
  int count=0,now,MaxMen = 0,Index,AIMaxSel=0,i,j,k;
@@ -503,7 +506,8 @@ void CheckAdv(char plr)
 
 
 
-// Remove unhappy astro's
+/** Remove unhappy astro's
+ */
 void RemoveUnhappy(char plr)
 {
 	int i,l,astroClass=0,fltCrew=0;

ast1.c

@@ -22,6 +22,8 @@
 // Designed by Fritz Bronner
 // Programmed by Michael K McCarty
 //
+/** \file ast1.c Astronaut Recruitment
+ */
 
 #include "Buzz_inc.h"
 #include "externs.h"

ast3.c

@@ -22,6 +22,8 @@
 // Designed by Fritz Bronner
 // Programmed by Michael K McCarty
 //
+/** \file ast3.c Training and Hospital code
+ */
 
 #include "Buzz_inc.h"
 #include "externs.h"

av.h

@@ -46,9 +46,9 @@ struct audio_channel {
     unsigned                fade;            /* actual fade value */
     int                     fade_inc;        /* fade inc or dec */
 #endif
-    struct audio_chunk*     chunk;           /* played chunk */
-    struct audio_chunk**    chunk_tailp;     /* tail of chunk list? */
-    unsigned                offset;          /* data offset in chunk */
+    struct audio_chunk*     chunk;           /**< played chunk */
+    struct audio_chunk**    chunk_tailp;     /**< tail of chunk list? */
+    unsigned                offset;          /**< data offset in chunk */
 };
 
 extern char AnimSoundCheck(void);

data.h

@@ -374,24 +374,25 @@ struct BuzzData {                   // master data list for Buzz Aldrin's
 };
 
 struct Players {
-	char BUZZ[4];                    // Save Version Marker
-	uint32_t Checksum;                   // Checksum of Data
-	char plr[NUM_PLAYERS];                     // Order of Turns
-	struct Defl Def;                 // Defaults
-	char Year;                       // Game Turn
-	char Season;                     // Season of Year
-	struct PrestType Prestige[28];   // Definitions of Prest Vals
-	struct BuzzData P[NUM_PLAYERS];            // Player Game Data
-	char EMark[4];                   // Event Marker
-	char Events[100];                // History of Event Cards
-	char Count;                      // Number of Events Picked
-   char PD[NUM_PLAYERS][28];
-	char Mile[NUM_PLAYERS][10];                // MileStone Calcs
+    char BUZZ[4];                    /**< Save Version Marker */
+    uint32_t Checksum;               /**< Checksum of Data */
+    char plr[NUM_PLAYERS];           /**< Order of Turns */
+    struct Defl Def;                 /**< Defaults */
+    char Year;                       /**< Game Turn */
+    char Season;                     /**< Season of Year */
+    struct PrestType Prestige[28];   /**< Definitions of Prest Vals */
+    struct BuzzData P[NUM_PLAYERS];  /**< Player Game Data */
+    char EMark[4];                   /**< Event Marker */
+    char Events[100];                /**< History of Event Cards */
+    char Count;                      /**< Number of Events Picked */
+    char PD[NUM_PLAYERS][28];
+    char Mile[NUM_PLAYERS][10];      /**< MileStone Calcs */
 };
 
 
 
-/* MissionHard Descriptions
+/** MissionHard Descriptions
+ * \verbatim
    0=Capsule
    1=Kicker
    2=LM
@@ -400,8 +401,8 @@ struct Players {
    5=EVA
    6=Photo Recon
    7=Secondary Booster
+ * \endverbatim
 */
-
 enum MissionHardwareType
 {
 	Mission_Capsule = 0,			// 0

endgame.c

@@ -15,7 +15,8 @@
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
-// End Game Routines
+/** \file endgame.c End Game Routines
+ */
 
 #include "Buzz_inc.h"
 #include "externs.h"

fs.h

@@ -4,7 +4,11 @@
 #include "race.h"
 #include <stdio.h>
 
-/* types of files - they have different locations in filesystem */
+/** \file fs.h Definitions for filesystem
+ * 
+ */
+
+/** types of files - they have different locations in filesystem */
 enum {
     FT_DATA = 0,
     FT_SAVE = 1,
@@ -14,7 +18,7 @@ enum {
 		FT_MIDI
 };
 
-/* used for saved games */
+/** used for saved games */
 struct ffblk {
 	char ff_name[64];
 	int ff_ftime;

future.c

@@ -15,6 +15,9 @@
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
+/** \file future.c This is responsible for Future Mission planning screen.
+ * 
+ */
 #include "Buzz_inc.h"
 #include "externs.h"
 #include <assert.h>

main.c

@@ -58,7 +58,7 @@
   struct cdtable *cdt;
   long PalOff;
   ui16 LetHand;
-  char BIG;
+  char BIG;         /**< 1 for fullscreen mission playback, 0 otherwise */
 
 char *S_Name[] = {
    "LAUNCH",
@@ -263,18 +263,27 @@ int main(int argc, char *argv[])
   exit(EXIT_SUCCESS);
 }
 
-// utility fn for AI to see if it should scrub the mission
+/** utility fn for AI to see if it should scrub the mission
+ * 
+ * Rules are:
+ * - always do unmanned missions
+ * - Safety must be within 15 of R&D-Safety
+ * 
+ * \param plr Playerdata
+ * \param launchIdx ID of the launch
+ */
 int CheckIfMissionGo(char plr,char launchIdx)
 {
   char idx,mcode;
   struct MissionType *pMission;
-  Equipment *E = NULL;	// Pointer to Equipment we're looking at
+  Equipment *E = NULL;	/* Pointer to Equipment we're looking at */
 
 	// Grab the Mission Code from the current Launch Index
   mcode=Data->P[plr].Mission[launchIdx].MissionCode;
   pMission=&Data->P[plr].Mission[launchIdx];
 
 	// Always a go for Unmanned missions
+  /** \todo introduce mission attribute "manned vs. unmanned" */
   if (mcode==1 || mcode==3 || mcode==5 || (mcode>=7 && mcode<=13) || mcode==15)
      return 1;
 
@@ -549,7 +558,13 @@ void FreePadMen(char plr,struct MissionType *XMis)
 }
 
 
-// Destroy Pad and Reset any Crews affected
+/** Destroy Pad and Reset any Crews affected
+ * 
+ * \param cost amount of MB to pay for repairs
+ * \param pad number of the launch facility destroyed
+ * \param plr Player data
+ * \param mode 0 if future mission, 1 is current mission
+ */
 void DestroyPad(char plr,char pad,int cost,char mode)
 {
    struct MissionType *BMis=NULL,*AMis=NULL;

mis_c.c

@@ -134,7 +134,7 @@ void RLEE (char *dest, char *src, unsigned int src_size)
  */
 void PlaySequence(char plr,int step,char *Seq,char mode)
 {
-    DEBUG3("->PlaySequence(plr, step %d, Seq, mode %s)", step, mode);
+    DEBUG4("->PlaySequence(plr, step %d, Seq %c, mode %s)", step, Seq, mode);
 	int keep_going;
 	int wlen,i,j;
 	unsigned int fres,max;

mis_m.c

@@ -40,7 +40,8 @@ extern struct MisEval Mev[60];
 extern char MANNED[2],STEP,pal2[768],STEPnum,FINAL,AI[2],CAP[2],LM[2],DOC[2],EVA[2],fEarly,mcc,JOINT;
 extern char DMFake;
 extern int AUDIO;
-char MFlag,death,durx,MPad,Unm,Dock_Skip,SCRUBS,noDock,InSpace;
+char MFlag,death,durx,MPad,Unm,SCRUBS,noDock,InSpace;
+char Dock_Skip; /**< used for mission branching */
 extern struct mStr Mis;
 
 extern ui16 MisStat;
@@ -54,6 +55,7 @@ void Tick(char);
 
 void GetFailStat(struct XFails *Now,char *FName,int rnum)
 {
+  DEBUG2("->GetFailStat(struct XFails *Now,char *FName,int rnum %d)", rnum);
   int i;
   FILE *fin;
   long count;
@@ -100,6 +102,7 @@ void GetFailStat(struct XFails *Now,char *FName,int rnum)
 	};
 
   fclose(fin);
+  DEBUG1("<-GetFailStat()");
 }
 
 void MisCheck(char plr,char mpad)

news_sup.c

@@ -27,7 +27,11 @@
 #include "Buzz_inc.h"
 #include "externs.h"
 
-int Steal(int p,int prog,int type) // type= 1:postive -1:negative search
+/** ???
+ * 
+ * \param type 1:postive -1:negative search
+ */
+int Steal(int p,int prog,int type) 
 {
  int i=0,j=0,k=0,save[28],lo=0,hi=28;
  if (prog)EMPTY_BODY;
@@ -106,8 +110,12 @@ int Steal(int p,int prog,int type) // type= 1:postive -1:negative search
  return save[j];
 }
 
-
-int NMod(int p,int prog,int type,int per) // type= 1:postive -1:negative search
+/** ???
+ * 
+ * \param type 1:postive -1:negative search
+ * \param per Amount of modification in percent
+ */
+int NMod(int p,int prog,int type,int per)
 {
   int i=0,j=0,save[28],lo=0,hi=28;
   Equipment *Eptr[28];
@@ -117,7 +125,7 @@ int NMod(int p,int prog,int type,int per) // type= 1:postive -1:negative search
   /* drvee: this loop was going to 25, not 28 */
   for (i=0;i<(int)ARRAY_LENGTH(Eptr);i++)
    {
-       /* XXX: Mismatch between data.h(250) and this code here */
+       /** \bug Mismatch between data.h(250) and this code here */
     Eptr[i]=(Equipment *) &Data->P[p].Probe[i];
     save[i]= ((Eptr[i]->Safety+per*type)<=(Eptr[i]->MaxSafety)&& Eptr[i]->Num>=0) ? Eptr[i]->Safety+per*type : 0;
     if (Eptr[i]->Num<0) save[i]=0;

news_suq.c

@@ -22,7 +22,10 @@
 extern char AI[2];
 extern struct mStr Mis;
 
-//return true if need to scrub mission because of crews
+/**
+ * 
+ * \return true (1) if need to scrub mission because of crews
+ */
 char CheckCrewOK(char plr,char pad)
 {
  char RT_value=0;