Add some documentation to the raycast functions.

Since these are now functions and not in a class there's no obvious
encapsulation for the two related functions. Previously they were
only available in the PolyVox namespace documentation where they were
hidden among lots of other things. Adding the \file command to
Raycast.h allows up to add comments to that page (_raycast_8h.html)
and have that as the central location for the raycast docs.

There still needs to be a comment about the form that the callback
must take (return type and arguments) including the fact that both
functors and lambdas work.

library/PolyVoxCore/include/PolyVoxCore/Raycast.h

@@ -40,6 +40,8 @@ namespace PolyVox
 
 	/// OUT OF DATE SINCE UNCLASSING
 	////////////////////////////////////////////////////////////////////////////////
+	/// \file Raycast.h
+	///
 	/// The principle behind raycasting is to fire a 'ray' through the volume and determine
 	/// what (if anything) that ray hits. This simple test can be used for the purpose of
 	/// picking, visibility checks, lighting calculations, or numerous other applications.

library/PolyVoxCore/include/PolyVoxCore/Raycast.inl

@@ -35,8 +35,8 @@ namespace PolyVox
 	//	Thanks to Jetro Lauha of Fathammer in Helsinki, Finland for reporting this error.
 	//
 	//	Jetro also points out that the computations of i, j, iend, and jend are incorrectly rounded if the line
-	//  coordinates are allowed to go negative. While that was not really the intent of the code — that is, I
-	//  assumed grids to be numbered from (0, 0) to (m, n) — I'm at fault for not making my assumption clear.
+	//  coordinates are allowed to go negative. While that was not really the intent of the code -- that is, I
+	//  assumed grids to be numbered from (0, 0) to (m, n) -- I'm at fault for not making my assumption clear.
 	//  Where it is important to handle negative line coordinates the computation of these variables should be
 	//  changed to something like this:
 	//
@@ -52,6 +52,22 @@ namespace PolyVox
 	//  It should simply read "if (ty <= tz)".
 	//
 	//	This error was reported by Joey Hammer (PixelActive).
+	
+	/**
+	 * Cast a ray through a volume by specifying the start and end positions
+	 * 
+	 * The ray will move from \a v3dStart to \a v3dEnd, calling \a callback for each
+	 * voxel it passes through until \a callback returns \a false. In this case it
+	 * returns a RaycastResults::Interupted. If it passes from start to end
+	 * without \a callback returning \a false, it returns RaycastResults::Completed.
+	 * 
+	 * \param volData The volume to pass the ray though
+	 * \param v3dStart The start position in the volume
+	 * \param v3dEnd The end position in the volume
+	 * \param callback The callback to call for each voxel
+	 * 
+	 * \return A RaycastResults designating whether the ray hit anything or not
+	 */
 	template<typename VolumeType, typename Callback>
 	RaycastResult raycastWithEndpoints(VolumeType* volData, const Vector3DFloat& v3dStart, const Vector3DFloat& v3dEnd, Callback& callback)
 	{
@@ -129,6 +145,30 @@ namespace PolyVox
 		return RaycastResults::Completed;
 	}
 
+	/**
+	 * Cast a ray through a volume by specifying the start and a direction
+	 * 
+	 * The ray will move from \a v3dStart along \a v3dDirectionAndLength, calling 
+	 * \a callback for each voxel it passes through until \a callback returns 
+	 * \a false. In this case it returns a RaycastResults::Interupted. If it 
+	 * passes from start to end without \a callback returning \a false, it 
+	 * returns RaycastResults::Completed.
+	 * 
+	 * \note These has been confusion in the past with people not realising
+	 * that the length of the direction vector is important. Most graphics API can provide
+	 * a camera position and view direction for picking purposes, but the view direction is
+	 * usually normalised (i.e. of length one). If you use this view direction directly you
+	 * will only iterate over a single voxel and won't find what you are looking for. Instead
+	 * you must scale the direction vector so that it's length represents the maximum distance
+	 * over which you want the ray to be cast.
+	 * 
+	 * \param volData The volume to pass the ray though
+	 * \param v3dStart The start position in the volume
+	 * \param v3dDirectionAndLength The direction and length of the ray
+	 * \param callback The callback to call for each voxel
+	 * 
+	 * \return A RaycastResults designating whether the ray hit anything or not
+	 */
 	template<typename VolumeType, typename Callback>
 	RaycastResult raycastWithDirection(VolumeType* volData, const Vector3DFloat& v3dStart, const Vector3DFloat& v3dDirectionAndLength, Callback& callback)
 	{