0.0.2-preview.1 - 2019/01/28

@2018.1
ErikMoczi · Feb 6, 2019 · 0db484a · 0db484a
1 parent 2684295
commit 0db484a
Show file tree

Hide file tree

Showing 9 changed files with 210 additions and 21 deletions.
diff --git a/package/CHANGELOG.md b/package/CHANGELOG.md
@@ -3,6 +3,9 @@ All notable changes to this package will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
+## [0.0.2-preview.1] - 2019-01-25
+### Changed
+ - Fixed a compilation issue caused by using the 'default' literal.
 
 ## [0.0.1-preview.5] - 2019-01-14
 ### Changed

diff --git a/package/Documentation~/TableOfContents.md b/package/Documentation~/TableOfContents.md
@@ -1,5 +1,3 @@
 # Unity Editor Coroutines
 
-* [Editor Coroutines overview](index)
-* [Code examples](examples)
-* [API](api)
+* [Editor Coroutines overview](index)
diff --git a/package/Documentation~/manual.md b/package/Documentation~/manual.md
@@ -1,5 +1,3 @@
 # Unity Editor Coroutines manual
 
-- [Editor Coroutines overview](index.md)
-- [Code examples](examples.md)
-- [API](api.md)
+- [Editor Coroutines overview](index.md)
diff --git a/package/Editor/EditorCoroutine.cs b/package/Editor/EditorCoroutine.cs
@@ -7,7 +7,7 @@
 namespace Unity.EditorCoroutines.Editor
 {
     /// <summary>
-    /// Instances of the EditorCoroutine class do not expose properties or functions, their sole purpose is to reference the ongoing coroutine process.
+    /// A handle to an EditorCoroutine, can be passed to <see cref="EditorCoroutineUtility">EditorCoroutineUtility</see> methods to control lifetime.
     /// </summary>
     public class EditorCoroutine
     {
@@ -75,14 +75,14 @@ public bool MoveNext(IEnumerator enumerator)
 
                 if(advance)
                 {
-                    data = default; 
+                    data = default(ProcessorData); 
                     return enumerator.MoveNext();
                 }
                 return true;
             }
         }
 
-        WeakReference m_Owner;
+        internal WeakReference m_Owner;
         IEnumerator m_Routine;
         YieldProcessor m_Processor;
 

diff --git a/package/Editor/EditorCoroutineUtility.cs b/package/Editor/EditorCoroutineUtility.cs
@@ -1,36 +1,121 @@
 using System.Collections;
+using UnityEngine;
 
 namespace Unity.EditorCoroutines.Editor
 {
     public static class EditorCoroutineUtility
     {
         /// <summary>
-        /// Starts an editor coroutine, with the specified owner object. If the owner expires while the coroutine is still executing, execution will stop.
+        /// Starts an <see cref ="EditorCoroutine">EditorCoroutine</see> with the specified owner object. 
+        /// If the garbage collector collects the owner object, while the resulting coroutine is still executing, the coroutine will stop running.
+        /// <code>
+        /// using System.Collections;
+        /// using Unity.EditorCoroutines.Editor;
+        /// using UnityEditor;
+        ///
+        /// public class ExampleWindow : EditorWindow
+        /// {
+        ///     int m_Updates = 0;
+        ///     void OnEnable()
+        ///     {
+        ///         EditorCoroutineUtility.StartCoroutine(CountEditorUpdates(), this);
+        ///     }
+        ///
+        ///     IEnumerator CountEditorUpdates()
+        ///     {
+        ///         while (true)
+        ///         {
+        ///             ++m_Updates;
+        ///             yield return null;
+        ///         }
+        ///     }
+        /// }
+        /// </code>
         /// </summary>
         /// <param name="routine"> IEnumerator to iterate over. </param>
         /// <param name="owner">Object owning the coroutine. </param>
-        /// <returns></returns>
+        /// <remarks>
+        /// Only types that don't inherit from <see cref="UnityEngine.Object">UnityEngine.Object</see> will get collected the next time the GC runs instead of getting null-ed immediately.
+        /// </remarks>
+        /// <returns>A handle to an <see cref="EditorCoroutine">EditorCoroutine</see>.</returns>
         public static EditorCoroutine StartCoroutine(IEnumerator routine, object owner)
         {
             return new EditorCoroutine(routine, owner);
         }
 
         /// <summary>
-        /// Starts an editor coroutine, without a owning object. The editor coroutine will execute until it is done or otherwise canceled.
+        /// This method starts an <see cref="EditorCoroutine">EditorCoroutine</see> without an owning object. The <see cref="EditorCoroutine">EditorCoroutine</see> runs until it completes or is canceled using <see cref="StopCoroutine(EditorCoroutine)">StopCoroutine</see>.
+        /// <code>
+        /// using System.Collections;
+        /// using Unity.EditorCoroutines.Editor;
+        /// using UnityEditor;
+        /// using UnityEngine;
+        ///
+        /// public class ExampleWindow : EditorWindow
+        /// {
+        ///     void OnEnable()
+        ///     {
+        ///         EditorCoroutineUtility.StartCoroutineOwnerless(LogTimeSinceStartup());
+        ///     }
+        ///
+        ///     IEnumerator LogTimeSinceStartup()
+        ///     {
+        ///         while (true)
+        ///         {
+        ///             Debug.LogFormat("Time since startup: {0} s", Time.realtimeSinceStartup);
+        ///             yield return null;
+        ///         }
+        ///     }
+        /// }
+        /// </code>
         /// </summary>
-        /// <param name="routine"> IEnumerator to iterate over. </param>
-        /// <returns></returns>
+        /// <param name="routine"> Generator function to execute. </param>
+        /// <returns>A handle to an <see cref="EditorCoroutine">EditorCoroutine.</see></returns>
         public static EditorCoroutine StartCoroutineOwnerless(IEnumerator routine)
         {
             return new EditorCoroutine(routine);
         }
 
         /// <summary>
-        /// Stops an editor coroutine.
+        /// Immediately stop an <see cref="EditorCoroutine">EditorCoroutine</see>. This method is safe to call on an already completed <see cref="EditorCoroutine">EditorCoroutine</see>.
+        /// <code>
+        /// using System.Collections;
+        /// using Unity.EditorCoroutines.Editor;
+        /// using UnityEditor;
+        /// using UnityEngine;
+        ///
+        /// public class ExampleWindow : EditorWindow
+        /// {
+        ///     EditorCoroutine m_LoggerCoroutine;
+        ///     void OnEnable()
+        ///     {
+        ///         m_LoggerCoroutine = EditorCoroutineUtility.StartCoroutineOwnerless(LogRunning());
+        ///     }
+        ///     
+        ///     void OnDisable()
+        ///     {
+        ///         EditorCoroutineUtility.StopCoroutine(m_LoggerCoroutine);
+        ///     }
+        ///
+        ///     IEnumerator LogRunning()
+        ///     {
+        ///         while (true)
+        ///         {
+        ///             Debug.Log("Running");
+        ///             yield return null;
+        ///         }
+        ///     }
+        /// }
+        /// </code>
         /// </summary>
-        /// <param name="coroutine"></param>
+        /// <param name="coroutine">A handle to an <see cref="EditorCoroutine">EditorCoroutine.</see></param>
         public static void StopCoroutine(EditorCoroutine coroutine)
         {
+            if (coroutine == null)
+            {
+                Debug.LogAssertion("EditorCoroutine handle is null.");
+                return;
+            }
             coroutine.Stop();
         }
     }

diff --git a/package/Editor/EditorWaitForSeconds.cs b/package/Editor/EditorWaitForSeconds.cs
@@ -1,12 +1,40 @@
 namespace Unity.EditorCoroutines.Editor
 {
     /// <summary>
-    /// Suspends the editor coroutine execution for the given amount of seconds using unscaled time.
+    /// Suspends the <see cref="EditorCoroutine">EditorCoroutine</see> execution for the given amount of seconds, using unscaled time. 
+    /// The coroutine execution continues after the specified time has elapsed.
+    /// <code>
+    /// using System.Collections;
+    /// using UnityEngine;
+    /// using Unity.EditorCoroutines.Editor;
+    /// using UnityEditor;
+    ///
+    /// public class MyEditorWindow : EditorWindow
+    /// {
+    ///     IEnumerator PrintEachSecond()
+    ///     {
+    ///         var waitForOneSecond = new EditorWaitForSeconds(1.0f);
+    ///
+    ///         while (true)
+    ///         {
+    ///             yield return waitForOneSecond;
+    ///             Debug.Log("Printing each second");
+    ///         }
+    ///     }
+    /// }
+    /// </code>
     /// </summary>
     public class EditorWaitForSeconds
     {
+        /// <summary>
+        /// The time to wait in seconds.
+        /// </summary>
         public double WaitTime { get; }
 
+        /// <summary>
+        /// Creates a instruction object for yielding inside a generator function.
+        /// </summary>
+        /// <param name="time">The amount of time to wait in seconds.</param>
         public EditorWaitForSeconds(float time)
         {
             WaitTime = time;

diff --git a/package/Editor/EditorWindowCoroutineExtension.cs b/package/Editor/EditorWindowCoroutineExtension.cs
@@ -1,12 +1,36 @@
 using System.Collections;
 using UnityEditor;
+using UnityEngine;
 
 namespace Unity.EditorCoroutines.Editor
 {
     public static class EditorWindowCoroutineExtension
     {
         /// <summary>
-        /// Start an editor coroutine, owned by the calling EditorWindow object.
+        /// Start an <see cref="EditorCoroutine">EditorCoroutine</see>, owned by the calling <see cref="EditorWindow">EditorWindow</see> instance.
+        /// <code> 
+        /// using System.Collections;
+        /// using Unity.EditorCoroutines.Editor;
+        /// using UnityEditor;
+        ///
+        /// public class ExampleWindow : EditorWindow
+        /// {
+        ///     void OnEnable()
+        ///     {
+        ///         this.StartCoroutine(CloseWindowDelayed());
+        ///     }
+        ///
+        ///     IEnumerator CloseWindowDelayed() //close the window after 1000 frames have elapsed
+        ///     {
+        ///         int count = 1000;
+        ///         while (count > 0)
+        ///         {
+        ///             yield return null;
+        ///         }
+        ///         Close();
+        ///     }
+        /// }
+        /// </code>
         /// </summary>
         /// <param name="routine"></param>
         /// <returns></returns>
@@ -16,11 +40,63 @@ public static EditorCoroutine StartCoroutine(this EditorWindow window, IEnumerat
         }
 
         /// <summary>
-        /// Stop an editor coroutine.
+        /// Immediately stop an <see cref="EditorCoroutine">EditorCoroutine</see> that was started by the calling <see cref="EditorWindow"/> instance. This method is safe to call on an already completed <see cref="EditorCoroutine">EditorCoroutine</see>.
+        /// <code>
+        /// using System.Collections;
+        /// using Unity.EditorCoroutines.Editor;
+        /// using UnityEditor;
+        /// using UnityEngine;
+        ///
+        /// public class ExampleWindow : EditorWindow
+        /// {
+        ///     EditorCoroutine coroutine;
+        ///     void OnEnable()
+        ///     {
+        ///         coroutine = this.StartCoroutine(CloseWindowDelayed());
+        ///     }
+        ///
+        ///     private void OnDisable()
+        ///     {
+        ///         this.StopCoroutine(coroutine);
+        ///     }
+        ///
+        ///     IEnumerator CloseWindowDelayed()
+        ///     {
+        ///         while (true)
+        ///         {
+        ///             Debug.Log("Running");
+        ///             yield return null;
+        ///         }
+        ///     }
+        /// }
+        /// </code>
         /// </summary>
         /// <param name="coroutine"></param>
         public static void StopCoroutine(this EditorWindow window, EditorCoroutine coroutine)
         {
+            if(coroutine == null)
+            {
+                Debug.LogAssertion("Provided EditorCoroutine handle is null.");
+                return;
+            }
+
+            if(coroutine.m_Owner == null)
+            {
+                Debug.LogError("The EditorCoroutine is ownerless. Please use EditorCoroutineEditor.StopCoroutine to terminate such coroutines.");
+                return;
+            }
+
+            if (!coroutine.m_Owner.IsAlive)
+                return; //The EditorCoroutine's owner was already terminated execution will cease next time it is processed
+
+            var owner = coroutine.m_Owner.Target as EditorWindow;
+
+            if (owner == null || owner != null && owner != window)
+            {
+                Debug.LogErrorFormat("The EditorCoroutine is owned by another object: {0}.", coroutine.m_Owner.Target);
+                return;
+            }
+
             EditorCoroutineUtility.StopCoroutine(coroutine);
         }
     }

diff --git a/package/package.json b/package/package.json
@@ -1,7 +1,7 @@
 {
   "name": "com.unity.editorcoroutines",
   "displayName": "Editor Coroutines",
-  "version": "0.0.1-preview.5",
+  "version": "0.0.2-preview.1",
   "unity": "2018.1",
   "description": "The editor coroutines package allows developers to start constructs similar to Unity's monobehaviour based coroutines within the editor using abitrary objects. ",
   "keywords": [
@@ -13,6 +13,6 @@
   "repository": {
     "type": "git",
     "url": "https://gitlab.cds.internal.unity3d.com/upm-packages/core/com.unity.editorcoroutines.git",
-    "revision": "e63fe73ea0c1fa3fc715ae99e6def079c057e1fe"
+    "revision": "6e18db566e559d8bb9f12deea2325c4117a3e7d9"
   }
 }
diff --git a/versions.txt b/versions.txt
@@ -3,3 +3,4 @@
 0.0.1-preview.3
 0.0.1-preview.4
 0.0.1-preview.5
+0.0.2-preview.1