Improve documentation

src/CoroutineBase.cs

@@ -24,7 +24,6 @@ public class CoroutineBase
 
     private bool hasCalledStart = false;
     private bool wasReceivingUpdatesBeforePause = false;
-
 
     /// <summary>
     /// Determines whether the Update() method is called during process frames or physics frames.
@@ -35,7 +34,15 @@ public class CoroutineBase
     /// Determines the pause behaviour of this coroutine.
     /// </summary>
     public CoRunMode RunMode { get; private set; }
+
+    // The ProcessMode and RunMode fields should be treated as readonly, as they are not and should not be changed
+    // after construction of the coroutine. They are not declared as readonly, as the `Inherit` mode has to be
+    // translated into an actual mode, which is only known when the coroutine is added to the hierarchy, not when
+    // the constructor is called.
 
+    /// <summary>
+    /// Event that is fired when this coroutine is killed (stops).
+    /// </summary>
     public event Action Stopped;
 
     public void StartCoroutine(CoroutineBase coroutine)
@@ -97,6 +104,9 @@ protected virtual void OnExit() { }
 
     // Coroutine execution events:
 
+    /// <summary>
+    /// Called after OnEnter() if the coroutine is running or as soon as it is unpaused.
+    /// </summary>
     protected virtual void OnStart() { }
 
     /// <summary>
@@ -123,6 +133,7 @@ protected virtual void OnResume()
 
     /// <summary>
     /// Called every frame if the coroutine is playing.
+    /// The ProcessMode determines whether it is run in _Process() or _PhysicsProcess().
     /// </summary>
     public virtual void Update() { }
 
@@ -152,6 +163,9 @@ protected void DisableUpdates()
         Manager.DeactivateCoroutine(this);
     }
 
+    /// <summary>
+    /// Called when one of the child coroutines stops / finishes.
+    /// </summary>
     protected virtual void OnChildStopped(CoroutineBase child)
     {
         // If the parent coroutine is dead, then there is no reason to
@@ -246,13 +260,13 @@ private void RemoveChild(CoroutineBase coroutine)
     public void OnGamePausedChanged(bool isGamePaused)
     {
         UpdateRunState(isGamePaused);
-        UpdateChildrenAboutPausedChanged(isGamePaused);
+        NotifyChildrenAboutPausedChanged(isGamePaused);
     }
 
     /// <summary>
     /// Informs the child coroutines that the game has been paused / unpaused.
     /// </summary>
-    private void UpdateChildrenAboutPausedChanged(bool isGamePaused)
+    private void NotifyChildrenAboutPausedChanged(bool isGamePaused)
     {
         CoroutineBase child = firstChild;
         while (child != null)

src/CoroutineManager.cs

@@ -21,6 +21,9 @@ public partial class CoroutineManager : Node
     private DeferredHashSet<CoroutineBase> activePhysicsProcessCoroutines = new();
     private HashSet<CoroutineBase> aliveRootCoroutines = new();
 
+    /// <summary>
+    /// Starts and initializes the given coroutine.
+    /// </summary>
     public void StartCoroutine(CoroutineBase coroutine)
     {
         coroutine.Manager = this;
@@ -29,11 +32,17 @@ public void StartCoroutine(CoroutineBase coroutine)
         aliveRootCoroutines.Add(coroutine);
     }
 
+    /// <summary>
+    /// Enables Update() calls to the coroutine.
+    /// </summary>
     public void ActivateCoroutine(CoroutineBase coroutine)
     {
         GetUpdatePoolOfCoroutine(coroutine).Add(coroutine);
     }
 
+    /// <summary>
+    /// Disables Update() calls to the coroutine.
+    /// </summary>
     public void DeactivateCoroutine(CoroutineBase coroutine)
     {
         GetUpdatePoolOfCoroutine(coroutine).Remove(coroutine);

src/Coroutines/AwaitCoroutine.cs

@@ -5,7 +5,8 @@ namespace HCoroutines;
 /// <summary>
 /// A coroutine that waits until an asynchronous task has been completed.
 /// If the coroutine is killed before completion, the async task
-/// will currently *not* be canceled.
+/// will currently *not* be canceled. The execution of the async task is
+/// also *not* affected by the pause mode.
 /// </summary>
 public class AwaitCoroutine<T> : CoroutineBase
 {