Documenation clarification in IEventReceiver (thx teto) and ISceneCollisionManager (thx aanderse).

git-svn-id: svn://svn.code.sf.net/p/irrlicht/code/trunk@3008 dfc29bdd-3216-0410-991c-e03cc46cb475

include/IEventReceiver.h

@@ -121,7 +121,7 @@ namespace irr
 
 		//! Middle mouse button triple click.
 		//! This event is generated after the third EMIE_MMOUSE_PRESSED_DOWN event.
-		EMIE_MMOUSE_TRIPLE_CLICK,			
+		EMIE_MMOUSE_TRIPLE_CLICK,
 
 		//! No real event. Just for convenience to get number of events
 		EMIE_COUNT
@@ -431,7 +431,11 @@ public:
 	virtual ~IEventReceiver() {}
 
 	//! Called if an event happened.
-	/** \return True if the event was processed. */
+	/** Please take care that you should only return 'true' when you want to _prevent_ Irrlicht
+	* from processing the event any further. So 'true' does mean that an event is completely done.
+	* Therefore your return value for all unprocessed events should be 'false'.
+	\return True if the event was processed.
+	*/
 	virtual bool OnEvent(const SEvent& event) = 0;
 };
 

include/ISceneCollisionManager.h

@@ -25,14 +25,14 @@ namespace scene
 	{
 	public:
 
-		//! Finds the collision point of a line and lots of triangles, if there is one.
+		//! Finds the nearest collision point of a line and lots of triangles, if there is one.
 		/** \param ray: Line with which collisions are tested.
 		\param selector: TriangleSelector containing the triangles. It
 		can be created for example using
 		ISceneManager::createTriangleSelector() or
 		ISceneManager::createTriangleOctTreeSelector().
 		\param outCollisionPoint: If a collision is detected, this will
-		contain the position of the nearest collision.
+		contain the position of the nearest collision to the line-start.
 		\param outTriangle: If a collision is detected, this will
 		contain the triangle with which the ray collided.
 		\param outNode: If a collision is detected, this will contain
@@ -143,8 +143,8 @@ namespace scene
 		against this ray. The collision tests are done using a bounding
 		box for each scene node.
 		\param camera: Camera from which the ray is casted.
-		\param idBitMask: Only scene nodes with an id which matches at least one of the 
-		bits contained in this mask will be tested. However, if this parameter is 0, then 
+		\param idBitMask: Only scene nodes with an id which matches at least one of the
+		bits contained in this mask will be tested. However, if this parameter is 0, then
 		all nodes are checked.
 		feature is disabled.
 		Please note that the default node id of -1 will match with
@@ -158,33 +158,33 @@ namespace scene
 			s32 idBitMask=0, bool bNoDebugObjects = false) = 0;
 
 		//! Perform a ray/box and ray/triangle collision check on a heirarchy of scene nodes.
-		/** This checks all scene nodes under the specified one, first by ray/bounding 
+		/** This checks all scene nodes under the specified one, first by ray/bounding
 		box, and then by accurate ray/triangle collision, finding the nearest collision,
-		and the scene node containg it.  It returns the node hit, and (via output 
+		and the scene node containg it.  It returns the node hit, and (via output
 		parameters) the position of the collision, and the triangle that was hit.
 
 		All scene nodes in the hierarchy tree under the specified node are checked. Only
-		notes that are visible, with an ID that matches at least one bit in the supplied 
+		notes that are visible, with an ID that matches at least one bit in the supplied
 		bitmask, and which have a triangle selector are considered as candidates for being hit.
-		You do not have to build a meta triangle selector; the individual triangle selectors 
+		You do not have to build a meta triangle selector; the individual triangle selectors
 		of each candidate scene node are used automatically.
-		
+
 		\param ray: Line with which collisions are tested.
 		\param outCollisionPoint: If a collision is detected, this will contain the
 		position of the nearest collision.
 		\param outTriangle: If a collision is detected, this will contain the triangle
 		with which the ray collided.
-		\param idBitMask: Only scene nodes with an id which matches at least one of the 
-		bits contained in this mask will be tested. However, if this parameter is 0, then 
+		\param idBitMask: Only scene nodes with an id which matches at least one of the
+		bits contained in this mask will be tested. However, if this parameter is 0, then
 		all nodes are checked.
 		\param collisionRootNode: the scene node at which to begin checking. Only this
-		node and its children will be checked. If you want to check the entire scene, 
+		node and its children will be checked. If you want to check the entire scene,
 		pass 0, and the root scene node will be used (this is the default).
 		\param noDebugObjects: when true, debug objects are not considered viable targets.
 		Debug objects are scene nodes with IsDebugObject() = true.
 		\return Returns the scene node containing the hit triangle nearest to ray.start.
 		If no collision is detected, then 0 is returned. */
-		virtual ISceneNode* getSceneNodeAndCollisionPointFromRay(								
+		virtual ISceneNode* getSceneNodeAndCollisionPointFromRay(
 								core::line3df ray,
 								core::vector3df & outCollisionPoint,
 								core::triangle3df & outTriangle,