add dox

This was SVN commit r2513.

source/scripting/DOMEvent.cpp

@@ -43,6 +43,8 @@ bool IEventTarget::_DispatchEvent( CScriptEvent* evt, IEventTarget* target )
 	return( false );
 }
 
+// Dispatch an event to its handler.
+// returns: whether the event arrived (i.e. wasn't cancelled) [bool]
 bool IEventTarget::DispatchEvent( CScriptEvent* evt )
 {
 	const char* data = g_Profiler.InternString( "script: " + (CStr8)evt->m_Type );

source/scripting/DOMEvent.h

@@ -2,14 +2,17 @@
 //
 // Mark Thompson (mot20@cam.ac.uk / mark@wildfiregames.com)
 
-// Note: Cancellable? Cancelable? DOM says one l, OED says 2. JS interface uses 1.
+// Note: Cancellable [UK]? Cancelable [US]? DOM says one l, OED says 2.
+//       JS interface uses 1.
+
+// Entity and e.g. projectile classes derive from this and use it for
+// sending/receiving events.
 
 #ifndef DOMEVENT_INCLUDED
 #define DOMEVENT_INCLUDED
 
 #include "ScriptableObject.h"
-
-#include "EventTypes.h"
+#include "EventTypes.h"	// for EVENT_LAST
 
 class CScriptObject;
 class CScriptEvent;
@@ -38,24 +41,40 @@ public:
 		after = NULL;
 	}
 	~IEventTarget();
-	inline void SetPriorObject( IEventTarget* obj ) { before = obj; }
-	inline void SetNextObject( IEventTarget* obj ) { after = obj; }
+	// Set target that will receive each event after it is processed.
+	// unused
+	inline void SetPriorObject( IEventTarget* obj )
+	{
+		before = obj;
+	}
+	// Set target that will receive each event after it is processed.
+	// used by Entity and BaseEntity.
+	inline void SetNextObject( IEventTarget* obj )
+	{
+		after = obj;
+	}
 
+	// Register a handler for the given event type.
 	// Returns false if the handler was already present
 	bool AddHandler( int TypeCode, DOMEventHandler handler );
 	bool AddHandler( CStrW TypeString, DOMEventHandler handler );
+	// Remove a previously registered handler for the specified event.
 	// Returns false if the handler was not present
 	bool RemoveHandler( int TypeCode, DOMEventHandler handler );
 	bool RemoveHandler( CStrW TypeString, DOMEventHandler handler );
-	
+
+	// called by ScriptGlue.cpp for add|RemoveGlobalHandler
 	bool AddHandlerJS( JSContext* cx, uintN argc, jsval* argv );
 	bool RemoveHandlerJS( JSContext* cx, uintN argc, jsval* argv );
 
 	// Return the JSObject* we'd like to be the 'this' object
 	// when executing the handler. The argument is the object
 	// to which the event is targeted.
+	// It is passed to CScriptObject::DispatchEvent.
 	virtual JSObject* GetScriptExecContext( IEventTarget* target ) = 0;
 
+	// Dispatch an event to its handler.
+	// returns: whether the event arrived (i.e. wasn't cancelled) [bool]
 	bool DispatchEvent( CScriptEvent* evt );
 };
 

source/scripting/EventTypes.h

@@ -1,5 +1,11 @@
+#ifndef EVENTTYPES_H__
+#define EVENTTYPES_H__
+
 // EventTypes.h
-// Script event declarations
+// Fairly game-specific event declarations for use with DOMEvent.
+// Creates unique (for the current target) names for each event.
+// DOMEvent currently uses a preallocated array of EVENT_LAST elements,
+// so these must be consecutive integers starting with 0.
 
 enum EEventType
 {
@@ -13,9 +19,11 @@ enum EEventType
 	EVENT_PREPARE_ORDER,
 	EVENT_ORDER_TRANSITION,
 	EVENT_LAST,
+
 	// Projectile events
 	EVENT_IMPACT = 0,
 	EVENT_MISS,
+
 	// General events
 	EVENT_GAME_START = 0,
 	EVENT_GAME_TICK,
@@ -23,8 +31,8 @@ enum EEventType
 	EVENT_WORLD_CLICK,
 };
 
-// Only used for entity events...
-static const wchar_t* EventNames[] =
+// Only used for entity events... (adds them as a property)
+static const wchar_t* EventNames[EVENT_LAST] =
 {
 	/* EVENT_INITIALIZE */ L"onInitialize",
 	/* EVENT_TICK */ L"onTick",
@@ -35,3 +43,5 @@ static const wchar_t* EventNames[] =
 	/* EVENT_PREPARE_ORDER */ L"onPrepareOrder", /* To check if a unit can execute a given order */
 	/* EVENT_ORDER_TRANSITION */ L"onOrderTransition" /* When we change orders (sometimes...) */
 };
+
+#endif	// #ifndef EVENTTYPES_H__

source/scripting/GameEvents.h

@@ -1,12 +1,15 @@
 // GameEvents.h
-
-// A class that exists to let scripts know when important things happen
-// in the game.
+// Defines a singleton class, g_JSGameEvents that fires certain events on
+// request (Fire*). This serves to notify scripts of important game events.
+// The CScriptEvent-derived events are declared here as well,
+// with their type set to one of EventTypes.h's EEventType.
 
 #ifndef GAME_EVENTS_INCLUDED
 #define GAME_EVENTS_INCLUDED
 
 #include "DOMEvent.h"
+#include "EventTypes.h"
+#include "ps/Singleton.h"
 
 class CGameEvents : public IEventTarget, public Singleton<CGameEvents>
 {

source/scripting/SynchedJSObject.h

@@ -122,6 +122,8 @@ struct CSynchedJSObjectBase
 	SynchedPropertyTable m_SynchedProperties;
 
 protected:
+	// Called every time a property changes.
+	// This is where the individual callbacks are dispatched from.
 	virtual void Update(CStrW name, ISynchedJSProperty *prop)=0;
 
 public:
@@ -135,6 +137,8 @@ template <typename Class>
 class CSynchedJSObject: public CJSObject<Class>, public CSynchedJSObjectBase
 {
 protected:
+	// Add a property to the object; if desired, a callback is called every time it changes.
+	// Replaces CJSObject's AddProperty.
 	template <typename T> void AddSynchedProperty(CStrW name, T *native, UpdateFn update=NULL)
 	{
 		ISynchedJSProperty *prop=new CSynchedJSProperty<T>(name, native, this, update);