More documentation.

git-svn-id: svn://svn.code.sf.net/p/sc2/code/trunk@1840 8092fc87-c524-0410-9efc-e669fe64eaf9

sc2/src/sc2code/planets/calc.c

@@ -220,6 +220,7 @@ CalcTilt (void)
 	return (tilt);
 }
 
+// NB. Returns the RNG to the state it found it in.
 DWORD
 DoPlanetaryAnalysis (SYSTEM_INFOPTR SysInfoPtr, PPLANET_DESC
 		pPlanetDesc)

sc2/src/sc2code/planets/lander.h

@@ -30,6 +30,8 @@
 typedef struct
 {
 	BOOLEAN InTransit;
+			// Landing on or taking of from a planet.
+			// Setting it while landed will initiate takeoff.
 
 	SOUND OldMenuSounds;
 

sc2/src/sc2code/planets/plandata.h

@@ -206,6 +206,8 @@ typedef struct
 			 */
 } ElementEntry;
 
+// PlanetFrame describes a type of planet. It is not used to describe
+// individual planets.
 typedef struct
 {
 	BYTE Type;
@@ -215,8 +217,8 @@ typedef struct
 			 *           CRATERED_ALGO, or GAS_GIANT_ALGO
 			 * bits 4-7: interplanetary color, one of BLUE_BODY, GREEN_BODY,
 			 *           ORANGE_BODY, RED_BODY, WHITE_BODY (same as
-			 *           GRAY_BODY), YELLOW_BODY, NUM_STAR_COLORS,
-			 *           CYAN_BODY, PURPLE_BODY, VIOLET_BODY)
+			 *           GRAY_BODY), YELLOW_BODY, CYAN_BODY, PURPLE_BODY,
+			 *           VIOLET_BODY)
              */
 	BYTE BaseTectonics;
 			/* Base constant for calculation of tectonic activity,
@@ -272,9 +274,27 @@ typedef struct
 
 	DWORD ScanSeed[NUM_SCAN_TYPES];
 	DWORD ScanRetrieveMask[NUM_SCAN_TYPES];
+
+	// The CurPt, CurDensity and CurType fields are filled in
+	// when a GENERATE_MINERAL, GENERATE_ENERGY, or GENERATE_LIFE
+	// call is made.
 	POINT CurPt;
+			// Position of the mineral/bio/energy node on the planet.
 	COUNT CurDensity;
+			// For bio and energy: undefined
+			// For minerals the low byte is the gross size of the
+			// deposit (this determines the image), and the high
+			// byte is the fine size (the actual quantity).
 	COUNT CurType;
+			// For minerals: the type of element
+			// For bio: the type of the creature.
+			//          0 through NUM_CREATURE_TYPES are normal creatures,
+			//          NUM_CREATURE_TYPES + 1 is an Evil One
+			//          NUM_CREATURE_TYPES + 2 is a Brainbox Bulldozer
+			//          NUM_CREATURE_TYPES + 3 is Zex' Beauty
+			// For energy: 0 - Liftoff on collision
+			//             1 - No liftoff on collision
+			//             2 - (special case) Fwiffo
 
 	STRING DiscoveryString;
 	FONT LanderFont;

sc2/src/sc2code/planets/planets.c

@@ -61,6 +61,12 @@ DrawScannedObjects (BOOLEAN Reversed)
 	}
 }
 
+// Initialise the surface graphics, and start the planet music.
+// Called from the GENERATE_ORBITAL case of an IP generation function
+// (when orbit is entered; either from IP, or from loading a saved game)
+// and when "starmap" is selected from orbit and then cancelled.
+// IsDefined is true only when the planet comes with its own bitmap,
+// namely for Earth.
 void
 LoadPlanet (BOOLEAN IsDefined)
 {
@@ -74,6 +80,9 @@ LoadPlanet (BOOLEAN IsDefined)
 
 	if (pSolarSysState->MenuState.flash_task == 0)
 	{
+		// The "rotate planets" task is not initialised yet.
+		// This means the call to LoadPlanet is made from a
+		// GENERATE_ORBITAL case of an IP generation function.
 		PPLANET_DESC pPlanetDesc;
 		extern void GeneratePlanetSide (void);
 

sc2/src/sc2code/planets/planets.h

@@ -153,17 +153,29 @@ typedef struct planet_orbit
 	DWORD *ScratchArray;
 }  PLANET_ORBIT;
 
+// See doc/devel/generate for information on how this structure is
+// filled.
 typedef struct solarsys_state
 {
 	MENU_STATE MenuState;
 
 	COUNT WaitIntersect;
-	PLANET_DESC SunDesc[MAX_SUNS], PlanetDesc[MAX_PLANETS], MoonDesc[MAX_MOONS];
-	PPLANET_DESC pBaseDesc, pOrbitalDesc;
+	PLANET_DESC SunDesc[MAX_SUNS];
+	PLANET_DESC PlanetDesc[MAX_PLANETS];
+			// Description of the planets in the system.
+			// Only defined after a call to GenFunc with GENERATE_PLANETS
+			// as its argument, and overwritten by subsequent calls.
+	PLANET_DESC MoonDesc[MAX_MOONS];
+			// Description of the moons orbiting the planet pointed to
+			// by pBaseDesc.
+			// Only defined after a call to GenFunc with GENERATE_MOONS
+			// as its argument, and overwritten by subsequent calls.
+	PPLANET_DESC pBaseDesc;
+	PPLANET_DESC pOrbitalDesc;
 	SIZE FirstPlanetIndex, LastPlanetIndex;
 			// The planets get sorted on their image.origin.y value.
 			// PlanetDesc[FirstPlanetIndex] is the planet with the lowest
-			// image.origin.y, and PlanetDesc[FirstPlanetIndex] has the
+			// image.origin.y, and PlanetDesc[LastPlanetIndex] has the
 			// highest image.origin.y.
 			// PlanetDesc[PlanetDesc[i].NextIndex] is the next planet
 			// after PlanetDesc[i] in the ordering.
@@ -179,6 +191,8 @@ typedef struct solarsys_state
 
 	COUNT CurNode;
 	PLAN_GEN_FUNC GenFunc;
+			// Function to call to fill in various parts of this structure.
+			// See doc/devel/generate.
 
 	FRAME PlanetSideFrame[6];
 	UWORD Tint_rgb;

sc2/src/sc2code/sis.h

@@ -204,6 +204,8 @@ typedef struct
 
 	DWORD FuelOnBoard;
 	COUNT CrewEnlisted;
+			// Number of crew on board, not counting the captain.
+			// Set to (COUNT) ~0 to indicate game over.
 	COUNT TotalElementMass, TotalBioMass;
 
 	BYTE ModuleSlots[NUM_MODULE_SLOTS];