Clean up various comments, etc, in header files

src/README

@@ -10,11 +10,11 @@ source code is split up among the following files:
 
     trader.c    trader.h    - Main program, command-line interface
     globals.c   globals.h   - Global game constants and variables
-    game.c      game.h      - Game start and end routines
+    game.c      game.h      - Game start, end and (some) display functions
-    move.c      move.h      - Routines for making and processing a move
+    move.c      move.h      - Functions for making and processing a move
-    exch.c      exch.h      - Stock Exchange and Bank routines
+    exch.c      exch.h      - Stock Exchange and Bank functions
-    fileio.c    fileio.h    - Load and save game file routines
+    fileio.c    fileio.h    - Load and save game file functions
-    help.c      help.h      - Help text routines: how to play Star Traders
+    help.c      help.h      - Help text functions: how to play the game
-    intf.c      intf.h      - Basic text input/output routines
+    intf.c      intf.h      - Basic text input/output functions
     utils.c     utils.h     - Utility functions needed by Star Traders
     system.h                - All system header files are included here

src/exch.h

@@ -33,7 +33,7 @@
 
 
 /************************************************************************
-*                 Stock Exchange function declarations                  *
+*                  Stock Exchange function prototypes                   *
 ************************************************************************/
 
 extern void exchange_stock (void);

src/fileio.h

@@ -33,7 +33,7 @@
 
 
 /************************************************************************
-*               Game load and save function declarations                *
+*                Game load and save function prototypes                 *
 ************************************************************************/
 
 extern bool load_game (int num);

src/game.h

@@ -36,7 +36,7 @@
 
 
 /************************************************************************
-*                      Game function declarations                       *
+*                       Game function prototypes                        *
 ************************************************************************/
 
 extern void init_game (void);

src/globals.c

@@ -47,6 +47,7 @@ const char *company_name[MAX_COMPANIES] = {
     "Hercules and Co"
 };
 
+
 // Ordinal strings
 const char *ordinal[MAX_PLAYERS + 1] = {
     "0th",
@@ -71,17 +72,17 @@ map_val_t	galaxy_map[MAX_X][MAX_Y];	// Map of the galaxy
 move_rec_t	game_move[NUMBER_MOVES];	// Current moves
 
 int	max_turn;			// Max. number of turns in game
-int	turn_number;
+int	turn_number;			// Current turn (1 to max_turn)
-int	number_players;
+int	number_players;			// Number of players
-int	current_player;
+int	current_player;			// Current player (0 to number_players-1)
 int	first_player;			// Who WAS the first player to go?
 
 double	interest_rate;			// Current interest rate
 
-bool	game_loaded = false;		// True if game was loaded from disk
+bool	game_loaded	= false;	// True if game was loaded from disk
-int	game_num    = 0;		// Game number (1-9)
+int	game_num	= 0;		// Game number (1-9)
 
-bool	quit_selected;			// Is a player trying to quit the game?
+bool	quit_selected	= false;	// Is a player trying to quit the game?
-bool	abort_game;			// Abort game without declaring winner?
+bool	abort_game	= false;	// Abort game without declaring winner?
 
 bool	option_no_color = false;	// True if --no-color was specified

src/globals.h

@@ -9,8 +9,8 @@
   Author: John Zaitseff <J.Zaitseff@zap.org.au>
   $Id$
 
-  This file, globals.h, contains definitions for global variables and
+  This file, globals.h, contains declarations for global variables and
-  structures for Star Traders.
+  structures used in Star Traders.
 
 
   This program is free software: you can redistribute it and/or modify it
@@ -36,64 +36,71 @@
 
 
 /************************************************************************
-*                    Constants and type declarations                    *
+*                            Game constants                             *
 ************************************************************************/
 
-#define MAX_X			(38)	/* Map dimensions MAP_X x MAP_Y */
+#define MAX_X			38	// Map dimensions MAX_X x MAX_Y
-#define MAX_Y			(14)
+#define MAX_Y			14
-#define STAR_RATIO		(0.10)	/* 10% of map should be stars */
+#define STAR_RATIO		0.10	// 10% of map should be stars
 
-#define NUMBER_MOVES		(20)	/* Number of choices on map per turn */
+#define NUMBER_MOVES		20	// Number of choices on map per turn
-#define DEFAULT_MAX_TURN	(50)	/* Default number of turns per game */
+#define DEFAULT_MAX_TURN	50	// Default number of turns per game
 
-#define MAX_PLAYERS		(8)	    /* Maximum number of players */
+#define MAX_PLAYERS		8	// Maximum number of players
-#define INITIAL_CASH		(6000.00)   /* Initial cash per player */
+#define INITIAL_CASH		6000.00	// Initial cash per player
-#define MAX_OVERDRAFT		(1000.00)   /* Max. value player can go negative */
+#define MAX_OVERDRAFT		1000.00	// Max. value player can go negative
-#define PROB_BANKRUPTCY		(0.07)	    /* If overdraft, 7% chance of bankruptcy */
+#define PROB_BANKRUPTCY		0.07	// If overdraft, 7% chance of bankruptcy
 
-#define MAX_COMPANIES		(8)	    /* Max. number of companies (must be <= 26) */
+#define MAX_COMPANIES		8	// Max. number of companies (do not change!)
-#define INITIAL_SHARE_PRICE	(60.00)	    /* Initial share price */
+#define INITIAL_STOCK_ISSUED	5	// Initial number of shares issued out
-#define SHARE_PRICE_INC		(60.00)	    /* Share price incr. for increase in shipping */
+#define INITIAL_MAX_STOCK	50	// Initial max. number of shares available
-#define SHARE_PRICE_INC_OUTPOST	(70.00)	    /* Incr. for adding an outpost */
+#define INITIAL_SHARE_PRICE	60.00	// Initial share price
-#define SHARE_PRICE_INC_OUTSTAR	(70.00)     /* Extra incr. for adding outpost next to star */
-#define SHARE_PRICE_INC_STAR	(300.00)    /* Incr. for adding next to star */
-#define SHARE_PRICE_INC_EXTRA	(0.50)	    /* Extra factor when incr. share price */
-#define INC_SHARE_PRICE		(0.30)	    /* 30% chance for increasing share price */
-#define DEC_SHARE_PRICE		(0.65)	    /* 65% x 30% chance of decrementing same */
-#define PRICE_CHANGE_RATE	(0.25)	    /* Up to 25% of share price is used to incr./decr. */
-#define INITIAL_RETURN		(0.05)	    /* Initial return per share: 5% */
-#define PROB_CHANGE_RETURN	(0.25)	    /* Chance of changing return when company grows */
-#define CHANGE_RETURN_INC	(0.60)	    /* 60% chance such change will increase return */
-#define CHANGE_COMPANY_RETURN	(0.40)	    /* Chance of randomly changing return */
-#define COMPANY_RETURN_INC	(0.75)	    /* 75% chance such change will increase return */
-#define MAX_COMPANY_RETURN	(0.40)	    /* Maximum return per share */
-#define RETURN_DIVIDER		(1.5)	    /* Min. amount by which to divide if return is too large */
-#define OWNERSHIP_BONUS		(2.0)	    /* Bonus amount based on percentage ownership */
-#define INITIAL_STOCK_ISSUED	(5)	    /* Initial number of shares issued out */
-#define INITIAL_MAX_STOCK	(50)	    /* Initial max. number of shares available */
-#define MERGE_STOCK_RATIO	(0.50)	    /* 50% of old shares are credited to new company */
-#define COMPANY_BANKRUPTCY	(0.01)	    /* 1% chance of company bankruptcy */
-#define ALL_ASSETS_TAKEN	(0.20)	    /* 20% chance of assets taken of same */
-#define BID_CHANCE		(0.75)	    /* 75% chance of successful bidding */
-#define MAX_SHARES_BIDDED	(200)	    /* Max. number of shares issued */
 
-#define INITIAL_INTEREST_RATE	(0.10)	/* Initial bank interest rate: 10% */
+#define SHARE_PRICE_INC		60.00	// Share price incr. for increase in shipping
-#define CHANGE_INTEREST_RATE	(0.30)	/* 30% chance of changing interest rate */
+#define SHARE_PRICE_INC_OUTPOST	70.00	// Incr. for adding an outpost
-#define INTEREST_RATE_INC	(0.65)	/* 65% chance of above being an increment */
+#define SHARE_PRICE_INC_OUTSTAR	70.00	// Extra incr. for adding outpost next to star
-#define MAX_INTEREST_RATE	(0.30)	/* Maximum interest rate */
+#define SHARE_PRICE_INC_STAR	300.00	// Incr. for adding next to star
-#define INTEREST_RATE_DIVIDER	(1.5)	/* Min. amount by which to divide if interest is too high */
+#define SHARE_PRICE_INC_EXTRA	0.50	// Extra factor when incr. share price
-#define CREDIT_LIMIT_RATE	(2.0)	/* Multiplier for credit limit */
 
-#define ROUNDING_AMOUNT		(0.01)	/* Round off smaller amounts to zero */
+#define MERGE_STOCK_RATIO	0.50	// 50% of old shares are credited to new company
+#define COMPANY_BANKRUPTCY	0.01	// 1% chance of company bankruptcy
+#define ALL_ASSETS_TAKEN	0.20	// 20% chance of assets taken of same
 
+#define INC_SHARE_PRICE		0.30	// 30% chance for increasing share price
+#define DEC_SHARE_PRICE		0.65	// 65% x 30% chance of decrementing same
+#define PRICE_CHANGE_RATE	0.25	// Up to 25% of share price is used to incr./decr.
+#define INITIAL_RETURN		0.05	// Initial return per share: 5%
+#define GROWING_RETURN_CHANGE	0.25	// Chance of changing return when company grows
+#define GROWING_RETURN_INC	0.60	// 60% chance such change will increase return
+#define CHANGE_COMPANY_RETURN	0.40	// Chance of randomly changing return
+#define COMPANY_RETURN_INC	0.75	// 75% chance such change will increase return
+#define MAX_COMPANY_RETURN	0.40	// Maximum return per share
+#define RETURN_DIVIDER		1.50	// Min. amount by which to divide if return too large
+#define OWNERSHIP_BONUS		2.00	// Bonus amount based on percentage ownership
+#define BID_CHANCE		0.75	// 75% chance of successful bidding
+#define MAX_SHARES_BIDDED	200	// Max. number of shares issued
+
+#define INITIAL_INTEREST_RATE	0.10	// Initial bank interest rate: 10%
+#define CHANGE_INTEREST_RATE	0.30	// 30% chance of changing interest rate
+#define INTEREST_RATE_INC	0.65	// 65% chance of above being an increment
+#define MAX_INTEREST_RATE	0.30	// Maximum interest rate
+#define INTEREST_RATE_DIVIDER	1.50	// Min. amount by which to divide if interest is too high
+#define CREDIT_LIMIT_RATE	2.00	// Multiplier for credit limit
+
+#define ROUNDING_AMOUNT		0.01	// Round off smaller amounts to zero
+
+
+/************************************************************************
+*                        Game type declarations                         *
+************************************************************************/
 
 // Information about each company
 typedef struct company_info {
     const char	*name;			// Company name
     double	share_price;		// Share price
     double	share_return;		// Return per share
-    long	stock_issued;		// Total stock sold to players
+    long int	stock_issued;		// Total stock sold to players
-    long	max_stock;		// Max. stock that company has
+    long int	max_stock;		// Max. stock that company has
     bool	on_map;			// True if company on map
 } company_info_t;
 
@@ -103,7 +110,7 @@ typedef struct player_info {
     char	*name;			// Player name
     double	cash;			// Cash available
     double	debt;			// Amount of debt
-    long	stock_owned[MAX_COMPANIES];	// How much stock is owned
+    long int	stock_owned[MAX_COMPANIES];	// How much stock is owned
     bool	in_game;		// True if still in the game
     double	sort_value;		// Total value (only used in end_game())
 } player_info_t;
@@ -121,6 +128,7 @@ typedef enum map_val {
 #define COMPANY_TO_MAP(i)	((i) + MAP_A)
 #define MAP_TO_COMPANY(m)	((m) - MAP_A)
 #define IS_MAP_COMPANY(m)	((m) >= MAP_A && (m) <= MAP_LAST)
+
 #define PRINTABLE_MAP_VAL(m)	((char) (m))
 
 #define COMPANY_TO_KEY(i)	((i) + 'A')
@@ -141,11 +149,11 @@ typedef struct move_rec {
 
 // Player moves / selection values
 typedef enum selection {
-    SEL_COMPANY_FIRST		= 0,
+    SEL_COMPANY_FIRST	= 0,
-    SEL_COMPANY_LAST		= MAX_COMPANIES - 1,
+    SEL_COMPANY_LAST	= MAX_COMPANIES - 1,
 
-    SEL_MOVE_FIRST		= 0,
+    SEL_MOVE_FIRST	= 0,
-    SEL_MOVE_LAST		= NUMBER_MOVES - 1,
+    SEL_MOVE_LAST	= NUMBER_MOVES - 1,
 
     SEL_BANKRUPT,			// Player wishes to give up
     SEL_SAVE,				// Save and end the game
@@ -154,7 +162,7 @@ typedef enum selection {
     SEL_BANK,				// Visit the Trading Bank
     SEL_EXIT,				// Exit the Stock Exchange
 
-    SEL_NONE			= -1	// Nothing yet selected
+    SEL_NONE		= -1		// Nothing yet selected
 } selection_t;
 
 
@@ -175,9 +183,9 @@ extern map_val_t	galaxy_map[MAX_X][MAX_Y];	// Map of the galaxy
 extern move_rec_t	game_move[NUMBER_MOVES];	// Current moves
 
 extern int	max_turn;		// Max. number of turns in game
-extern int	turn_number;
+extern int	turn_number;		// Current turn (1 to max_turn)
-extern int	number_players;
+extern int	number_players;		// Number of players
-extern int	current_player;
+extern int	current_player;		// Current player (0 to number_players-1)
 extern int	first_player;		// Who WAS the first player to go?
 
 extern double	interest_rate;		// Current interest rate

src/help.h

@@ -33,7 +33,7 @@
 
 
 /************************************************************************
-*                    Help text function declarations                    *
+*                     Help text function prototypes                     *
 ************************************************************************/
 
 extern void show_help (void);

src/intf.h

@@ -9,8 +9,9 @@
   Author: John Zaitseff <J.Zaitseff@zap.org.au>
   $Id$
 
-  This file, intf.h, contains function declarations for basic text input/
+  This file, intf.h, contains declarations for basic text input/output
-  output routines for Star Traders.
+  functions used in Star Traders.  It uses the X/Open Curses library to
+  provide terminal-independent functionality.
 
 
   This program is free software: you can redistribute it and/or modify it
@@ -154,7 +155,7 @@ extern bool use_color;			// True to use colour in Star Traders
 
 
 /************************************************************************
-*             Basic text input/output function declarations             *
+*              Basic text input/output function prototypes              *
 ************************************************************************/
 
 extern void init_screen (void);

src/move.c

@@ -918,8 +918,8 @@ void inc_share_price (int num, double inc)
 {
     company[num].share_price += inc * (1.0 + randf() * SHARE_PRICE_INC_EXTRA);
     company[num].max_stock   += inc / (randf() * 10.0 + 5.0);
-    if (randf() < PROB_CHANGE_RETURN) {
+    if (randf() < GROWING_RETURN_CHANGE) {
-	company[num].share_return *= randf() + CHANGE_RETURN_INC;
+	company[num].share_return *= randf() + GROWING_RETURN_INC;
     }
 }
 

src/move.h

@@ -33,7 +33,7 @@
 
 
 /************************************************************************
-*                    Game move function declarations                    *
+*                     Game move function prototypes                     *
 ************************************************************************/
 
 extern void select_moves (void);

src/trader.h

@@ -36,16 +36,16 @@
 *                         Included header files                         *
 ************************************************************************/
 
-#include "system.h"
+#include "system.h"		// System header files
 
-#include "globals.h"
+#include "globals.h"		// Global game constants and variables
-#include "game.h"
+#include "game.h"		// Game start, end and display functions
-#include "move.h"
+#include "move.h"		// Making and processing a move
-#include "exch.h"
+#include "exch.h"		// Stock Exchange and Bank functions
-#include "fileio.h"
+#include "fileio.h"		// Load and save game file functions
-#include "help.h"
+#include "help.h"		// Help text functions: how to play
-#include "intf.h"
+#include "intf.h"		// Basic text input/output functions
-#include "utils.h"
+#include "utils.h"		// Utility functions needed by Star Traders
 
 
 /************************************************************************
@@ -54,9 +54,9 @@
 
 #define GAME_FILE_HEADER	PACKAGE_NAME " Saved Game"
 #define GAME_FILE_API_VERSION	"7.0"	// For game loads and saves
-#define GAME_FILE_SENTINEL	(42)	// End of game file sentinel
+#define GAME_FILE_SENTINEL	42	// End of game file sentinel
 
-#define BUFSIZE			(1024)	// For various string buffers
+#define BUFSIZE			1024	// For various string buffers
 
 
 #endif /* included_TRADER_H */

src/utils.h

@@ -37,7 +37,7 @@
 ************************************************************************/
 
 #define GAME_FILENAME_PROTO	"game%d"
-#define GAME_FILENAME_BUFSIZE	(16)
+#define GAME_FILENAME_BUFSIZE	16
 
 
 /************************************************************************
@@ -51,7 +51,7 @@
 
 
 /************************************************************************
-*                     Utility function declarations                     *
+*                      Utility function prototypes                      *
 ************************************************************************/
 
 // Initialisation and environment functions