# HG changeset patch
# User prock@33b003aa-7bff-0310-803a-e67f0ece8222
# Date 1273506861 0
# Node ID e241d755349651514ebaf12ed86f269739109628
# Parent  e29853880e8704ccf4c96a0180bd652e36110607
Fixing the epydoc markup.  Did some more commenting.

diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/common/baseobject.py
--- a/demos/shooter/scripts/common/baseobject.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/common/baseobject.py	Mon May 10 15:54:21 2010 +0000
@@ -36,16 +36,17 @@
 
 class SpaceObject(object):
 	"""
-	Space Object
-	
-	This is the base class for all game objects.
+	Space Object is the base class for all game objects.
 	"""
 	def __init__(self, scene, name, findInstance=True):
 		"""
-		@param scene A reference to the Scene
-		@param name The name of the space object
-		@param findInstance True if the instance you are looking for is already loaded
-		                    False if you want to load the instance yourself
+		@param scene: A reference to the Scene
+		@type scene: L{Scene}
+		@param name: The name of the space object
+		@type name: C{string}
+		@param findInstance: True if the instance you are looking for is already loaded
+		                     False if you want to load the instance yourself
+		@type findInstance: C{boolean}
 		
 		"""
 		self._scene = scene
@@ -114,10 +115,12 @@
 		
 	def applyThrust(self, vector):
 		"""
-		Applies a thrust vector to the object.  Note that objects do not have
-		mass or any inertia.
+		Applies a thrust vector to the object.  
 		
-		@param vector A fife.DoublePoint() specifying the direction and intensity of thrust.
+		@note: Objects do not have mass and therefore no inertia.
+		
+		@param vector A vector specifying the direction and intensity of thrust.
+		@type vector: L{fife.DoublePoint}
 		"""
 		self._velocity.x += (vector.x * (self._scene.timedelta/1000.0))/self._xscale
 		self._velocity.y += (vector.y * (self._scene.timedelta/1000.0))/self._yscale
@@ -132,7 +135,8 @@
 		"""
 		Applies a braking thrust in the opposite direction of the current velocity
 		
-		@param brakingForce a floating point value specifying how fast the object should decelerate
+		@param brakingForce: a floating point value specifying how fast the object should decelerate
+		@type brakingForce: C{float}
 		"""
 		if self._velocity.length() <= .01:
 			self._velocity.x = 0
diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/scene.py
--- a/demos/shooter/scripts/scene.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/scene.py	Mon May 10 15:54:21 2010 +0000
@@ -30,7 +30,7 @@
 
 class SceneNode(object):
 	"""
-	SceneNode
+	A node in the scene graph.
 	
 	This represents a node in the scene.  The node stores a list
 	of objects that exist in the node.  This is used by the Scene
@@ -55,17 +55,21 @@
 
 class Scene(object):
 	"""
-	Scene
+	Master game scene.  Keeps track of all game objects.
 	
 	This is the meat and potatoes of the game.  This class takes care of the scene graph,
 	updating objects, destroying objects, collision detection, etc etc.
 	"""
 	def __init__(self, world, engine, objectLayer, soundmanager):
 		"""
-		@param world A reference to the master instance of the World class
-		@param engine A reference to the FIFE engine
-		@param objectLayer The layer that all objects exist on
-		@param soundmanager A reference to the SoundManager
+		@param world: A reference to the master instance of the World class
+		@type world: L{World}
+		@param engine: A reference to the FIFE engine
+		@type engine: L{fife.Engine}
+		@param objectLayer: The layer that all objects exist on
+		@type objectLayer: L{fife.Layer}
+		@param soundmanager: A reference to the SoundManager
+		@type soundmanager: L{fife.extensions.soundmanager.SoundManager}
 		"""
 		self._engine = engine
 		self._world = world
@@ -252,16 +256,16 @@
 
 	def getObjectsInNode(self, nodeindex):
 		"""
-		@param nodeindex the index of the node you which to retrieve objects from.
-		@return The list of objects in the specified node index
+		@param nodeindex: the index of the node you which to retrieve objects from.
+		@return: The list of objects in the specified node index
 		"""
 		return self._nodes[nodeindex].instances
 
 	def getObjectsInRange(self, rangeL, rangeR):
 		"""
-		@param rangeL the left most node index
-		@param rangeR the right most node index
-		@return A combined list of objects in the specified node index range (inclusive)
+		@param rangeL: the left most node index
+		@param rangeR: the right most node index
+		@return: A combined list of objects in the specified node index range (inclusive)
 		"""
 		objects = list()
 		
@@ -274,10 +278,10 @@
 		"""
 		Adds an object to the scene in the correct scene node
 		
-		@param obj The object to add to the scene
+		@param obj: The object to add to the scene
 		"""
 		
-		#TODO: search to ensure the object isn't already part of the scene
+		#@todo: search to ensure the object isn't already part of the scene
 		loc = obj.instance.getLocation().getExactLayerCoordinates()
 		nodeindex = int(loc.x * self._xscale)
 
@@ -293,7 +297,7 @@
 		When an object moves in the scene you should call this function to update
 		scene graph.  You MUST do this or the graph will be incorrect.
 		
-		@param obj The object to move in the scene
+		@param obj: The object to move in the scene
 		"""
 		
 		loc = obj.instance.getLocation().getExactLayerCoordinates()
@@ -318,7 +322,7 @@
 		This function releases any memory allocated for the object by deleting
 		the FIFE instance.
 		
-		@param obj The object to delete
+		@param obj: The object to delete
 		"""
 		for node in self._nodes:
 			if obj in node.spaceobjects:
diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/ships/player.py
--- a/demos/shooter/scripts/ships/player.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/ships/player.py	Mon May 10 15:54:21 2010 +0000
@@ -89,9 +89,13 @@
 			self._scene.gameOver()
 		
 	def setInvulnerable(self, milliseconds):
-		#50 is defined in the players "flash" animation file
-		#2 is the number of frames in the animation
-		#TODO: read these values somehow from the animation
+		"""
+		50 is defined in the players "flash" animation file
+		2 is the number of frames in the animation		
+		
+		@todo: read these values somehow from the animation
+		
+		"""
 		number = int((milliseconds / 50) / 2)
 		
 		if number <= 0:
@@ -166,7 +170,7 @@
 		super(Player, self).update()
 		
 		#set up the players camera bounds
-		#TODO: grab screen resolution from somewhere
+		#@todo: grab screen resolution from somewhere
 		topleft = self._scene.camera.toMapCoordinates(fife.ScreenPoint(0,0))
 		bottomright = self._scene.camera.toMapCoordinates(fife.ScreenPoint(1024,768))
 
diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/ships/shipbase.py
--- a/demos/shooter/scripts/ships/shipbase.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/ships/shipbase.py	Mon May 10 15:54:21 2010 +0000
@@ -69,10 +69,14 @@
 	"""
 	def __init__(self, scene, name, findInstance=True):
 		"""
-		@param scene A reference to the Scene
-		@param name The name of the ship
-		@param findInstance True if the instance you are looking for is already loaded
-		                    False if you want to load the instance yourself
+		@param scene: A reference to the Scene
+		@type scene: L{Scene}
+		@param name: The name of the ship
+		@type name: C{string}
+		@param findInstance: True if the instance you are looking for is already loaded
+		                     False if you want to load the instance yourself
+		                     
+		@type findInstance: C{boolean}
 		
 		"""
 		
@@ -99,7 +103,7 @@
 		"""
 		Playes the flash animation (or action) the specified number of times
 		
-		@param number an integer specifying the number of times to play the flash animation
+		@param number: An integer specifying the number of times to play the flash animation
 		"""
 		if self._running:
 			self._instance.act('flash', self._instance.getFacingLocation())
@@ -110,7 +114,7 @@
 		"""
 		Fires the current weapon in the specified direction
 		
-		@param direction A fife.DoublePoint() specifying the direction to fire
+		@param direction: A L{fife.DoublePoint()} specifying the direction to fire
 		"""
 		if self._weapon and self._hitpoints > 0:
 			return self._weapon.fire(direction)
@@ -121,7 +125,7 @@
 		"""
 		Removes the specified number of hit points.  Destroys the ship if necessary.
 		
-		@param hp The number of hit points to remove from the ship.
+		@param hp: The number of hit points to remove from the ship.
 		"""
 		self._hitpoints -= hp
 		if self._hitpoints <= 0:
diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/weapons.py
--- a/demos/shooter/scripts/weapons.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/weapons.py	Mon May 10 15:54:21 2010 +0000
@@ -27,13 +27,25 @@
 
 class Projectile(SpaceObject):
 	"""
-	Projectile
+	Represents a projectile (or bullet or fireball) in the scene.
 
 	This is the entity that weapons fire.  Projectiles have an owner
 	and a time to live.  They are also what cause damage to ships
 	and other entities.
 	"""
 	def __init__(self, scene, owner, projectileName, timeToLive):
+		"""
+		@param scene: The scene
+		@type scene: L{Scene}
+		@param owner: The ship that fired the projectile
+		@type owner: L{Ship}
+		@param projectileName: The name of the FIFE object to load
+		@type projectilName: C{string}
+		@param timeToLive: The length of time in milliseconds the projectile will 
+		remain active before destroying itself.
+		@type timeToLive: C{int}
+		
+		"""
 		super(Projectile, self).__init__(scene, projectileName, False)
 
 		self._obj = self._model.getObject(self._name, "http://www.fifengine.de/xml/tutorial")
@@ -52,11 +64,28 @@
 		self._damage = 1
 	
 	def create(self, location):
+		"""
+		Spawns the projectile.
+		
+		@param location: The location to create the projectile
+		@type location: L{fife.Location}
+		
+		@note: This is called by L{Projectile.run}
+		"""
 		self._instance = self._layer.createInstance(self._obj, location.getExactLayerCoordinates(), "bullet")
 		fife.InstanceVisual.create(self._instance)
 		self._instance.thisown = 0
 
 	def run(self, velocity, location):
+		"""
+		Start the projectile on it's path.
+		
+		@param velocity: The starting velocity of the projectile
+		@type velocity: L{fife.DoublePoint}
+		@param location: The location to create the projectile
+		@type location: L{fife.Location}
+		
+		"""
 		if not self._running:
 			self._velocity = velocity
 			self._velocity.x /= self._xscale
@@ -110,6 +139,12 @@
 		self._soundclip = None
 		
 	def fire(self, direction):
+		"""
+		Fires the weapon in the specified direction.
+		
+		@param direction: A normalized vector specifying the direction to fire the projectile
+		@type direction: L{fife.DoublePoint}
+		"""
 		pass
 		
 	def _getProjectileVelocity(self):
diff -r e29853880e87 -r e241d7553496 demos/shooter/scripts/world.py
--- a/demos/shooter/scripts/world.py	Fri May 07 21:46:25 2010 +0000
+++ b/demos/shooter/scripts/world.py	Mon May 10 15:54:21 2010 +0000
@@ -151,6 +151,10 @@
 
 
 	def renderBoundingBox(self, obj):
+		"""
+		Just a hack to render an objects bounding box.
+		"""
+		
 		bbox = copy.copy(obj.boundingbox)
 		
 		#apply the object layer scale
diff -r e29853880e87 -r e241d7553496 engine/python/fife/extensions/fife_math.py
--- a/engine/python/fife/extensions/fife_math.py	Fri May 07 21:46:25 2010 +0000
+++ b/engine/python/fife/extensions/fife_math.py	Mon May 10 15:54:21 2010 +0000
@@ -36,9 +36,10 @@
 	"""
 	Helper function to normalize a 2D vector
 	
-	@param vector a L{fife.DoublePoint} to be normalized
+	@param vector: a L{fife.DoublePoint} to be normalized
+	@type vector: L{fife.DoublePoint}
 	
-	@return A normalized L{fife.DoublePoint}
+	@return: A normalized L{fife.DoublePoint}
 	"""
 	norm = fife.DoublePoint(0,0) 
 		
@@ -54,7 +55,7 @@
 	
 class Rect(object):
 	"""
-	Rect
+	A simple rectangle class that allows floating point values.
 	
 	A class used to specify the bounding box of objects.  For use
 	with collision detection.  This was written in python because
@@ -63,10 +64,14 @@
 	"""
 	def __init__(self, x = 0, y = 0, w = 0, h = 0):
 		"""
-		@param x The x coordinate
-		@param y The y coordinate
-		@param w The width
-		@param h The height
+		@param x: The x coordinate
+		@type x: C{int} or C{float}
+		@param y: The y coordinate
+		@type y: C{int} or C{float}
+		@param w: The width
+		@type w: C{int} or C{float}
+		@param h: The height
+		@type h: C{int} or C{float}
 		"""
 		self._x = x
 		self._y = y
@@ -77,8 +82,11 @@
 		"""
 		Tests for intersection of rect.
 		
-		@param rect the Rect to perform the test against
-		@return True if the rectancles intersect, False if not.
+		@param rect: the L{Rect} to perform the test against.
+		@type rect: L{Rect}
+		
+		@return: True if the rectancles intersect, False if not.
+		@rtype: C{boolean}
 		"""
 		_x = self._x - rect.x;
 		_y = self._y - rect.y;
@@ -137,11 +145,15 @@
 	"""
 	Rotates a point around the specified origin.
 	
-	@param origin A L{fife.DoublePoint} specifying the origin.
-	@param point A L{fife.DoublePoint} to be rotated.
-	@param angle The angle in which to rotate the point.
+	@param origin: A L{fife.DoublePoint} specifying the origin.
+	@type origin: L{fife.DoublePoint}
+	@param point: A L{fife.DoublePoint} to be rotated.
+	@type point: L{fife.DoublePoint}
+	@param angle: The angle in which to rotate the point.
+	@type angle: C{int} or C{float}
 	
-	@return A L{fife.DoublePoint} representing the rotated point.
+	@return: A L{fife.DoublePoint} representing the rotated point.
+	@rtype: L{fife.DoublePoint}
 	"""
 	newp = fife.DoublePoint(0,0)
 	
diff -r e29853880e87 -r e241d7553496 engine/python/fife/extensions/fife_timer.py
--- a/engine/python/fife/extensions/fife_timer.py	Fri May 07 21:46:25 2010 +0000
+++ b/engine/python/fife/extensions/fife_timer.py	Mon May 10 15:54:21 2010 +0000
@@ -62,9 +62,9 @@
 	"""
 	def __init__(self,delay=0,callback=None,repeat=0):
 		"""
-		@param delay The delay in milliseconds to execute the callback
-		@param callback The function to execute
-		@param repeat The number of times to execute the callback.  1=once, 0=forever 
+		@param delay: The delay in milliseconds to execute the callback
+		@param callback: The function to execute
+		@param repeat: The number of times to execute the callback.  1=once, 0=forever 
 		"""
 		super(Timer,self).__init__(delay)
 		self._is_registered = False
@@ -116,10 +116,11 @@
 	"""
 	Delay a function call by a number of milliseconds.
 
-	@param delay Delay in milliseconds.
-	@param callback The function to call.
+	@param delay: Delay in milliseconds.
+	@param callback: The function to call.
 
 	@return The timer.
+	@rtype: L{Timer}
 	"""
 	timer = Timer(delay, callback, 1)
 	timer.start()
@@ -130,10 +131,11 @@
 	"""
 	Repeat a function call.
 
-	@param period Period between calls in milliseconds.
-	@param callback The function to call.
+	@param period: Period between calls in milliseconds.
+	@param callback: The function to call.
 
-	@return The timer.
+	@return: The timer.
+	@rtype: L{Timer}
 
 	The call is repeated until the timer is stopped.
 	"""
diff -r e29853880e87 -r e241d7553496 engine/python/fife/extensions/soundmanager.py
--- a/engine/python/fife/extensions/soundmanager.py	Fri May 07 21:46:25 2010 +0000
+++ b/engine/python/fife/extensions/soundmanager.py	Mon May 10 15:54:21 2010 +0000
@@ -37,25 +37,36 @@
 play at once or allow the positioning of sounds.  It does however provide 
 a good starting point for a more advanced version of a sound manager.
 
+Usage::
+  soundmanager = SoundManager(my_fife_engine)
+  
+  emitter = soundmanager.createSoundEmitter("path/filename.ogg")
+  emitter.gain = 128
+  emitter.play()
+
 """
 
 class SoundEmitter(object):
 	"""
-	SoundEmitter
+	Wraps the L{fife.SoundEmitter} class.
 
 	This class wraps an instance of a L{fife.SoundEmitter} class along 
 	with some information about a sound clip (like gain and if its
 	looping).  All instances of SoundEmitter should be created by SoundManager.
 	
-	@todo At some point this class will store positional information
+	@todo: At some point this class will store positional information
 	and also be responsible for updating the L{fife.SoundEmitter} position.
 	"""
 	def __init__(self, soundmanager, clipid, soundname, emitter):
 		"""
-		@param soundmanager A reference to the SoundManager
-		@param clipid The FIFE sound clip ID from the sound clip pool
-		@param soundname The filename of the sound
-		@param emitter A reference to the L{fife.SoundEmitter} associated with this clip
+		@param soundmanager: A reference to the SoundManager
+		@type soundmanager: L{SoundManager}
+		@param clipid: The FIFE sound clip ID from the sound clip pool
+		@type clipid: C{int}
+		@param soundname: The filename of the sound
+		@type soundname: C{string}
+		@param emitter: A reference to the L{fife.SoundEmitter} associated with this clip
+		@type emitter: L{fife.SoundEmitter} 
 		
 		"""
 		self._soundmanager = soundmanager
@@ -93,6 +104,13 @@
 		return self._gain
 		
 	def _setGain(self, gain):
+		"""
+		Sets the volume of the L{SoundEmitter}.
+		
+		@param gain: Value should be from 0-255.  0 being mute and 255 being the normal
+		volume of the clip.
+		@type gain: C{int}
+		"""
 		self._gain = float(gain)
 		
 	def _getLooping(self):
@@ -141,7 +159,7 @@
 
 class SoundManager(object):
 	"""
-	SoundManger
+	A simple sound manager class.
 
 	This class manages and plays all the sounds of the game.  
 	It creates SoundEmitters and ensures that there is only one 
@@ -149,7 +167,8 @@
 	"""
 	def __init__(self, engine):
 		"""
-		@param engine A reference to the FIFE engine
+		@param engine: A reference to the FIFE engine
+		@type engine: L{fife.Engine}
 		"""
 		
 		self._engine = engine
@@ -164,12 +183,15 @@
 		"""
 		Returns a valid SoundEmitter instance.
 		
-		@param filename The relative path and filename of the sound file
-		@parm forceUnique This forces a new L{fife.SoundEmitter} to be created.  
+		@param filename: The relative path and filename of the sound file
+		@type clip: C{string}
+		@param forceUnique: This forces a new L{fife.SoundEmitter} to be created.
 		This is useful if you want more than one instance of the same sound 
 		to be played at the same time.
+		@type forceUnique: C{boolean}
 		
-		@return Returns a new SoundEmitter instance.
+		@return: Returns a new L{SoundEmitter} instance.
+		@rtype: L{SoundEmitter}
 		"""
 		if not self._loadedclips.has_key(filename):
 			clipid = self._engine.getSoundClipPool().addResourceFromFile(filename)
@@ -206,11 +228,12 @@
 		If the SoundEmitter is invalid (no fifeemitter) then it attempts 
 		to load it before playing it.
 		
-		@note This will stop any clips that use the same L{fife.SoundEmitter}.
+		@note: This will stop any clips that use the same L{fife.SoundEmitter}.
 		You cannot play the same sound more than once at a time unless you create
 		the SoundEmitter with the forceUnique paramater set to True.
 		
-		@param clip The SoundEmitter to be played
+		@param clip: The L{SoundEmitter} to be played
+		@type clip: L{SoundEmitter}
 		"""
 		if clip.fifeemitter:
 			if clip.callback:
@@ -232,7 +255,7 @@
 					repeat = 1
 					
 				clip.timer = fife_timer.Timer(clip.duration, clip.callback, repeat)
-				clip.timer.start()
+				#clip.timer.start()
 			else:
 				if clip.looping:
 					def real_callback(e, g):
@@ -242,11 +265,13 @@
 
 					clip.callback = cbwa(real_callback, clip.fifeemitter, clip.gain)
 					clip.timer = fife_timer.Timer(clip.duration, clip.callback, 0)
-					clip.timer.start()
+					#clip.timer.start()
 					
 				
 			clip.fifeemitter.setGain(float(clip.gain)/255.0)
-			clip.fifeemitter.play()	
+			clip.fifeemitter.play()
+			if clip.timer:
+				clip.timer.start()
 		else:
 			clip = self.createSoundEmitter(clip.name)
 			self.playClip(clip)
@@ -256,7 +281,8 @@
 		Stops playing the sound clip.   Note that this will stop all clips that 
 		use the same FIFE emitter.
 		
-		@parm clip The SoundEmitter to stop.
+		@param clip: The SoundEmitter to stop.
+		@type clip: L{SoundEmitter}
 		"""
 		if clip.fifeemitter:
 			clip.fifeemitter.stop()
@@ -272,8 +298,9 @@
 			
 	def destroy(self):
 		"""
-		Releases all instances of L{fife.SoundEmitter}.  This does not free 
-		the resources from the FIFE sound clip pool.
+		Releases all instances of L{fife.SoundEmitter}.  
+		
+		@note: This does not free the resources from the FIFE sound clip pool.
 		"""
 		self.stopAllSounds()