#778 Added documentation. CityCursor.E renamed to Cursor.

It is no longer needed to select an object to zoom into it,
simply hovering will do. This is quicker and prevents to move
objects accidentally.

Assets/SEE/GameObjects/CityCursor.cs

@@ -7,24 +7,41 @@
 
 namespace SEE.GO
 {
+    /// <summary>
+    /// Cursor for a code city that captures the city's objects when they are hovered over.
+    /// It is really only a wrapper around a <see cref="Cursor3D"/> that is attached to the city.
+    ///
+    /// This class is assumed to be attached to a component holding an
+    /// <see cref="AbstractSEECity"/> component.
+    /// </summary>
     public class CityCursor : MonoBehaviour
     {
-        internal Cursor3D E { get; private set; }
+        /// <summary>
+        /// The cursor that is attached to this city.
+        /// </summary>
+        internal Cursor3D Cursor { get; private set; }
+
+        /// <summary>
+        /// The city this cursor is attached to.
+        /// </summary>
         private AbstractSEECity city;
 
+        /// <summary>
+        /// Initializes the <see cref="Cursor"/> and subscribes to the necessary hovering events.
+        /// </summary>
         private void Start()
         {
             if (TryGetComponent(out AbstractSEECity city))
             {
                 this.city = city;
 #if UNITY_EDITOR
-                E = Cursor3D.Create(city.name);
+                Cursor = Cursor3D.Create(city.name);
 #else
-                E = Cursor3D.Create();
+                Cursor = Cursor3D.Create();
 #endif
 
-                InteractableObject.AnySelectIn += AnySelectIn;
-                InteractableObject.AnySelectOut += AnySelectOut;
+                InteractableObject.AnyHoverIn += AnyHoverIn;
+                InteractableObject.AnyHoverOut += AnyHoverOut;
             }
             else
             {
@@ -33,29 +50,46 @@ private void Start()
             }
         }
 
+        /// <summary>
+        /// Unsubscribe from events when this object is destroyed
+        /// and destroys the <see cref="Cursor"/>.
+        /// </summary>
         private void OnDestroy()
         {
-            InteractableObject.AnySelectIn -= AnySelectIn;
-            InteractableObject.AnySelectOut -= AnySelectOut;
-
-            Destroyer.Destroy(E);
+            InteractableObject.AnyHoverIn  -= AnyHoverIn;
+            InteractableObject.AnyHoverOut -= AnyHoverOut;
+            Destroyer.Destroy(Cursor);
         }
 
-        private void AnySelectIn(InteractableObject interactableObject, bool isInitiator)
+        /// <summary>
+        /// Makes <paramref name="interactableObject"/> the <see cref="Cursor"/> focus when
+        /// it belongs to <see cref="city"/>.
+        /// Called whenever an <see cref="InteractableObject"/> is selected.
+        /// </summary>
+        /// <param name="interactableObject">the selected object</param>
+        /// <param name="isInitiator">currently ignored</param>
+        private void AnyHoverIn(InteractableObject interactableObject, bool isInitiator)
         {
             Graph selectedGraph = interactableObject.GraphElemRef.Elem.ItsGraph;
             if (selectedGraph.Equals(city.LoadedGraph))
             {
-                E.AddFocus(interactableObject);
+                Cursor.AddFocus(interactableObject);
             }
         }
 
-        private void AnySelectOut(InteractableObject interactableObject, bool isInitiator)
+        /// <summary>
+        /// Removes <paramref name="interactableObject"/> from the <see cref="Cursor"/> focus when
+        /// it belongs to <see cref="city"/>.
+        /// Called whenever an <see cref="InteractableObject"/> is unselected.
+        /// </summary>
+        /// <param name="interactableObject">the unselected object</param>
+        /// <param name="isInitiator">currently ignored</param>
+        private void AnyHoverOut(InteractableObject interactableObject, bool isInitiator)
         {
             Graph selectedGraph = interactableObject.GraphElemRef.Elem.ItsGraph;
             if (selectedGraph.Equals(city.LoadedGraph))
             {
-                E.RemoveFocus(interactableObject);
+                Cursor.RemoveFocus(interactableObject);
             }
         }
     }