Merge branch 'master' of melanie@opensimulator.org:/var/git/opensim

4 files changed, 57 insertions, 17 deletions

diff --git a/OpenSim/Region/Framework/Interfaces/IWorldComm.cs b/OpenSim/Region/Framework/Interfaces/IWorldComm.cs
index 74526c4..948b9dc 100644
--- a/OpenSim/Region/Framework/Interfaces/IWorldComm.cs
+++ b/OpenSim/Region/Framework/Interfaces/IWorldComm.cs
@@ -49,10 +49,49 @@ namespace OpenSim.Region.Framework.Interfaces
 
     public interface IWorldComm
     {
+        /// <summary>
+        /// Create a listen event callback with the specified filters.
+        /// The parameters localID,itemID are needed to uniquely identify
+        /// the script during 'peek' time. Parameter hostID is needed to
+        /// determine the position of the script.
+        /// </summary>
+        /// <param name="localID">localID of the script engine</param>
+        /// <param name="itemID">UUID of the script engine</param>
+        /// <param name="hostID">UUID of the SceneObjectPart</param>
+        /// <param name="channel">channel to listen on</param>
+        /// <param name="name">name to filter on</param>
+        /// <param name="id">key to filter on (user given, could be totally faked)</param>
+        /// <param name="msg">msg to filter on</param>
+        /// <returns>number of the scripts handle</returns>        
         int Listen(uint LocalID, UUID itemID, UUID hostID, int channel, string name, UUID id, string msg);
+
+        /// <summary>
+        /// This method scans over the objects which registered an interest in listen callbacks.
+        /// For everyone it finds, it checks if it fits the given filter. If it does,  then
+        /// enqueue the message for delivery to the objects listen event handler.
+        /// The enqueued ListenerInfo no longer has filter values, but the actually trigged values.
+        /// Objects that do an llSay have their messages delivered here and for nearby avatars,
+        /// the OnChatFromClient event is used.
+        /// </summary>
+        /// <param name="type">type of delvery (whisper,say,shout or regionwide)</param>
+        /// <param name="channel">channel to sent on</param>
+        /// <param name="name">name of sender (object or avatar)</param>
+        /// <param name="id">key of sender (object or avatar)</param>
+        /// <param name="msg">msg to sent</param>        
         void DeliverMessage(ChatTypeEnum type, int channel, string name, UUID id, string msg);
+
+        /// <summary>
+        /// Are there any listen events ready to be dispatched?
+        /// </summary>
+        /// <returns>boolean indication</returns>        
         bool HasMessages();
+
+        /// <summary>
+        /// Pop the first availlable listen event from the queue
+        /// </summary>
+        /// <returns>ListenerInfo with filter filled in</returns>        
         IWorldCommListenerInfo GetNextMessage();
+        
         void ListenControl(UUID itemID, int handle, int active);
         void ListenRemove(UUID itemID, int handle);
         void DeleteListener(UUID itemID);
diff --git a/OpenSim/Region/Framework/Scenes/EventManager.cs b/OpenSim/Region/Framework/Scenes/EventManager.cs
index 464ead8..a4a1abc 100644
--- a/OpenSim/Region/Framework/Scenes/EventManager.cs
+++ b/OpenSim/Region/Framework/Scenes/EventManager.cs
@@ -92,8 +92,7 @@ namespace OpenSim.Region.Framework.Scenes
         public delegate void OnShutdownDelegate();
 
         public event OnShutdownDelegate OnShutdown;
-
-        public delegate void ObjectGrabDelegate(uint localID, uint originalID, Vector3 offsetPos, IClientAPI remoteClient, SurfaceTouchEventArgs surfaceArgs);
+        
         public delegate void ObjectDeGrabDelegate(uint localID, uint originalID, IClientAPI remoteClient, SurfaceTouchEventArgs surfaceArgs);
         public delegate void ScriptResetDelegate(uint localID, UUID itemID);
 
@@ -103,7 +102,14 @@ namespace OpenSim.Region.Framework.Scenes
 
         public event OnSetRootAgentSceneDelegate OnSetRootAgentScene;
 
+        /// <summary>
+        /// Called when an object is touched/grabbed.
+        /// </summary>
+        /// The originalID is the local ID of the part that was actually touched.  The localID itself is always that of
+        /// the root part.
+        public delegate void ObjectGrabDelegate(uint localID, uint originalID, Vector3 offsetPos, IClientAPI remoteClient, SurfaceTouchEventArgs surfaceArgs);
         public event ObjectGrabDelegate OnObjectGrab;
+        
         public event ObjectGrabDelegate OnObjectGrabbing;
         public event ObjectDeGrabDelegate OnObjectDeGrab;
         public event ScriptResetDelegate OnScriptReset;
@@ -111,55 +117,42 @@ namespace OpenSim.Region.Framework.Scenes
         public event OnPermissionErrorDelegate OnPermissionError;
 
         public delegate void NewRezScript(uint localID, UUID itemID, string script, int startParam, bool postOnRez, string engine, int stateSource);
-
         public event NewRezScript OnRezScript;
 
         public delegate void RemoveScript(uint localID, UUID itemID);
-
         public event RemoveScript OnRemoveScript;
 
         public delegate void StartScript(uint localID, UUID itemID);
-
         public event StartScript OnStartScript;
 
         public delegate void StopScript(uint localID, UUID itemID);
-
         public event StopScript OnStopScript;
 
         public delegate bool SceneGroupMoved(UUID groupID, Vector3 delta);
-
         public event SceneGroupMoved OnSceneGroupMove;
 
         public delegate void SceneGroupGrabed(UUID groupID, Vector3 offset, UUID userID);
-
         public event SceneGroupGrabed OnSceneGroupGrab;
 
         public delegate bool SceneGroupSpinStarted(UUID groupID);
-
         public event SceneGroupSpinStarted OnSceneGroupSpinStart;
 
         public delegate bool SceneGroupSpun(UUID groupID, Quaternion rotation);
-
         public event SceneGroupSpun OnSceneGroupSpin;
 
         public delegate void LandObjectAdded(ILandObject newParcel);
-
         public event LandObjectAdded OnLandObjectAdded;
 
         public delegate void LandObjectRemoved(UUID globalID);
-
         public event LandObjectRemoved OnLandObjectRemoved;
 
         public delegate void AvatarEnteringNewParcel(ScenePresence avatar, int localLandID, UUID regionID);
-
         public event AvatarEnteringNewParcel OnAvatarEnteringNewParcel;
 
         public delegate void SignificantClientMovement(IClientAPI remote_client);
-
         public event SignificantClientMovement OnSignificantClientMovement;
 
         public delegate void IncomingInstantMessage(GridInstantMessage message);
-
         public event IncomingInstantMessage OnIncomingInstantMessage;
 
         public event IncomingInstantMessage OnUnhandledInstantMessage;
diff --git a/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs b/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
index ec41ac7..8c56870 100644
--- a/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneObjectGroup.cs
@@ -235,6 +235,9 @@ namespace OpenSim.Region.Framework.Scenes
             set { m_rootPart.GroupID = value; }
         }
 
+        /// <value>
+        /// The parts of this scene object group.  You must lock this property before using it.
+        /// </value>
         public Dictionary<UUID, SceneObjectPart> Children
         {
             get { return m_parts; }
@@ -2097,7 +2100,7 @@ namespace OpenSim.Region.Framework.Scenes
         }
 
         /// <summary>
-        /// Get a child part with a given UUID
+        /// Get a part with a given UUID
         /// </summary>
         /// <param name="primID"></param>
         /// <returns>null if a child part with the primID was not found</returns>
@@ -2112,7 +2115,7 @@ namespace OpenSim.Region.Framework.Scenes
         }
 
         /// <summary>
-        /// Get a child part with a given local ID
+        /// Get a part with a given local ID
         /// </summary>
         /// <param name="localID"></param>
         /// <returns>null if a child part with the local ID was not found</returns>
diff --git a/OpenSim/Region/Framework/Scenes/SceneObjectPart.cs b/OpenSim/Region/Framework/Scenes/SceneObjectPart.cs
index b1c6fb9..61ba4da 100644
--- a/OpenSim/Region/Framework/Scenes/SceneObjectPart.cs
+++ b/OpenSim/Region/Framework/Scenes/SceneObjectPart.cs
@@ -3178,6 +3178,11 @@ namespace OpenSim.Region.Framework.Scenes
             }
         }
 
+        /// <summary>
+        /// Set the events that this part will pass on to listeners.
+        /// </summary>
+        /// <param name="scriptid"></param>
+        /// <param name="events"></param>
         public void SetScriptEvents(UUID scriptid, int events)
         {
             // scriptEvents oldparts;