Docs: improve stencil shadow algorithm documentation

Author: paroj

Docs/src/bibliography.bib

@@ -139,3 +139,10 @@ @article{moller1997fast
   year={1997},
   publisher={Taylor \& Francis}
 }
+
+@article{mcguire2003fast,
+  title={Fast, practical and robust shadows},
+  author={McGuire, Morgan and Hughes, John F and Egan, Kevin and Kilgard, Mark J and Everitt, Cass},
+  journal={Brown University Computer Science Tech Report CS-03-19, November},
+  year={2003}
+}

OgreMain/include/OgreMesh.h

@@ -730,24 +730,7 @@ namespace Ogre {
         /** Destroys and frees the edge lists this mesh has built. */
         void freeEdgeList(void);
 
-        /** This method prepares the mesh for generating a renderable shadow volume. 
-        @remarks
-            Preparing a mesh to generate a shadow volume involves firstly ensuring that the 
-            vertex buffer containing the positions for the mesh is a standalone vertex buffer,
-            with no other components in it. This method will therefore break apart any existing
-            vertex buffers this mesh holds if position is sharing a vertex buffer. 
-            Secondly, it will double the size of this vertex buffer so that there are 2 copies of 
-            the position data for the mesh. The first half is used for the original, and the second 
-            half is used for the 'extruded' version of the mesh. The vertex count of the main 
-            VertexData used to render the mesh will remain the same though, so as not to add any 
-            overhead to regular rendering of the object.
-            Both copies of the position are required in one buffer because shadow volumes stretch 
-            from the original mesh to the extruded version. 
-        @par
-            Because shadow volumes are rendered in turn, no additional
-            index buffer space is allocated by this method, a shared index buffer allocated by the
-            shadow rendering algorithm is used for addressing this extended vertex buffer.
-        */
+        /// @copydoc VertexData::prepareForShadowVolume
         void prepareForShadowVolume(void);
 
         /** Return the edge list for this mesh, building it if required. 

OgreMain/include/OgreVertexIndexData.h

@@ -119,8 +119,8 @@ namespace Ogre {
         */
         VertexData* clone(bool copyData = true, HardwareBufferManagerBase* mgr = 0) const OGRE_NODISCARD;
 
-        /** Modifies the vertex data to be suitable for use for rendering shadow geometry.
-        @remarks
+        /** Modifies the vertex data to be suitable for use for rendering shadow geometry as in @cite mcguire2003fast
+
             Preparing vertex data to generate a shadow volume involves firstly ensuring that the 
             vertex buffer containing the positions is a standalone vertex buffer,
             with no other components in it. This method will therefore break apart any existing
@@ -131,12 +131,16 @@ namespace Ogre {
             the same though, so as not to add any overhead to regular rendering of the object.
             Both copies of the position are required in one buffer because shadow volumes stretch 
             from the original mesh to the extruded version. 
-        @par
+
             It's important to appreciate that this method can fundamentally change the structure of your
             vertex buffers, although in reality they will be new buffers. As it happens, if other 
             objects are using the original buffers then they will be unaffected because the reference
             counting will keep them intact. However, if you have made any assumptions about the 
             structure of the vertex data in the buffers of this object, you may have to rethink them.
+
+            Because shadow volumes are rendered in turn, no additional
+            index buffer space is allocated by this method, a shared index buffer allocated by the
+            shadow rendering algorithm is used for addressing this extended vertex buffer.
         */
         void prepareForShadowVolume(void);