--- a/hedgewars/GSHandlers.inc	Thu Apr 07 14:13:11 2011 -0400
+++ b/hedgewars/GSHandlers.inc	Thu Apr 07 23:54:09 2011 +0200
@@ -16,6 +16,15 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  *)
 
+(*
+ * This file contains the step handlers for gears.
+ *
+ * Important: Since gears change the course of the game, calculations that
+ *            lead to different results for different clients/players/machines
+ *            should NOT occur!
+ *            Use safe functions and data types! (e.g. GetRandom() and hwFloat)
+ *)
+
 procedure doStepPerPixel(Gear: PGear; step: TGearStepProcedure; onlyCheckIfChanged: boolean);
 var
     dX, dY, sX, sY: hwFloat;

--- a/hedgewars/VGSHandlers.inc	Thu Apr 07 14:13:11 2011 -0400
+++ b/hedgewars/VGSHandlers.inc	Thu Apr 07 23:54:09 2011 +0200
@@ -15,6 +15,16 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
  *)
+
+(*
+ * This file contains the step handlers for visual gears.
+ *
+ * Since the effects of visual gears do not affect the course of the game,
+ * no "synchronization" between players is required.
+ * => The usage of safe functions or data types (e.g. GetRandom() or hwFloat)
+ * is usually not necessary and therefore undesirable.
+ *)
+
 procedure doStepFlake(Gear: PVisualGear; Steps: Longword);
 var sign: real;
 begin

--- a/hedgewars/uGears.pas	Thu Apr 07 14:13:11 2011 -0400
+++ b/hedgewars/uGears.pas	Thu Apr 07 23:54:09 2011 +0200
@@ -19,6 +19,19 @@
 {$INCLUDE "options.inc"}
 
 unit uGears;
+(*
+ * This unit defines the behavior of gears.
+ *
+ * Gears are "things"/"objects" that may be visible to the player or not,
+ * but always have an effect on the course of the game.
+ *
+ * E.g.: weapons, hedgehogs, etc.
+ *
+ * Note: The visual appearance of gears is defined in the unit "uGearsRender".
+ *
+ * Note: Gears that do not have an effect on the game but are just visual
+ *       effects are called "Visual Gears" and defined in the respective unit!
+ *)
 interface
 uses SDLh, uConsts, uFloat, uTypes;
 
@@ -65,6 +78,10 @@
 procedure HHSetWeapon(HHGear: PGear); forward;
 procedure doStepCase(Gear: PGear); forward;
 
+// For better maintainability the step handlers of gears are stored in
+// separate files.
+// Note: step handlers of gears that are hedgehogs are in a different file
+//       than the handlers for all other gears.
 {$INCLUDE "GSHandlers.inc"}
 {$INCLUDE "HHHandlers.inc"}
 

--- a/hedgewars/uVisualGears.pas	Thu Apr 07 14:13:11 2011 -0400
+++ b/hedgewars/uVisualGears.pas	Thu Apr 07 23:54:09 2011 +0200
@@ -19,6 +19,15 @@
 {$INCLUDE "options.inc"}
 
 unit uVisualGears;
+(*
+ * This unit defines the behavior and the appearance of visual gears.
+ *
+ * Visual gears are "things"/"objects" in the game that do not need to be
+ * perfectly synchronized over all clients since their effect is only
+ * of visual nature.
+ *
+ * E.g.: background flakes, visual effects: explosion, smoke trails, etc.
+ *)
 interface
 uses uConsts, uFloat, GLunit, uTypes;
 
@@ -42,6 +51,8 @@
 
 const cExplFrameTicks = 110;
 
+// For better maintainability the step handlers of visual gears are stored
+// in a separate file.
 {$INCLUDE "VGSHandlers.inc"}
 
 procedure AddDamageTag(X, Y, Damage, Color: LongWord);