Add method doc to Scene.RemoveClient() to ask any callers to use Scene.IncomingCloseAgent() instead.

IncomingCloseAgent() now sets the scene presence state machine properly, which is necessary to avoid races between multiple sources of close.
Hence, it's also necessary for everyone to consistently call IncomingCloseAgent()
Calling RemoveClient() directly is currently generating an attention-grabbing exception though this right now this is harmless.

OpenSim/Region/Framework/Scenes/Scene.cs

@@ -3382,6 +3382,18 @@ namespace OpenSim.Region.Framework.Scenes
             }
         }
 
+        /// <summary>
+        /// Remove the given client from the scene. 
+        /// </summary>
+        /// <remarks>
+        /// Only clientstack code should call this directly.  All other code should call IncomingCloseAgent() instead
+        /// to properly operate the state machine and avoid race conditions with other close requests (such as directly
+        /// from viewers).
+        /// </remarks>
+        /// <param name='agentID'>ID of agent to close</param>
+        /// <param name='closeChildAgents'>
+        /// Close the neighbour child agents associated with this client.
+        /// </param>
         public override void RemoveClient(UUID agentID, bool closeChildAgents)
         {
             AgentCircuitData acd = m_authenticateHandler.GetAgentCircuitData(agentID);

OpenSim/Region/Framework/Scenes/SceneBase.cs

@@ -217,6 +217,19 @@ namespace OpenSim.Region.Framework.Scenes
         #region Add/Remove Agent/Avatar
 
         public abstract ISceneAgent AddNewClient(IClientAPI client, PresenceType type);
+
+        /// <summary>
+        /// Remove the given client from the scene. 
+        /// </summary>
+        /// <remarks>
+        /// Only clientstack code should call this directly.  All other code should call IncomingCloseAgent() instead
+        /// to properly operate the state machine and avoid race conditions with other close requests (such as directly
+        /// from viewers).
+        /// </remarks>
+        /// <param name='agentID'>ID of agent to close</param>
+        /// <param name='closeChildAgents'>
+        /// Close the neighbour child agents associated with this client.
+        /// </param>
         public abstract void RemoveClient(UUID agentID, bool closeChildAgents);
 
         public bool TryGetScenePresence(UUID agentID, out object scenePresence)