Fix miscellaneous formatting problems, typos etc. in some of the docs

OgreMain/include/Animation/OgreBone.h

@@ -189,7 +189,7 @@ namespace Ogre
         */
         void _setNodeParent( Node *nodeParent );
 
-        /** Sets a given orientation in local space (ie. relative to its parent)
+        /** Sets a given orientation in local space (i.e., relative to its parent)
         @remarks
             Don't call this function too often, as we need to convert to SoA
         */
@@ -225,7 +225,7 @@ namespace Ogre
         */
         inline Vector3 getScale() const;
 
-        /** Tells the Bone whether it should inherit orientation from it's parent node.
+        /** Tells the Bone whether it should inherit orientation from its parent node.
         @remarks
             See Node::setInheritOrientation remarks.
             Note that Nodes and bones inherit scale and orientation differently, because
@@ -247,7 +247,7 @@ namespace Ogre
         */
         bool getInheritOrientation() const;
 
-        /** Tells the node whether it should inherit scaling factors from it's parent node.
+        /** Tells the node whether it should inherit scaling factors from its parent node.
         @remarks
             See setInheritOrientation().
         @param inherit If true, this node's scale will be affected by its parent's scale. If false,
@@ -270,7 +270,7 @@ namespace Ogre
         */
         Matrix4 _getDerivedTransform() const;
 
-        /** Gets the transformation matrix for this bone in local space (i.e. as if the
+        /** Gets the transformation matrix for this bone in local space (i.e., as if the
             skeleton wasn't attached to a SceneNode).
         @remarks
             This method returns the full transformation matrix

OgreMain/include/Compositor/OgreCompositorShadowNode.h

@@ -66,21 +66,26 @@ namespace Ogre
         This is not needed anymore.
 
         To summarize: a normal rendering flow with shadow map looks like this:
-            shadowNode->setupShadowCamera( normal->getVisibleBoundsInfo() );
-            shadowNode->_cullPhase01();
-            shadowNode->_renderPhase02();
-            normal->_cullPhase01();
-            normal->_renderPhase02();
+
+        @code{.cpp}
+        shadowNode->setupShadowCamera( normal->getVisibleBoundsInfo() );
+        shadowNode->_cullPhase01();
+        shadowNode->_renderPhase02();
+        normal->_cullPhase01();
+        normal->_renderPhase02();
+        @endcode
     @par
     @par
         On forward lighting passes, shadow mapping is handled in the following way:
-            1) Build a list of all lights visible by all cameras (SceneManager does this)
-            2) Traverse the list to get the closest lights to the current camera.
-               These lights will cast shadows.
-            3) Build a list of the closest lights for each object (SceneManager does this)
-            4) Traverse this list and find those that are actually casting a shadow
-            5) Send to the GPU & engine the list in step 4, but shadow casting lights are
+
+        1. Build a list of all lights visible by all cameras (SceneManager does this)
+        2. Traverse the list to get the closest lights to the current camera.
+          These lights will cast shadows.
+        3. Build a list of the closest lights for each object (SceneManager does this)
+        4. Traverse this list and find those that are actually casting a shadow
+        5. Send to the GPU & engine the list in step 4, but shadow casting lights are
                put first, then sorted by proximity.
+
         See the comments inside the function setShadowMapsToPass for more information.
     @author
         Matias N. Goldberg

OgreMain/include/Compositor/OgreCompositorShadowNodeDef.h

@@ -133,7 +133,7 @@ namespace Ogre
         size_t getSharesSetupWith() const { return sharesSetupWith; }
     };
 
-    /** Shadow Nodes are special nodes (not to be confused with @see CompositorNode)
+    /** Shadow Nodes are special nodes (not to be confused with CompositorNode)
         that are only used for rendering shadow maps.
         Normal Compositor Nodes can share or own a ShadowNode. The ShadowNode will
         render the scene enough times to fill all shadow maps so the main scene pass

OgreMain/include/Compositor/OgreCompositorWorkspaceDef.h

@@ -181,24 +181,26 @@ namespace Ogre
 
         /** Clears all the connection between channels of the nodes @see connect
         @remarks
-            1. We don't clear the output connection (@see connectOutput, @see clearOutputConnections)
-            2. The node aliases (both implicit and explicit) will still exist. @see clearAll.
+            1. We don't clear the output connection (see CompositorNode::connectExternalRT, see
+        clearOutputConnections())
+            2. The node aliases (both implicit and explicit) will still exist. see clearAll.
             3. A node with incomplete inputs should be disabled before the workspace is instantiated
-               (@see CompositorNodeDef::setStartEnabled). If the workspace has already been instantiated,
-               the node instance should be disabled, @see CompositorNode::setEnabled)
+               (see CompositorNodeDef::setStartEnabled). If the workspace has already been instantiated,
+               the node instance should be disabled, see CompositorNode::setEnabled)
             4. It is safe to call this function while there are still workspaces, but you must call
                CompositorWorkspace::reconnectAllNodes after you're done setting the new node connections
         */
         void clearAllInterNodeConnections();
 
-        /** Clears the connection from the "final output RenderTarget" (i.e. usually the RenderWindow)
-            that goes to the input channel of one of our nodes. @see connectOutput.
+        /** Clears the connection from the "final output RenderTarget" (i.e., usually the RenderWindow)
+            that goes to the input channel of one of our nodes. See CompositorNode::connectExternalRT.
         @remarks
-            1. We don't clear other type of connections (@see connect, @see clearAllInterNodeConnections)
-            2. The node aliases (both implicit and explicit) will still exist. @see clearAll.
+            1. We don't clear other type of connections (see connect(), see
+        clearAllInterNodeConnections())
+            2. The node aliases (both implicit and explicit) will still exist. see clearAll.
             3. A node with incomplete inputs should be disabled before the workspace is instantiated
-               (@see CompositorNodeDef::setStartEnabled). If the workspace has already been instantiated,
-               the node instance should be disabled, @see CompositorNode::setEnabled)
+               (see CompositorNodeDef::setStartEnabled). If the workspace has already been instantiated,
+               the node instance should be disabled, see CompositorNode::setEnabled)
             4. It is safe to call this function while there are still workspaces, but you must call
                CompositorWorkspace::reconnectAllNodes after you're done setting the new node connections
         */
@@ -214,7 +216,7 @@ namespace Ogre
 
         /** An alias is explicitly used when the user wants to use multiple, independent
             instances of the same node. Each alias equals one instance.
-            An implicit alias is when the name of the alias and it's node name match.
+            An implicit alias is when the name of the alias and its node name match.
         @remarks
             When the name of the node and its alias are the same, it is said to be called an
             "implicit" alias.

OgreMain/include/Compositor/OgreTextureDefinition.h

@@ -394,7 +394,7 @@ namespace Ogre
         static void destroyTextures( CompositorChannelVec &inOutTexContainer, RenderSystem *renderSys );
 
         /** Destroys & recreates only the textures that depend on the main RT
-            (e.g. the Render Window) resolution.
+            (e.g., the Render Window) resolution.
         @remarks
             This is divided in two steps: recreateResizableTextures01 & recreateResizableTextures02
             since in some cases in RenderPassDescriptor, setting up MRT and depth textures
@@ -502,14 +502,14 @@ namespace Ogre
         /// We need the definition because, unlike textures, the container passed in may
         /// contain textures that were not created by us (i.e. global & input textures)
         /// that we shouldn't delete.
-        /// It is illegal for two buffers to have the same name, so it's invalid that a
+        /// It is illegal for two buffers to have the same name, so it's invalid that
         /// e.g. an input and a local texture would share the same name.
         static void destroyBuffers( const BufferDefinitionVec &bufferDefs,
                                     CompositorNamedBufferVec  &inOutBufContainer,
                                     RenderSystem              *renderSys );
 
         /** Destroys & recreates only the buffers that depend on the main RT
-            (i.e. the RenderWindow) resolution
+            (i.e., the RenderWindow) resolution
         @param textureDefs
             Array of texture definitions, so we know which ones depend on main RT's resolution
         @param inOutTexContainer

OgreMain/include/Compositor/Pass/OgreCompositorPassDef.h

@@ -83,7 +83,7 @@ namespace Ogre
             + PASS_COMPUTE (see CompositorPassComputeDef)
             + PASS_SHADOWS (see CompositorPassShadowsDef)
             + PASS_MIPMAP (see CompositorPassMipmapDef)
-            
+
         This class doesn't do much on its own. See the derived types for more information
         A definition is shared by all pass instantiations (i.e. Five CompositorPassScene can
         share the same CompositorPassSceneDef) and are assumed to remain const throughout
@@ -160,8 +160,8 @@ namespace Ogre
         /** Will issue a warning (by raising an exception) if Ogre is forced to flush
             the RenderTarget, which is very bad for performance on mobile, and can
             cause serious performance problems in Desktop if using MSAA, and also
-            cause correctness problems (i.e. bad rendering) if store action is
-            StoreAction::Resolve.
+            cause correctness problems (i.e., bad rendering) if store action is
+            StoreAction::MultisampleResolve.
         @remarks
             Flushes are caused by splitting rendering to the same RenderTarget
             in multiple passes while rendering to a different RenderTarget in the middle.

OgreMain/include/OgreHlmsManager.h

@@ -191,13 +191,18 @@ namespace Ogre
             on them, as we need to ensure caches of HlmsPso remain valid.
 
         @param baseParams
+        @parblock
             A macroblock reference to base the parameters. This reference may live on the stack,
-            on the heap, etc; it's RS-specific data does not have to be filled.
+            on the heap, etc; its RS-specific data does not have to be filled.
             e.g. this is fine:
+
+            @code{.cpp}
                 HlmsMacroblock myRef;
                 myRef.mDepthCheck = false;
                 HlmsMacroblock *finalBlock = manager->getMacroblock( myRef );
                 //myRef.mRsData == finalBlock.mRsData not necessarily true
+            @endcode
+        @endparblock
         @return
             Created or cached datablock with same parameters as baseParams
         */

OgreMain/include/OgreItem.h

@@ -108,7 +108,7 @@ namespace Ogre
         SubItemVec                    mSubItems;
 
         /** A set of all the entities which shares a single OldSkeletonInstance.
-            This is only created if the Item is in fact sharing it's OldSkeletonInstance with
+            This is only created if the Item is in fact sharing its OldSkeletonInstance with
             other Entities.
         */
         // ItemSet* mSharedSkeletonEntities;
@@ -209,7 +209,7 @@ namespace Ogre
         /// Stops sharing the SkeletonInstance with other Items. @see useSkeletonInstanceFrom
         void stopUsingSkeletonInstanceFromMaster();
 
-        /** Returns whether this Item shares it's SkeltonInstance with other Item instances.
+        /** Returns whether this Item shares its SkeltonInstance with other Item instances.
          */
         bool sharesSkeletonInstance() const;
 
@@ -242,7 +242,7 @@ namespace Ogre
         // bool hasVertexAnimation() const;
 
         /** Returns a pointer to the set of entities which share a OldSkeletonInstance.
-            If this instance does not share it's OldSkeletonInstance with other instances @c NULL will be
+            If this instance does not share its OldSkeletonInstance with other instances @c NULL will be
            returned
         */
         // const ItemSet* getSkeletonInstanceSharingSet() const    { return mSharedSkeletonEntities; }
@@ -264,7 +264,7 @@ namespace Ogre
             resources it references have been earmarked for background loading,
             so you should check isInitialised afterwards to see if it was successful.
         @param forceReinitialise
-            If @c true, this forces the Item to tear down it's
+            If @c true, this forces the Item to tear down its
             internal structures and try to rebuild them. Useful if you changed the
             content of a Mesh or Skeleton at runtime.
         */
@@ -278,7 +278,7 @@ namespace Ogre
         void _notifyParentNodeMemoryChanged() override;
     };
 
-    /** FItemy object for creating Item instances */
+    /** Factory object for creating Item instances */
     class _OgreExport ItemFactory final : public MovableObjectFactory
     {
     protected:

OgreMain/include/OgreLight.h

@@ -60,13 +60,6 @@ namespace Ogre
         and direction.
         Light::setDirection and Light::getDirection will redirect to the SceneNode and assert
         or crash if not attached to one.
-    @par
-        Remember also that dynamic lights rely on modifying the colour of vertices based on the position
-    of the light compared to an object's vertex normals. Dynamic lighting will only look good if the
-        object being lit has a fair level of tessellation and the normals are properly set. This is
-    particularly true for the spotlight which will only look right on highly tessellated models. In the
-    future OGRE may be extended for certain scene types so an alternative to the standard dynamic
-    lighting may be used, such as dynamic lightmaps.
     */
     class _OgreExport Light : public MovableObject, public TextureGpuListener
     {
@@ -184,14 +177,19 @@ namespace Ogre
          */
         const ColourValue &getSpecularColour() const { return mSpecular; }
 
-        /** Sets the attenuation parameters (range, constant, linear & quadratic, @see setAttenuation)
+        /** Sets the attenuation parameters (range, constant, linear & quadratic, see #setAttenuation)
             based on a given radius.
         @remarks
-            The actual attenuation formula is:
-                            1
-            --------------------------------
-            (distance / radius)² * 0.5 + 0.5
-
+            The actual attenuation formula is:<br/>
+            <table style="text-align: center;">
+              <tr>
+                <td style="border-bottom: 1px solid black;">1</td>
+              </tr>
+              <tr>
+                <td>(distance / radius)<sup>2</sup> * 0.5 + 0.5</td>
+              </tr>
+            </table>
+        @remarks
             The original formula never ends, that is the range is infinity. This function calculates
             a range based on "lumThreshold": When the luminosity past certain distance is below the
             established threshold, the light calculations are cut.
@@ -414,7 +412,6 @@ namespace Ogre
         */
         Vector4 getAs4DVector() const;
 
-
         /// @copydoc AnimableObject::createAnimableValue
         AnimableValuePtr createAnimableValue( const String &valueName ) override;
 
@@ -427,7 +424,7 @@ namespace Ogre
             This method allows you to set the distance at which shadows will no
             longer be rendered.
         @note
-            Each shadow technique can interpret this subtely differently.
+            Each shadow technique can interpret this subtly differently.
             For example, one technique may use this to eliminate casters,
             another might use it to attenuate the shadows themselves.
             You should tweak this value to suit your chosen shadow technique
@@ -455,7 +452,7 @@ namespace Ogre
         /** Get the near clip plane distance to be used by the shadow camera, if
             this light casts texture shadows.
         @remarks
-            May be zero if the light doesn't have it's own near distance set;
+            May be zero if the light doesn't have its own near distance set;
             use _deriveShadowNearDistance for a version guaranteed to give a result.
         */
         Real getShadowNearClipDistance() const { return mShadowNearClipDist; }
@@ -479,7 +476,7 @@ namespace Ogre
         /** Get the far clip plane distance to be used by the shadow camera, if
             this light casts texture shadows.
         @remarks
-            May be zero if the light doesn't have it's own far distance set;
+            May be zero if the light doesn't have its own far distance set;
             use _deriveShadowfarDistance for a version guaranteed to give a result.
         */
         Real getShadowFarClipDistance() const { return mShadowFarClipDist; }
@@ -551,7 +548,7 @@ namespace Ogre
             information only this Light knows.
         @remarks
             This method allows a Light to map in a custom GPU program parameter
-            based on it's own data. This is represented by a GPU auto parameter
+            based on its own data. This is represented by a GPU auto parameter
             of ACT_LIGHT_CUSTOM, and to allow there to be more than one of these per
             Light, the 'data' field on the auto parameter will identify
             which parameter is being updated and on which light. The implementation