code comments for Scheduler and ComponentLink

yew/src/html/scope.rs

@@ -162,7 +162,11 @@ impl<COMP: Component> Scope<COMP> {
         scheduler().push_comp(ComponentRunnableType::Destroy, Box::new(destroy));
     }
 
-    /// Send a message to the component
+    /// Send a message to the component.
+    ///
+    /// Please be aware that currently this method
+    /// immediately/synchronously schedules a call to the
+    /// [Component](Component) interface. 
     pub fn send_message<T>(&self, msg: T)
     where
         T: Into<COMP::Message>,
@@ -172,14 +176,23 @@ impl<COMP: Component> Scope<COMP> {
 
     /// Send a batch of messages to the component.
     ///
-    /// This is useful for reducing re-renders of the components because the messages are handled
-    /// together and the view function is called only once if needed.
+    /// This is useful for reducing re-renders of the components
+    /// because the messages are handled together and the view
+    /// function is called only once if needed.
+    ///
+    /// Please be aware that currently this method
+    /// immediately/synchronously schedules calls to the
+    /// [Component](Component) interface.
     pub fn send_message_batch(&self, messages: Vec<COMP::Message>) {
         self.update(ComponentUpdate::MessageBatch(messages), false);
     }
 
-    /// Creates a `Callback` which will send a message to the linked component's
-    /// update method when invoked.
+    /// Creates a `Callback` which will send a message to the linked
+    /// component's update method when invoked.
+    ///
+    /// Please be aware that currently the result of this callback
+    /// immediately/synchronously schedules a call to the
+    /// [Component](Component) interface. 
     pub fn callback<F, IN, M>(&self, function: F) -> Callback<IN>
     where
         M: Into<COMP::Message>,
@@ -193,8 +206,12 @@ impl<COMP: Component> Scope<COMP> {
         closure.into()
     }
 
-    /// Creates a `Callback` from a FnOnce which will send a message to the linked
-    /// component's update method when invoked.
+    /// Creates a `Callback` from a FnOnce which will send a message
+    /// to the linked component's update method when invoked.
+    ///
+    /// Please be aware that currently the result of this callback
+    /// will immediately/synchronously schedule calls to the
+    /// [Component](Component) interface. 
     pub fn callback_once<F, IN, M>(&self, function: F) -> Callback<IN>
     where
         M: Into<COMP::Message>,
@@ -208,8 +225,12 @@ impl<COMP: Component> Scope<COMP> {
         Callback::once(closure)
     }
 
-    /// Creates a `Callback` which will send a batch of messages back to the linked
-    /// component's update method when invoked.
+    /// Creates a `Callback` which will send a batch of messages back
+    /// to the linked component's update method when invoked.
+    ///
+    /// Please be aware that currently the results of these callbacks
+    /// will immediately/synchronously schedule calls to the
+    /// [Component](Component) interface. 
     pub fn batch_callback<F, IN>(&self, function: F) -> Callback<IN>
     where
         F: Fn(IN) -> Vec<COMP::Message> + 'static,
@@ -236,6 +257,8 @@ struct ComponentState<COMP: Component> {
 }
 
 impl<COMP: Component> ComponentState<COMP> {
+    /// Creates a new `ComponentState`, also invokes the `create()` 
+    /// method on component to create it.
     fn new(
         element: Element,
         ancestor: Option<VNode>,
@@ -255,6 +278,9 @@ impl<COMP: Component> ComponentState<COMP> {
     }
 }
 
+/// A `Runnable` task which calls the creates the `ComponentState` (if
+/// there is none) and invokes the `create()` method on a `Component`
+/// to create it.
 struct CreateComponent<COMP>
 where
     COMP: Component,
@@ -285,6 +311,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `update()` method on a `Component`.
 struct UpdateComponent<COMP>
 where
     COMP: Component,
@@ -334,6 +361,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `rendered()` method on a `Component`.
 struct RenderedComponent<COMP>
 where
     COMP: Component,
@@ -362,6 +390,7 @@ where
     }
 }
 
+/// A `Runnable` task which calls the `destroy()` method on a `Component`.
 struct DestroyComponent<COMP>
 where
     COMP: Component,

yew/src/scheduler.rs

@@ -24,6 +24,7 @@ pub(crate) trait Runnable {
 /// This is a global scheduler suitable to schedule and run any tasks.
 #[derive(Clone)]
 pub(crate) struct Scheduler {
+    /// This lock is used to prevent recursion in [Scheduler#start()](Scheduler#start())
     lock: Rc<RefCell<()>>,
     main: Shared<VecDeque<Box<dyn Runnable>>>,
     component: ComponentScheduler,
@@ -97,6 +98,10 @@ impl Scheduler {
     }
 
     pub(crate) fn start(&self) {
+        // The lock here is used to prevent recursion. It is assumed
+        // that if the lock here fails to acquire, it is because this
+        // `start()` method is being called recursively in a
+        // `runnable.run()`. 
         if let Ok(_lock) = self.lock.try_borrow_mut() {
             while let Some(runnable) = self.next_runnable() {
                 runnable.run();