* beegee's comments patch

* very minor changes

CCallback.h

@@ -46,6 +46,7 @@ class CGGarrison;
 class CObstacleInstance;
 typedef std::vector<const CStack*> TStacks;
 
+/// Struct which holds a short information about a town
 struct InfoAboutTown
 {
 	struct Details

CConsoleHandler.h

@@ -18,6 +18,8 @@ namespace boost
 	class thread;
 }
 
+/// Class which wraps the native console. It can print text based on
+/// the chosen color
 class DLL_EXPORT CConsoleHandler
 {
 public:

CGameInterface.h

@@ -86,6 +86,7 @@ public:
 	virtual void battleStacksRemoved(const BattleStacksRemoved & bsr){}; //called when certain stack is completely removed from battlefield
 };
 
+/// Central class for managing human player / AI interface logic
 class CGameInterface : public CBattleGameInterface
 {
 public:

CThreadHelper.h

@@ -18,6 +18,7 @@
 
 typedef boost::function<void()> Task;
 
+/// Can assign CPU work to other threads/cores
 class CThreadHelper
 {
 	boost::mutex rtinm;

StartInfo.h

@@ -15,7 +15,7 @@
  *
  */
 
-
+/// Struct which describes the name, the color, the starting bonus of a player
 struct PlayerSettings
 {
 	enum Ebonus {brandom=-1,bartifact, bgold, bresource};
@@ -50,6 +50,7 @@ struct PlayerSettings
 	}
 };
 
+/// Struct which describes the difficulty, the turn time,.. of a heroes match.
 struct StartInfo
 {
 	enum EMode {NEW_GAME, LOAD_GAME, CAMPAIGN, DUEL, INVALID = 255};

client/AdventureMapButton.h

@@ -23,8 +23,8 @@ class CLabel;
 
 namespace config{struct ButtonInfo;}
 
-
-class CButtonBase : public KeyShortcut//basic button class
+/// Base class for buttons.
+class CButtonBase : public KeyShortcut
 {
 public:
 	enum ButtonState
@@ -60,6 +60,8 @@ public:
 	virtual ~CButtonBase(); //d-tor
 };
 
+/// Typical Heroes 3 button which can be inactive or active and can 
+/// hold further information if you right-click it
 class AdventureMapButton : public CButtonBase
 {
 	std::vector<std::string> imageNames;//store list of images that can be used by this button
@@ -87,6 +89,7 @@ public:
 	void setPlayerColor(int player);
 };
 
+/// A button which can be selected/deselected
 class CHighlightableButton 
 	: public AdventureMapButton
 {
@@ -101,6 +104,7 @@ public:
 	void clickLeft(tribool down, bool previousState);
 };
 
+/// A group of buttons where one button can be selected
 class CHighlightableButtonsGroup : public CIntObject
 {
 public:
@@ -120,7 +124,7 @@ public:
 	void block(ui8 on);
 };
 
-
+/// A typical slider which can be orientated horizontally/vertically.
 class CSlider : public CIntObject
 {
 public:

client/CAdvmapInterface.h

@@ -28,6 +28,7 @@ class IShipyard;
  *
  */
 
+/// Adventure options dialogue where you can view the world, dig, play the replay of the last turn,...
 class CAdventureOptions : public CIntObject
 {
 public:
@@ -39,7 +40,7 @@ public:
 	static void showScenarioInfo();
 };
 	 
-
+/// Minimap which is displayed at the right upper corner of adventure map
 class CMinimap : public CIntObject
 {
 public:
@@ -70,6 +71,8 @@ public:
 	void showTile(const int3 &pos); //removes FoW
 	void showVisibleTiles(int level=-1);// (level==-1) => redraw all levels
 };
+
+/// Holds information about which tiles of the terrain are shown/not shown at the screen
 class CTerrainRect
 	:  public CIntObject
 {
@@ -93,6 +96,9 @@ public:
 	int3 whichTileIsIt(const int & x, const int & y); //x,y are cursor position
 	int3 whichTileIsIt(); //uses current cursor pos
 };
+
+/// Resources bar which shows information about how many gold, crystals,... you have
+/// Current date is displayed too
 class CResDataBar
 	: public CIntObject
 {
@@ -111,6 +117,8 @@ public:
 	void draw(SDL_Surface * to);
 	void show(SDL_Surface * to);
 };
+
+/// Info box which shows next week/day information, hold the current date
 class CInfoBar : public CIntObject
 {
 public:
@@ -133,8 +141,11 @@ public:
 	void deactivate();
 	void updateSelection(const CGObjectInstance *obj);
 };
-/*****************************/
-class CAdvMapInt : public CIntObject //adventure map interface
+
+/// That's a huge class which handles general adventure map actions and 
+/// shows the right menu(questlog, spellbook, end turn,..) from where you 
+/// can get to the towns and heroes. 
+class CAdvMapInt : public CIntObject
 {
 public:
 	CAdvMapInt();

client/CAnimation.h

@@ -25,10 +25,8 @@ struct SDL_Surface;
 class SDLImageLoader;
 class CompImageLoader;
 
-/*
- * class for def loading, methods are based on CDefHandler
- * after loading will store general info (palette and frame offsets) and pointer to file itself
- */
+/// Class for def loading, methods are based on CDefHandler
+/// After loading will store general info (palette and frame offsets) and pointer to file itself
 class CDefFile
 {
 private:
@@ -254,9 +252,7 @@ public:
 	void showAll(SDL_Surface *to);
 };
 
-/*
- * Base class for displaying animation, used as superclass for different animations
- */
+/// Base class for displaying animation, used as superclass for different animations
 class CShowableAnim: public CIntObject
 {
 public:
@@ -312,9 +308,7 @@ public:
 	void showAll(SDL_Surface *to);
 };
 
-/*
- *
- */
+/// Creature-dependend animations like attacking, moving,... outside battles
 class CCreatureAnim: public CShowableAnim
 {
 public:

client/CBattleInterface.h

@@ -32,9 +32,9 @@ struct SetStackEffect;;
 struct BattleAction;
 class CGTownInstance;
 struct CatapultAttack;
-
 class CBattleInterface;
 
+/// Small struct which contains information about the id of the attacked stack, the damage dealt,...
 struct SStackAttackedInfo
 {
 	const CStack * defender; //attacked stack
@@ -45,6 +45,7 @@ struct SStackAttackedInfo
 	bool killed; //if true, stack has been killed
 };
 
+/// Small struct which contains information about the position and the velocity of a projectile
 struct SProjectileInfo
 {
 	int x, y; //position on the screen
@@ -57,8 +58,8 @@ struct SProjectileInfo
 	bool reverse; //if true, projectile will be flipped by vertical asix
 };
 
-//battle animation handlers
 
+/// Base class of battle animations
 class CBattleAnimation
 {
 protected:
@@ -88,6 +89,7 @@ public:
 	CDummyAnim(CBattleInterface * _owner, int howManyFrames);
 };
 
+/// This class manages a spell effect animation
 class CSpellEffectAnim : public CBattleAnimation
 {
 private:
@@ -105,6 +107,7 @@ public:
 	CSpellEffectAnim(CBattleInterface * _owner, std::string _customAnim, int _x, int _y, int _dx = 0, int _dy = 0, bool _Vflip = false);
 };
 
+/// Sub-class which is responsible for managing the battle stack animation.
 class CBattleStackAnimation : public CBattleAnimation
 {
 public:
@@ -115,6 +118,7 @@ public:
 	static bool isToReverse(THex hexFrom, THex hexTo, bool curDir /*if true, creature is in attacker's direction*/, bool toDoubleWide, bool toDir); //determines if creature should be reversed (it stands on hexFrom and should 'see' hexTo)
 };
 
+/// Class responsible for animation of stack chaning direction (left <-> right)
 class CReverseAnim : public CBattleStackAnimation
 {
 private:
@@ -130,6 +134,7 @@ public:
 	CReverseAnim(CBattleInterface * _owner, const CStack * stack, THex dest, bool _priority);
 };
 
+/// Animation of a defending unit
 class CDefenceAnim : public CBattleStackAnimation
 {
 private:
@@ -147,6 +152,7 @@ public:
 	CDefenceAnim(SStackAttackedInfo _attackedInfo, CBattleInterface * _owner);
 };
 
+/// Move animation of a creature
 class CBattleStackMoved : public CBattleStackAnimation
 {
 private:
@@ -165,6 +171,7 @@ public:
 	CBattleStackMoved(CBattleInterface * _owner, const CStack * _stack, THex _destHex, bool _endMoving, int _distance);
 };
 
+/// Move start animation of a creature
 class CBattleMoveStart : public CBattleStackAnimation
 {
 public:
@@ -175,6 +182,7 @@ public:
 	CBattleMoveStart(CBattleInterface * _owner, const CStack * _stack);
 };
 
+/// Move end animation of a creature
 class CBattleMoveEnd : public CBattleStackAnimation
 {
 private:
@@ -187,6 +195,7 @@ public:
 	CBattleMoveEnd(CBattleInterface * _owner, const CStack * _stack, THex destTile);
 };
 
+/// This class is responsible for managing the battle attack animation
 class CBattleAttack : public CBattleStackAnimation
 {
 protected:
@@ -205,6 +214,7 @@ public:
 	CBattleAttack(CBattleInterface * _owner, const CStack * attacker, THex _dest, const CStack * defender);
 };
 
+/// Hand-to-hand attack
 class CMeleeAttack : public CBattleAttack
 {
 public:
@@ -215,6 +225,7 @@ public:
 	CMeleeAttack(CBattleInterface * _owner, const CStack * attacker, THex _dest, const CStack * _attacked);
 };
 
+/// Shooting attack
 class CShootingAnim : public CBattleAttack
 {
 private:
@@ -230,7 +241,7 @@ public:
 
 //end of battle animation handlers
 
-
+/// Hero battle animation
 class CBattleHero : public CIntObject
 {
 public:
@@ -251,6 +262,7 @@ public:
 	~CBattleHero(); //d-tor
 };
 
+/// Class which stands for a single hex field on a battlefield
 class CBattleHex : public CIntObject
 {
 private:
@@ -272,11 +284,13 @@ public:
 	CBattleHex();
 };
 
+/// Class which manages the locked hex fields that are blocked e.g. by obstacles
 class CBattleObstacle
 {
 	std::vector<int> lockedHexes;
 };
 
+/// Class which shows the console at the bottom of the battle screen and manages the text of the console
 class CBattleConsole : public CIntObject
 {
 private:
@@ -296,6 +310,7 @@ public:
 	void scrollDown(unsigned int by = 1); //scrolls console up by 'by' positions
 };
 
+/// Class which is responsible for showing the battle result window
 class CBattleResultWindow : public CIntObject
 {
 private:
@@ -313,6 +328,7 @@ public:
 	void show(SDL_Surface * to = 0);
 };
 
+/// Class which manages the battle options window
 class CBattleOptionsWindow : public CIntObject
 {
 private:
@@ -333,6 +349,7 @@ public:
 	void show(SDL_Surface * to = 0);
 };
 
+/// Struct for battle effect animation e.g. morale, prayer, armageddon, bless,...
 struct SBattleEffect
 {
 	int x, y; //position on the screen
@@ -341,6 +358,7 @@ struct SBattleEffect
 	int effectID; //uniqueID equal ot ID of appropriate CSpellEffectAnim
 };
 
+/// Shows the stack queue
 class CStackQueue : public CIntObject
 {
 	class StackBox : public CIntObject
@@ -374,6 +392,8 @@ public:
 	//void showAll(SDL_Surface *to);
 };
 
+/// Big class which handles the overall battle interface actions and it is also responsible for
+/// drawing everything correctly.
 class CBattleInterface : public CIntObject
 {
 private:
@@ -421,6 +441,7 @@ private:
 
 	std::list<SBattleEffect> battleEffects; //different animations to display on the screen like spell effects
 
+	/// Class which is resposible for the wall of a siege during battle
 	class SiegeHelper
 	{
 	private:

client/CBitmapHandler.h

@@ -18,11 +18,13 @@ class CLodHandler;
 
 enum Epcxformat {PCX8B, PCX24B};
 
+/// Struct which stands for a simple rgba palette
 struct BMPPalette
 {
 	unsigned char R,G,B,F;
 };
 
+/// Class which converts pcx to bmp images
 class CPCXConv
 {	
 public:

client/CCastleInterface.h

@@ -30,6 +30,7 @@ class CMinorResDataBar;
  *
  */
 
+/// Building "button"
 class CBuildingRect : public CShowableAnim
 {
 public:
@@ -47,6 +48,7 @@ public:
 	void showAll(SDL_Surface *to);
 };
 
+/// Hero army slot
 class CHeroGSlot : public CIntObject
 {
 public:
@@ -65,8 +67,10 @@ public:
 	~CHeroGSlot(); //d-tor
 };
 
+/// Huge class which manages the castle window
 class CCastleInterface : public CWindowWithGarrison
 {
+	/// Creature info window
 	class CCreaInfo : public CIntObject
 	{
 	public:
@@ -79,6 +83,7 @@ class CCastleInterface : public CWindowWithGarrison
 		void clickRight(tribool down, bool previousState);
 		void show(SDL_Surface * to);
 	};
+	/// Town info which gets shown by right-clicking on a town at the map
 	class CTownInfo : public CIntObject
 	{
 	public:
@@ -141,11 +146,14 @@ public:
 	void recreateBuildings();
 	void recreateIcons();
 };
+
+/// Hall window where you can build things
 class CHallInterface : public CIntObject
 {
 public:
 	CMinorResDataBar * resdatabar;
 
+	/// The building information box which gets shown by right-clicking on a building image
 	class CBuildingBox : public CIntObject
 	{
 	public:
@@ -161,6 +169,7 @@ public:
 		~CBuildingBox(); //d-tor
 	};
 
+	/// The actual building window where you can decide to buy a building or not
 	class CBuildWindow: public CIntObject
 	{
 	public:
@@ -195,6 +204,7 @@ public:
 	void deactivate();
 };
 
+/// The fort screen where you can afford units
 class CFortScreen : public CIntObject
 {
 	class RecArea : public CIntObject
@@ -225,6 +235,7 @@ public:
 	void deactivate();
 };
 
+/// The mage guild screen where you can see which spells you have
 class CMageGuildScreen : public CIntObject
 {
 public:
@@ -252,6 +263,7 @@ public:
 
 };
 
+/// The blacksmith window where you can buy one of the three war machines
 class CBlacksmithDialog : public CIntObject
 {
 public:

client/CConfigHandler.h

@@ -15,6 +15,7 @@ class CAdvMapInt;
 
 namespace config
 {
+	/// Struct holds data about client resolution, colors, fullscreen mode
 	struct ClientConfig
 	{
 		int resx, resy, bpp, fullscreen; //client resolution/colours
@@ -24,6 +25,7 @@ namespace config
 		std::string server, //server address (e.g. 127.0.0.1)
 			defaultAI; //dll name
 	};
+	
 	struct ButtonInfo
 	{
 		std::string defName;
@@ -31,6 +33,7 @@ namespace config
 		int x, y; //position on the screen
 		bool playerColoured; //if true button will be colored to main player's color (works properly only for appropriate 8bpp graphics)
 	};
+	/// Struct which holds data about position of several GUI elements at the adventure map screen
 	struct AdventureMapConfig
 	{
 		//minimap properties
@@ -71,6 +74,7 @@ namespace config
 	{
 		AdventureMapConfig ac;
 	};
+	/// Handles adventure map screen settings
 	class CConfigHandler
 	{
 	public:

client/CCreatureAnimation.h

@@ -20,6 +20,7 @@
 
 struct BMPPalette;
 
+/// Class which manages animations of creatures/units inside battles
 class CCreatureAnimation : public CIntObject
 {
 private:

client/CCursorHandler.h

@@ -16,7 +16,8 @@ struct SDL_Surface;
  *
  */
 
-class CCursorHandler //handles cursor
+/// handles mouse cursor
+class CCursorHandler 
 {
 public:
 	int mode, number;

client/CGameInfo.h

@@ -45,10 +45,8 @@ public:
 
 struct Mapa;
 
-/*
-	CGameInfo class
-	for allowing different functions for accessing game informations
-*/
+/// CGameInfo class
+/// for allowing different functions for accessing game informations
 class CGameInfo
 {
 	ConstTransitivePtr<CGameState> state; //don't touch it in client's code

client/CHeroWindow.h

@@ -25,6 +25,7 @@ class LRClickableAreaWText;
 class LRClickableAreaWTextComp;
 class CArtifactsOfHero;
 
+/// Button which switches hero selection
 class CHeroSwitcher : public CIntObject
 {
 public:

client/CKingdomInterface.h

@@ -25,6 +25,7 @@ class MoraleLuckBox;
  *
  */
 
+/// Huge class responsible for viewing and handling kingdom view, where you can see all your towns, flagged mines and heroes
 class CKingdomInterface : public CGarrisonHolder
 {
 	class CTownItem : public CWindowWithGarrison

client/CMessage.h

@@ -56,6 +56,7 @@ struct ComponentsToBlit
 	~ComponentsToBlit(); //d-tor
 };
 
+/// Class which draws formatted text messages and generates chat windows
 class CMessage
 {
 public:

client/CPlayerInterface.h

@@ -74,6 +74,7 @@ namespace boost
 	class recursive_mutex;
 };
 
+/// Stores information about system options like hero move speed, map scrolling speed, creature animation speed,...
 struct SystemOptions
 {
 	std::string playerName;
@@ -109,6 +110,7 @@ struct SystemOptions
 
 extern SystemOptions GDefaultOptions; //defined and inited in CMT.cpp, stores default settings loaded with application
 
+/// Central class for managing user interface logic
 class CPlayerInterface : public CGameInterface, public IUpdateable
 {
 public:

client/CPreGame.h

@@ -34,6 +34,7 @@ namespace boost{ class thread; class recursive_mutex;}
 
 enum ESortBy{_playerAm, _size, _format, _name, _viccon, _loscon, _numOfMaps}; //_numOfMaps is for campaigns
 
+/// Class which handles map sorting by different criteria
 class mapSorter
 {
 public:
@@ -42,6 +43,7 @@ public:
 	mapSorter(ESortBy es):sortBy(es){};
 };
 
+/// The main menu screens listed in the EState enum
 class CMenuScreen : public CIntObject
 {
 public:
@@ -63,7 +65,7 @@ public:
 	void moveTo(CMenuScreen *next);
 };
 
-
+/// Struct which stores name, date and a value which says if the file is located in LOD
 struct FileInfo
 {
 	std::string name; // file name with full path and extension
@@ -71,6 +73,7 @@ struct FileInfo
 	bool inLod; //tells if this file is located in Lod
 };
 
+/// Implementation of the chat box
 class CChatBox : public CIntObject
 {
 public:
@@ -109,6 +112,7 @@ public:
 	~InfoCard();
 };
 
+/// The selection tab which is shown at the map selection screen
 class SelectionTab : public CIntObject
 {
 private:
@@ -153,6 +157,7 @@ public:
 	~SelectionTab();
 };
 
+/// The options tab which is shown at the map selection phase.
 class OptionsTab : public CIntObject
 {
 	CPicture *bg;
@@ -218,6 +223,7 @@ public:
 	bool canUseThisHero( int ID );
 };
 
+/// Interface for selecting a map.
 class ISelectionScreenInfo
 {
 public:
@@ -243,6 +249,7 @@ public:
 
 };
 
+/// The actual map selection screen which consists of the options and selection tab
 class CSelectionScreen : public CIntObject, public ISelectionScreenInfo
 {
 public:
@@ -281,6 +288,7 @@ public:
 	void propagateNames();
 };
 
+/// Save game screen
 class CSavingScreen : public CSelectionScreen
 {
 public:
@@ -291,7 +299,7 @@ public:
 	~CSavingScreen();
 };
 
-//scenario information screen shown during the game (thus not really a "pre-game" but fits here anyway)
+/// Scenario information screen shown during the game (thus not really a "pre-game" but fits here anyway)
 class CScenarioInfo : public CIntObject, public ISelectionScreenInfo
 {
 public:
@@ -303,6 +311,7 @@ public:
 	~CScenarioInfo();
 };
 
+/// Multiplayer mode
 class CMultiMode : public CIntObject
 {
 public:
@@ -317,6 +326,7 @@ public:
 	void joinTCP();
 };
 
+/// Hot seat player window
 class CHotSeatPlayers : public CIntObject
 {
 public:
@@ -329,6 +339,7 @@ public:
 	void enterSelectionScreen();
 };
 
+/// Campaign screen where you can choose one out of three starting bonuses
 class CBonusSelection : public CIntObject
 {
 	SDL_Surface * background;
@@ -405,6 +416,7 @@ public:
 	void startMap();
 };
 
+/// Handles background screen, loads graphics for victory/loss condition and random town or hero selection
 class CGPreGame : public CIntObject, public IUpdateable
 {
 public:

client/CSpellWindow.h

@@ -22,6 +22,7 @@ struct SDL_Rect;
 class CGHeroInstance;
 class CStatusBar;
 
+/// Spellbook button is used by the spell window class
 class SpellbookInteractiveArea : public CIntObject
 {
 private:
@@ -39,6 +40,7 @@ public:
 		boost::function<void()> funcHon, boost::function<void()> funcHoff, CPlayerInterface * _myInt);//c-tor
 };
 
+/// The spell window
 class CSpellWindow : public CIntObject
 {
 private:

client/CVideoHandler.cpp

@@ -941,5 +941,5 @@ CVideoPlayer::~CVideoPlayer()
 }
 
 #endif
-
- 	  	 
+
+ 	  	 

client/Client.h

@@ -32,7 +32,7 @@ namespace boost { class thread; }
 
 void processCommand(const std::string &message, CClient *&client);
 
-//structure to handle running server and connecting to it
+/// structure to handle running server and connecting to it
 class CServerHandler
 {
 private:
@@ -56,6 +56,7 @@ public:
 	~CServerHandler();
 };
 
+/// Class which handles client - server logic
 class CClient : public IGameCallback
 {
 public:

client/FontBase.h

@@ -15,7 +15,8 @@ enum EFonts
 {
 	FONT_BIG, FONT_CALLI, FONT_CREDITS, FONT_HIGH_SCORE, FONT_MEDIUM, FONT_SMALL, FONT_TIMES, FONT_TINY, FONT_VERD
 };
-
+
+
 struct Font
 {
 	struct Char

client/FunctionList.h

@@ -14,6 +14,7 @@
  *
  */
 
+/// List of functions that share the same signature - can be used to call all of them easily
 template<typename Signature>
 class CFunctionList
 {

client/GUIBase.h

@@ -56,6 +56,7 @@ class CGTownInstance;
 class StackState;
 class CPlayerInterface;
 
+/// A point with x/y coordinate, used mostly for graphic rendering
 struct Point
 {
 	int x, y;
@@ -122,6 +123,7 @@ struct Point
 	}
 };
 
+/// Rectangle class, which have a position and a size
 struct Rect : public SDL_Rect
 {
 	Rect()//default c-tor
@@ -276,6 +278,7 @@ struct Rect : public SDL_Rect
 	}
 };
 
+/// Defines a show method
 class IShowable
 {
 public:
@@ -288,6 +291,7 @@ public:
 	virtual ~IShowable(){}; //d-tor
 };
 
+/// Status bar interface
 class IStatusBar
 {
 public:
@@ -298,6 +302,7 @@ public:
 	virtual std::string getCurrent()=0; //returns currently displayed text
 };
 
+/// Defines a activate/deactive method
 class IActivable
 {
 public:
@@ -305,6 +310,8 @@ public:
 	virtual void deactivate()=0;
 	virtual ~IActivable(){}; //d-tor
 };
+
+
 class IShowActivable : public IShowable, public IActivable
 {
 public:
@@ -314,6 +321,7 @@ public:
 	virtual ~IShowActivable(){}; //d-tor
 };
 
+
 class IUpdateable
 {
 public:
@@ -321,6 +329,7 @@ public:
 	virtual ~IUpdateable(){}; //d-tor
 };
 
+/// Base UI element
 class CIntObject : public IShowActivable //interface object
 {
 public:
@@ -431,8 +440,8 @@ public:
 	}
 };
 
-//class for binding keys to left mouse button clicks
-//classes wanting use it should have it as one of their base classes
+/// Class for binding keys to left mouse button clicks
+/// Classes wanting use it should have it as one of their base classes
 class KeyShortcut : public virtual CIntObject
 {
 public:
@@ -443,7 +452,8 @@ public:
 	virtual void keyPressed(const SDL_KeyboardEvent & key); //call-in
 };
 
-class CGarrisonHolder : public virtual CIntObject// to unify updating garrisons via PlayerInterface
+/// to unify updating garrisons via PlayerInterface
+class CGarrisonHolder : public virtual CIntObject
 {
 public:
 	CGarrisonHolder();
@@ -456,7 +466,7 @@ public:
 	CGarrisonInt *garr;
 	virtual void updateGarrisons();
 };
-
+/// Window GUI class
 class CSimpleWindow : public CIntObject
 {
 public:
@@ -465,7 +475,7 @@ public:
 	CSimpleWindow():bitmap(NULL){}; //c-tor
 	virtual ~CSimpleWindow(); //d-tor
 };
-
+/// Image class
 class CPicture : public CIntObject
 {
 public: 
@@ -494,6 +504,7 @@ public:
 	void colorizeAndConvert(int player);
 };
 
+/// Handles GUI logic and drawing
 class CGuiHandler
 {
 public:

client/GUIClasses.h

@@ -73,7 +73,8 @@ class CArtifactInstance;
 
 extern SDL_Color tytulowy, tlo, zwykly ;
 
-class CInfoWindow : public CSimpleWindow //text + comp. + ok button
+/// text + comp. + ok button
+class CInfoWindow : public CSimpleWindow 
 { //window able to delete its components when closed
 	bool delComps; //whether comps will be deleted
 
@@ -98,7 +99,9 @@ public:
 	static void showYesNoDialog( const std::string & text, const std::vector<SComponent*> *components, const CFunctionList<void( ) > &onYes, const CFunctionList<void()> &onNo, bool DelComps = true, int player = 1); //use only before the game starts! (showYesNoDialog in LOCPLINT must be used then)
 	static CInfoWindow *create(const std::string &text, int playerID = 1, const std::vector<SComponent*> *components = NULL, bool DelComps = false);
 };
-class CSelWindow : public CInfoWindow //component selection window
+
+/// component selection window
+class CSelWindow : public CInfoWindow 
 { //warning - this window deletes its components by closing!
 public:
 	void selectionChange(unsigned to);
@@ -108,7 +111,8 @@ public:
 	//notification - this class inherits important destructor from CInfoWindow
 };
 
-class CRClickPopup : public CIntObject //popup displayed on R-click
+/// popup displayed on R-click
+class CRClickPopup : public CIntObject 
 {
 public:
 	virtual void activate();
@@ -123,7 +127,8 @@ public:
 	static void createAndPush(const CGObjectInstance *obj, const Point &p, EAlignment alignment = BOTTOMRIGHT);
 };
 
-class CRClickPopupInt : public CRClickPopup //popup displayed on R-click
+/// popup displayed on R-click
+class CRClickPopupInt : public CRClickPopup 
 {
 public:
 	IShowActivable *inner;
@@ -150,7 +155,8 @@ public:
 	~CInfoPopup(); //d-tor
 };
 
-class SComponent : public virtual CIntObject //common popup window component
+/// common popup window component
+class SComponent : public virtual CIntObject
 {
 public:
 	enum Etype
@@ -198,6 +204,8 @@ public:
 	void select(bool on);
 };
 class CGarrisonInt;
+
+/// A single garrison slot which holds one creature of a specific amount
 class CGarrisonSlot : public CIntObject
 {
 public:
@@ -221,6 +229,7 @@ public:
 	~CGarrisonSlot(); //d-tor
 };
 
+/// Class which manages slots of upper and lower garrison, splitting of units
 class CGarrisonInt :public CIntObject
 {
 public:
@@ -262,6 +271,7 @@ public:
 	~CGarrisonInt(); //d-tor
 };
 
+/// Status bar which is shown at the bottom of the in-game screens
 class CStatusBar
 	: public CIntObject, public IStatusBar
 {
@@ -278,6 +288,7 @@ public:
 	std::string getCurrent(); //getter for current
 };
 
+/// Label which shows text
 class CLabel
 	: public virtual CIntObject
 {
@@ -296,7 +307,7 @@ public:
 	CLabel(int x=0, int y=0, EFonts Font = FONT_SMALL, EAlignment Align = TOPLEFT, const SDL_Color &Color = zwykly, const std::string &Text =  "");
 };
 
-//a multi-line label that tries to fit text with given available width and height; if not possible, it creates a slider for scrolling text
+/// a multi-line label that tries to fit text with given available width and height; if not possible, it creates a slider for scrolling text
 class CTextBox
 	: public CLabel
 {
@@ -320,6 +331,7 @@ public:
 	void sliderMoved(int to);
 };
 
+/// Status bar which is shown at the bottom of the in-game screens
 class CGStatusBar
 	: public CLabel, public IStatusBar
 {
@@ -341,6 +353,7 @@ public:
 	void calcOffset();
 };
 
+/// UIElement which can get input focus
 class CFocusable 
 	: public virtual CIntObject
 {
@@ -356,6 +369,7 @@ public:
 	~CFocusable();
 };
 
+/// Text input box where players can enter text
 class CTextInput
 	: public CLabel, public CFocusable
 {
@@ -372,6 +386,7 @@ public:
 	void keyPressed(const SDL_KeyboardEvent & key);
 };
 
+/// Listbox UI Element
 class CList : public CIntObject
 {
 public:
@@ -396,6 +411,8 @@ public:
 	virtual int size() = 0; //how many elements do we have
 	void fixPos(); //scrolls list, so the selection will be visible
 };
+
+/// List of heroes which is shown at the right of the adventure map screen
 class CHeroList
 	: public CList
 {
@@ -420,6 +437,7 @@ public:
 	int size(); //how many elements do we have
 };
 
+/// List of towns which is shown at the right of the adventure map screen
 class CTownList
 	: public CList
 {
@@ -441,7 +459,8 @@ public:
 	int size(); //how many elements do we have
 };
 
-class CCreaturePic : public CIntObject //draws picture with creature on background, use Animated=true to get animation
+/// draws picture with creature on background, use Animated=true to get animation
+class CCreaturePic : public CIntObject 
 {
 private:
 	CPicture *bg; //background
@@ -452,6 +471,7 @@ public:
 	~CCreaturePic(); //d-tor
 };
 
+/// Recruitment window where you can recruit creatures
 class CRecruitmentWindow : public CIntObject
 {
 public:
@@ -492,6 +512,7 @@ public:
 	~CRecruitmentWindow(); //d-tor
 };
 
+/// Split window where creatures can be splitted up into two single unit stacks
 class CSplitWindow : public CIntObject
 {
 public:
@@ -516,6 +537,7 @@ public:
 	void sliderMoved(int to);
 };
 
+/// Raised up level windowe where you can select one out of two skills
 class CLevelWindow : public CIntObject
 {
 public:
@@ -534,6 +556,7 @@ public:
 	void show(SDL_Surface * to);
 };
 
+/// Resource bar like that at the bottom of the adventure map screen
 class CMinorResDataBar : public CIntObject
 {
 public:
@@ -544,6 +567,7 @@ public:
 	~CMinorResDataBar(); //d-tor
 };
 
+/// Town portal, castle gate window
 class CObjectListWindow : public CIntObject
 {
 public:
@@ -811,6 +835,7 @@ public:
 	CInGameConsole(); //c-tor
 };
 
+/// Shows a text by moving the mouse cursor over the object
 class HoverableArea: public virtual CIntObject
 {
 public:
@@ -822,6 +847,7 @@ public:
 	virtual ~HoverableArea();
 };
 
+/// Can interact on left and right mouse clicks, plus it shows a text when by hovering over it
 class LRClickableAreaWText: public HoverableArea
 {
 public:
@@ -836,6 +862,7 @@ public:
 	virtual void clickRight(tribool down, bool previousState);
 };
 
+/// Can interact on left and right mouse clicks
 class LRClickableAreaWTextComp: public LRClickableAreaWText
 {
 public:
@@ -858,6 +885,7 @@ public:
 	~MoraleLuckBox();
 };
 
+/// Opens hero window by left-clicking on it
 class CHeroArea: public CIntObject
 {
 public:
@@ -871,7 +899,7 @@ public:
 	void showAll(SDL_Surface * to);
 };
 
-
+/// Opens town screen by left-clicking on it
 class LRClickableAreaOpenTown: public LRClickableAreaWTextComp
 {
 public:
@@ -881,6 +909,7 @@ public:
 	LRClickableAreaOpenTown();
 };
 
+/// Creature info window
 class CCreInfoWindow : public CIntObject
 {
 public:
@@ -912,6 +941,7 @@ public:
 	void show(SDL_Surface * to);
 };
 
+/// Artifacts can be placed there. Gets shown at the hero window
 class CArtPlace: public LRClickableAreaWTextComp
 {
 public:
@@ -939,6 +969,7 @@ public:
 	~CArtPlace(); //d-tor
 };
 
+/// Contains artifacts of hero. Distincts which artifacts are worn or backpacked
 class CArtifactsOfHero : public CIntObject
 {
 	const CGHeroInstance * curHero; //local copy of hero on which we operate
@@ -997,6 +1028,7 @@ public:
 	friend class CArtPlace;
 };
 
+/// Garrison window where you can take creatures out of the hero to place it on the garrison
 class CGarrisonWindow : public CWindowWithGarrison
 {
 public:
@@ -1043,6 +1075,7 @@ public:
 	~CExchangeWindow(); //d-tor
 };
 
+/// Here you can buy ships
 class CShipyardWindow : public CIntObject
 {
 public:
@@ -1060,6 +1093,7 @@ public:
 	~CShipyardWindow();
 };
 
+/// Puzzle screen which gets uncovered when you visit obilisks
 class CPuzzleWindow : public CIntObject
 {
 private:
@@ -1079,6 +1113,7 @@ public:
 	~CPuzzleWindow();
 };
 
+/// Creature transformer window
 class CTransformerWindow : public CIntObject
 {
 public:
@@ -1143,8 +1178,8 @@ public:
 	~CUniversityWindow(); //d-tor
 };
 
-
-class CUnivConfirmWindow : public CIntObject//Confirmation window for University
+/// Confirmation window for University
+class CUnivConfirmWindow : public CIntObject
 {
 public:
 	CUniversityWindow * parent;
@@ -1156,6 +1191,7 @@ public:
 	void makeDeal(int skill);
 };
 
+/// Hill fort is the building where you can upgrade units
 class CHillFortWindow : public CWindowWithGarrison
 {
 public:

client/Graphics.h

@@ -29,6 +29,7 @@ class CGDefInfo;
 
 typedef struct _TTF_Font TTF_Font; //from SDL_ttf.h
 
+/// Handles fonts, hero images, town images, various graphics
 class Graphics
 {
 public:

int3.h

@@ -13,6 +13,7 @@
 
 #include <cmath>
 
+/// Class which consists of three integer values. Represents position on adventure map.
 class int3
 {
 public:

lib/BattleAction.h

@@ -13,6 +13,7 @@
  *
  */
 
+/// A struct which handles battle actions like defending, walking,... - represents a creature stack in a battle
 class CStack;
 
 struct DLL_EXPORT BattleAction

lib/BattleState.cpp

@@ -1665,7 +1665,7 @@ SpellCasting::ESpellCastProblem BattleInfo::battleCanCastThisSpell( int player,
 				case 1:
 					if(stack->owner == caster->getOwner())
 					{
-						if(canCastHereLower(player, spell, mode, stack->position) == SpellCasting::OK)
+						if(battleIsImmune(player, spell, mode, stack->position) == SpellCasting::OK)
 						{
 							targetExists = true;
 							break;
@@ -1673,7 +1673,7 @@ SpellCasting::ESpellCastProblem BattleInfo::battleCanCastThisSpell( int player,
 					}
 					break;
 				case 0:
-					if(canCastHereLower(player, spell, mode, stack->position) == SpellCasting::OK)
+					if(battleIsImmune(player, spell, mode, stack->position) == SpellCasting::OK)
 					{
 						targetExists = true;
 						break;
@@ -1682,7 +1682,7 @@ SpellCasting::ESpellCastProblem BattleInfo::battleCanCastThisSpell( int player,
 				case -1:
 					if(stack->owner != caster->getOwner())
 					{
-						if(canCastHereLower(player, spell, mode, stack->position) == SpellCasting::OK)
+						if(battleIsImmune(player, spell, mode, stack->position) == SpellCasting::OK)
 						{
 							targetExists = true;
 							break;
@@ -1710,7 +1710,7 @@ SpellCasting::ESpellCastProblem BattleInfo::battleCanCastThisSpellHere( int play
 	if(moreGeneralProblem != SpellCasting::OK)
 		return moreGeneralProblem;
 
-	return canCastHereLower(player, spell, mode, dest);
+	return battleIsImmune(player, spell, mode, dest);
 }
 
 const CGHeroInstance * BattleInfo::getHero( int player ) const
@@ -1721,7 +1721,7 @@ const CGHeroInstance * BattleInfo::getHero( int player ) const
 	return heroes[1];
 }
 
-SpellCasting::ESpellCastProblem BattleInfo::canCastHereLower( int player, const CSpell * spell, ECastingMode mode, THex dest ) const
+SpellCasting::ESpellCastProblem BattleInfo::battleIsImmune( int player, const CSpell * spell, ECastingMode mode, THex dest ) const
 {
 	const CStack * subject = getStackT(dest, false);
 	const CGHeroInstance * caster = mode == HERO_CASTING ? getHero(player) : NULL;

lib/BattleState.h

@@ -120,9 +120,7 @@ struct DLL_EXPORT BattleInfo : public CBonusSystemNode
 
 	SpellCasting::ESpellCastProblem battleCanCastSpell(int player, ECastingMode mode) const; //returns true if there are no general issues preventing from casting a spell
 	SpellCasting::ESpellCastProblem battleCanCastThisSpell(int player, const CSpell * spell, ECastingMode mode) const; //checks if given player can cast given spell
-private:
-	SpellCasting::ESpellCastProblem canCastHereLower(int player, const CSpell * spell, ECastingMode mode, THex dest) const; //same as battleCanCastThisSpellHere, but doesn't refer to battleCanCastThisSpell
-public:
+	SpellCasting::ESpellCastProblem battleIsImmune(int player, const CSpell * spell, ECastingMode mode, THex dest) const; //checks for creature immunity / anything that prevent casting *at given hex* - doesn't take into acount general problems such as not having spellbook or mana points etc.
 	SpellCasting::ESpellCastProblem battleCanCastThisSpellHere(int player, const CSpell * spell, ECastingMode mode, THex dest); //checks if given player can cast given spell at given tile in given mode
 
 	bool battleCanFlee(int player) const; //returns true if player can flee from the battle

lib/CMapInfo.h

@@ -6,7 +6,8 @@ class CMapHeader;
 class CCampaignHeader;
 struct StartInfo;
 
-
+/// A class which stores the count of human players and all players, the filename,
+/// scenario options, the map header information,...
 class DLL_EXPORT CMapInfo
 {
 public:

lib/CondSh.h

@@ -12,6 +12,7 @@
  *
  */
 
+/// Used for multithreading, wraps boost functions
 template <typename T> struct CondSh
 {
 	T data;

lib/Connection.h

@@ -244,6 +244,7 @@ struct VectorisedObjectInfo
 	}
 };
 
+/// Class which is responsible for storing and loading data.
 class DLL_EXPORT CSerializer
 {
 public:
@@ -349,6 +350,7 @@ struct VectorisedTypeFor
 		>::type type;
 };
 
+/// The class which manages saving objects.
 template <typename Serializer> class DLL_EXPORT COSer : public CSaverBase
 {
 public:
@@ -587,6 +589,7 @@ public:
 	}
 };
 
+/// The class which manages loading of objects.
 template <typename Serializer> class DLL_EXPORT CISer : public CLoaderBase
 {
 public:

lib/HeroBonus.h

@@ -157,6 +157,7 @@ namespace PrimarySkill
 	BONUS_NAME(CREATURE_DAMAGE)/*subtype 0 = both, 1 = min, 2 = max*/\
 	BONUS_NAME(EXP_MULTIPLIER)/* val - percent of additional exp gained by stack/commander (base value 100)*/
 
+/// Struct for handling bonuses of several types. Can be transfered to any hero
 struct DLL_EXPORT Bonus
 {
 	enum BonusType
@@ -472,7 +473,7 @@ namespace NBonus
 	DLL_EXPORT int getCount(const CBonusSystemNode *obj, int from, int id);
 };
 
-//generates HeroBonus from given data
+/// generates HeroBonus from given data
 inline Bonus makeFeatureVal(Bonus::BonusType type, ui8 duration, si16 subtype, si32 value, Bonus::BonusSource source, ui16 turnsRemain = 0, si32 additionalInfo = 0)
 {
 	Bonus sf;

lib/IGameCallback.h

@@ -41,6 +41,7 @@ struct StackLocation;
 struct ArtifactLocation;
 class CArtifactInstance;
 
+/// Interface class for handling general game logic and actions
 class DLL_EXPORT IGameCallback
 {
 protected:

lib/RegisterTypes.cpp

@@ -1,5 +1,3 @@
-
-
 #include "Connection.h"
 #include "NetPacks.h"
 #include "VCMI_Lib.h"

lib/VCMIDirs.h

@@ -14,7 +14,7 @@
 #endif
 
 
-/* Where to find the various VCMI files. This is mostly usefull for linux. */
+/// Where to find the various VCMI files. This is mostly usefull for linux. 
 class VCMIDirs {
 public:
 	std::string UserPath;

lib/VCMI_Lib.h

@@ -23,6 +23,7 @@ class CDefObjInfoHandler;
 class CTownHandler;
 class CGeneralTextHandler;
 
+/// Loads and constructs several handlers
 class DLL_EXPORT LibClasses
 {
 public:

lib/map.h

@@ -35,7 +35,7 @@ class CQuest;
 class CGTownInstance;
 class IModableArt;
 
-
+/// Struct which describes a single terrain tile
 struct DLL_EXPORT TerrainTile
 {
 	enum EterrainType {border=-1, dirt, sand, grass, snow, swamp, rough, subterranean, lava, water, rock};
@@ -71,7 +71,9 @@ struct DLL_EXPORT TerrainTile
 	bool entrableTerrain(bool allowLand, bool allowSea) const; //checks if terrain is not a rock. If from is water/land, same type is also required. 
 	bool isClear(const TerrainTile *from = NULL) const; //checks for blocking objs and terraint type (water / land)
 };
-struct DLL_EXPORT SheroName //name of starting hero
+
+/// name of starting hero
+struct DLL_EXPORT SheroName 
 {
 	int heroID;
 	std::string heroName;
@@ -81,6 +83,9 @@ struct DLL_EXPORT SheroName //name of starting hero
 		h & heroID & heroName;
 	}
 };
+
+/// Player information regarding map. Which factions are allowed, AI tactic setting, main hero name, 
+/// position of main town,...
 struct DLL_EXPORT PlayerInfo
 {
 	si32 p7, p8, p9;
@@ -136,6 +141,8 @@ struct DLL_EXPORT PlayerInfo
 			posOfMainTown & team & generateHero;
 	}
 };
+
+/// Small struct which holds information about the loss condition
 struct DLL_EXPORT LossCondition
 {
 	ElossCon typeOfLossCon;
@@ -153,6 +160,8 @@ struct DLL_EXPORT LossCondition
 
 	LossCondition();
 };
+
+/// Small struct which holds information about the victory condition
 struct DLL_EXPORT CVictoryCondition
 {
 	EvictoryConditions condition; //ID of condition
@@ -172,6 +181,7 @@ struct DLL_EXPORT CVictoryCondition
 	}
 };
 
+/// Struct which holds a name and the rumor text
 struct DLL_EXPORT Rumor
 {
 	std::string name, text;
@@ -182,6 +192,7 @@ struct DLL_EXPORT Rumor
 	}
 };
 
+/// Struct which describes who can hire this hero
 struct DLL_EXPORT DisposedHero
 {
 	ui32 ID;
@@ -195,6 +206,7 @@ struct DLL_EXPORT DisposedHero
 	}
 };
 
+/// Class which manages map events.
 class DLL_EXPORT CMapEvent
 {
 public:
@@ -221,6 +233,8 @@ public:
 	}
 };
 
+/// Sub-class derived by CMapEvent; This event can build specific buildings or add 
+/// additional creatures in a town.
 class DLL_EXPORT CCastleEvent: public CMapEvent
 {
 public:
@@ -235,6 +249,7 @@ public:
 	}
 };
 
+/// Holds information about loss/victory condition, map format, version, players, height, width,...
 class DLL_EXPORT CMapHeader
 {
 public:
@@ -267,6 +282,8 @@ public:
 	}
 };
 
+/// Extends the base class and adds further map information like rumors, disposed heroes, 
+/// allowed spells, artifacts, abilities and such things.
 struct DLL_EXPORT Mapa : public CMapHeader
 {
 	ui32 checksum;

server/CGameHandler.cpp

@@ -4870,22 +4870,16 @@ void CGameHandler::runBattle()
 	}
 
 	//spells opening battle
-	if (gs->curB->heroes[0] && gs->curB->heroes[0]->hasBonusOfType(Bonus::OPENING_BATTLE_SPELL))
+	for(int i=0; i<ARRAY_COUNT(gs->curB->heroes); ++i)
 	{
-		BonusList bl;
-		gs->curB->heroes[0]->getBonuses(bl, Selector::type(Bonus::OPENING_BATTLE_SPELL));
-		BOOST_FOREACH (Bonus *b, bl)
+		if(gs->curB->heroes[i] && gs->curB->heroes[i]->hasBonusOfType(Bonus::OPENING_BATTLE_SPELL))
 		{
-			handleSpellCasting(b->subtype, 3, -1, 0, gs->curB->heroes[0]->tempOwner, NULL, gs->curB->heroes[1], b->val);
-		}
-	}
-	if (gs->curB->heroes[1] && gs->curB->heroes[1]->hasBonusOfType(Bonus::OPENING_BATTLE_SPELL))
-	{
-		BonusList bl;
-		gs->curB->heroes[1]->getBonuses(bl, Selector::type(Bonus::OPENING_BATTLE_SPELL));
-		BOOST_FOREACH (Bonus *b, bl)
-		{
-			handleSpellCasting(b->subtype, 3, -1, 1, gs->curB->heroes[1]->tempOwner, NULL, gs->curB->heroes[0], b->val);
+			BonusList bl;
+			gs->curB->heroes[i]->getBonuses(bl, Selector::type(Bonus::OPENING_BATTLE_SPELL));
+			BOOST_FOREACH (Bonus *b, bl)
+			{
+				handleSpellCasting(b->subtype, 3, -1, 0, gs->curB->heroes[i]->tempOwner, NULL, gs->curB->heroes[1-i], b->val);
+			}
 		}
 	}